merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 169 insertions, 0 deletions

diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst
new file mode 100644
index 0000000..9ffdd1d
--- /dev/null
+++ b/docs/source/lang/cpp/variables.rst
@@ -0,0 +1,169 @@
+.. highlight:: cpp
+
+.. _lang-variables:
+
+Variables
+=========
+
+A variable is a way of naming and storing a value for later use by
+the program, such as data from a sensor or an intermediate value
+used in a calculation.
+
+.. contents:: Contents
+   :local:
+
+.. _lang-variables-declaring:
+
+Declaring Variables
+-------------------
+
+Before they are used, all variables have to be *declared*. Declaring a
+variable means defining its type, giving it a name, and (optionally)
+giving it an initial value (this is often referred to as
+*initializing* the variable).  Variables do not have to be initialized
+(given a value) when they are declared, but it is good style to give
+them an initial value whenever possible.
+
+Here is an example of declaring a variable named ``inputVariable1``
+with type :ref:`int <lang-int>` (the ``int`` type is used to store
+integers, like -2, -1, 0, 1, etc.)::
+
+    int inputVariable1;
+
+In the above declaration, we did not give the variable an initial
+value.  Here is another example, where we declare an ``int`` variable
+named ``inputVariable2``, with an initial value of ``0``::
+
+    int inputVariable2 = 0;
+
+The Maple environment comes ready to use with many useful types of
+variables.  See the :ref:`built-in types <lang-built-in-types>` page
+for more information.
+
+Here are a few examples of declaring variables of different types::
+
+     int lightSensVal;
+     char currentLetter;
+     unsigned long long speedOfLight = 186000ULL;
+     char errorMessage = {"choose another option"}; // see string
+
+Naming Variables
+----------------
+
+The rules for naming a variable are simple.  Names for variables can
+contain letters, numbers, and underscores (the underscore is the
+:kbd:`_` character), and cannot begin with a number.  So
+``temperature_reading``, ``tempReading``, ``tempReading1``, and
+``tempReading2`` are all valid variable names, but ``4_temp_readings``
+is not, because it begins with a number.
+
+You cannot choose a name for a variable that is one of the C++
+:ref:`keywords <lang-keywords>`.
+
+Variable names are case-sensitive, so "tempreading" and "tempReading"
+are different variables.  However, it is very bad style to write code
+that chooses variables which are the same up to case.
+
+You should give your variables descriptive names, so as to make your
+code more readable. Variable names like ``tiltSensor`` or
+``pushButton`` help you (and anyone else reading your code) understand
+what the variable represents. Variable names like ``var`` or
+``value``, on the other hand, do little to make your code readable.
+
+.. _lang-variables-scope:
+
+Variable Scope
+--------------
+
+An important choice that programmers face is where (in the program
+text) to declare variables. The specific place that variables are
+declared influences how various functions in a program will "see" the
+variable.  This is called variable *scope*.  See the :ref:`scope
+reference <lang-scope>` for more information.
+
+.. _lang-variables-initializing:
+
+Initializing Variables
+----------------------
+
+Variables may be *initialized* (assigned a starting value) when they
+are declared or not. It is always good programming practice however to
+double check that a variable has valid data in it before it is used.
+Using a variable before you give it a value is a common source of
+bugs.
+
+.. _lang-variables-rollover:
+
+Variable Rollover
+-----------------
+
+Every (numeric) type has a valid *range*.  The range of a type is the
+smallest and largest value that a variable of that type can store.
+For example, the :ref:`int <lang-int>` type has a range of
+-2,147,483,648 to 2,147,483,647 [#frange]_.
+
+When variables are made to exceed their range's maximum value, they
+"roll over" back to their minimum value.  Note that this happens in
+both directions.  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::
+
+       int x;
+       x = -2,147,483,648;
+       x = x - 1; // x now contains -2,147,483,647; rolled over "left to right"
+
+       x = 2,147,483,647;
+       x = x + 1; // x now contains -2,147,483,648; rolled over "right to left"
+
+Each numeric type's reference page includes its range.  See the
+:ref:`built-in types <lang-built-in-types>` reference for links to each
+type's reference page.
+
+Using Variables
+---------------
+
+Once variables have been declared, they are given values using the
+:ref:`assignment operator <lang-assignment>`, which is a single equals
+sign, ``=``. The assignment operator tells the program to store the
+value on the right side of the equals sign into the variable on the
+left side::
+
+    inputVariable1 = 7;             // sets variable named inputVariable1 to 7
+    inputVariable2 = analogRead(2); // sets variable named inputVariable2 to
+                                    // the (digitized) input voltage read from
+                                    //  analog pin #2
+
+Once a variable has been set (assigned a value), you can test its
+value to see if it meets certain conditions, or you can use its value
+directly. For instance, the following code tests whether the
+inputVariable2 is less than 100, then sets a delay based on
+inputVariable2 (which, at that point, is at least 100)::
+
+    if (inputVariable2 < 100) {
+      inputVariable2 = 100;
+    }
+
+    delay(inputVariable2);
+
+See Also
+--------
+
+- :ref:`lang-scope`
+- :ref:`lang-built-in-types`
+
+.. rubric:: Footnotes
+
+.. [#frange] This range might seem a little weird at first.  The
+   reasons for this range of values have to do with the fact that an
+   ``int`` occupies 32 bits of memory, and the facts ::
+
+     2^31 = -2,147,483,648
+     2^31 - 1 = 2,147,483,647
+
+
+   Why 2^31 instead of 2^32?  Well, that has to do with `how ints are
+   (usually) stored
+   <http://en.wikipedia.org/wiki/Two%27s_complement>`_ on computers.
+
+.. include:: /arduino-cc-attribution.txt
+