arduino language reference nearing completion, properly CC-BY-SA 3.0 attributed

1 files changed, 44 insertions, 61 deletions

diff --git a/docs/source/arduino/int.rst b/docs/source/arduino/int.rst
index 2bb3bef..4bb876c 100644
--- a/docs/source/arduino/int.rst
+++ b/docs/source/arduino/int.rst
@@ -1,3 +1,5 @@
+.. highlight:: cpp
+
 .. _arduino-int:
 
 int
@@ -6,79 +8,60 @@ int
 Description
 -----------
 
-Integers are your primary datatype for number storage, and store a
-2 byte value. This yields a range of -32,768 to 32,767 (minimum
-value of -2^15 and a maximum value of (2^15) - 1).
-
-
-
-Int's store negative numbers with a technique called
-`2's complement math. <http://en.wikipedia.org/wiki/2's_complement>`_
-The highest bit, sometimes refered to as the "sign" bit, flags the
-number as a negative number. The rest of the bits are inverted and
-1 is added.
-
-
-
-The Arduino takes care of dealing with negative numbers for you, so
-that arithmetic operations work transparently in the expected
-manner. There can be an unexpected complication in dealing with the
-`bitshift right operator (>>) <http://arduino.cc/en/Reference/Bitshift>`_
-however.
-
-
-
-Example
--------
-
-::
+The ``int`` data type represents integers.  Integers are your primary
+data type for number storage, and store a 4 byte value. This yields a
+range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a
+maximum value of (2^31) - 1; that's about negative 2 billion to
+positive 2 billion).
 
-        int ledPin = 13;
+An ``int`` stores a negative number with a technique called `two's
+complement math
+<http://en.wikipedia.org/wiki/Two%27s_complement#Explanation>`_\ .
+The highest bit in an ``int``, sometimes refered to as the "sign" bit,
+flags the number as a negative number.  (See the linked article on
+two's complement for more information).
 
+The Maple takes care of dealing with negative numbers for you, so that
+arithmetic operations work mostly as you'd expect. There can be an
+:ref:`unexpected complication <arduino-bitshift-signbit-gotcha>` in
+dealing with the :ref:`bitshift right operator (>>)
+<arduino-bitshift>`, however.
 
+Here is an example of declaring an ``int`` variable named ``ledPin``,
+then giving it value 13::
 
-Syntax
-------
+    int ledPin = 13;
 
-::
+The general syntax for declaring an ``int`` variable named ``var``,
+then giving it value ``val``, looks like::
 
-        int var = val;
+    int var = val;
 
+.. _arduino-int-overflow:
 
+Integer Overflow
+----------------
 
+When ``int`` variables leave the range specified above, they "roll
+over" in the other direction.  It's like in the game *Pac-Man* -- when
+Pac-Man goes past the right edge of the screen, he reappears on the
+left, and when he goes past the left side of the screen, he reappears
+on the right.  Here are some examples::
 
--  var - your int variable name
--  val - the value you assign to that variable
-
-
-
-Coding Tip
-----------
-
-When variables are made to exceed their maximum capacity they "roll
-over" back to their minimum capacitiy, note that this happens in
-both directions.
-
-
-
-::
-
-       int x
-       x = -32,768;
-       x = x - 1;       // x now contains 32,767 - rolls over in neg. direction
-    
-       x = 32,767;
-       x = x + 1;       // x now contains -32,768 - rolls over
-
+       int x;
+       x = -2,147,483,648;
+       x--; // x now contains 2,147,483,647; rolled over "left to right"
 
+       x = 2,147,483,647;
+       x++; // x now contains -2,147,483,648; rolled over "right to left"
 
 See Also
 --------
 
-
--  `byte <http://arduino.cc/en/Reference/Byte>`_
--  `unsigned int <http://arduino.cc/en/Reference/UnsignedInt>`_
--  `long <http://arduino.cc/en/Reference/Long>`_
--  `unsigned long <http://arduino.cc/en/Reference/UnsignedLong>`_
--  `Integer Constants <http://arduino.cc/en/Reference/IntegerConstants>`_
--  `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_
+-  :ref:`unsigned int <arduino-unsignedint>`
+-  :ref:`char <arduino-char>`
+-  :ref:`unsigned char <arduino-unsignedchar>`
+-  :ref:`long <arduino-long>`
+-  :ref:`unsigned long <arduino-unsignedlong>`
+-  :ref:`Integer Constants <arduino-constants-integers>`
+-  :ref:`Variables <arduino-variables>`