current Maple documentation either rewritten or stubbed out in Sphinx

1 files changed, 80 insertions, 49 deletions

diff --git a/docs/source/language.rst b/docs/source/language.rst
index 6634f9d..7bf71c6 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -9,11 +9,17 @@
 The Maple can be programmed in the `Wiring
 <http://www.wiring.org.co/reference/>`_ language, which is the same
 language used to program the `Arduino <http://arduino.cc/>`_ boards.
-The entire language will be supported in a future release.  Please see
-the extensive `language reference
+Please see the extensive `language reference
 <http://arduino.cc/en/Reference/HomePage>`_ on the Arduino webpage for
 more information, or follow a direct link below.
 
+.. warning::
+
+   The Arduino boards have different sizes for data types, so don't
+   trust their documentation for how many bytes an ``int``, ``long``,
+   etc. take up.  The sizes of each data type on the Maple are given
+   in the :ref:`table below <language-arduino-docs>`.
+
 C or C++ programmers curious about the differences between the Wiring
 language and C++ may wish to skip to the
 :ref:`arduino_c_for_c_hackers`.
@@ -21,6 +27,8 @@ language and C++ may wish to skip to the
 Unique Maple Additions
 ----------------------
 
+.. _language-assert:
+
 ``ASSERT(...)``
     The ``ASSERT()`` function can be very useful for basic program
     debugging. The function accepts a boolean; for example::
@@ -46,6 +54,8 @@ Unique Maple Additions
     this will **not work in the IDE**; even with this definition,
     assertions will still be enabled.
 
+.. _language-arduino-docs:
+
 Arduino Documentation Links
 ---------------------------
 
@@ -70,73 +80,73 @@ Arduino Documentation Links
 |* `for`_                            |                                    |                                         |
 |                                    |**Data Types**                      |* `analogRead()`_                        |
 |* `switch/case`_                    |                                    |                                         |
-|                                    |* `void`_                           |* `analogWrite()`_ - PWM                 |
-|* `while`_                          |                                    |                                         |
-|                                    |* `boolean`_                        |                                         |
-|* `do...while`_                     |                                    |**Advanced I/O**                         |
-|                                    |* `char`_                           |                                         |
-|* `break`_                          |                                    |* `tone()`_                              |
-|                                    |* `unsigned char`_                  |                                         |
-|* `continue`_                       |                                    |* `noTone()`_                            |
-|                                    |* `byte`_                           |                                         |
-|* `return`_                         |                                    |* `shiftOut()`_                          |
-|                                    |* `int`_                            |                                         |
-|* `goto`_                           |                                    |* `pulseIn()`_                           |
-|                                    |* `unsigned int`_                   |                                         |
-|                                    |                                    |                                         |
-|**Further syntax**                  |* `word`_                           |**Time**                                 |
-|                                    |                                    |                                         |
-|* `;`_ (semicolon)                  |* `long`_                           |* `millis()`_                            |
-|                                    |                                    |                                         |
-|* `{}`_ (curly braces)              |* `unsigned long`_                  |* `micros()`_                            |
-|                                    |                                    |                                         |
-|* `//`_ (single line comment)       |* `float`_                          |* `delay()`_                             |
+|                                    |Primitive data types on the Maple   |* `analogWrite()`_ - PWM                 |
+|* `while`_                          |have different sizes than on the    |                                         |
+|                                    |Arduino, since the Maple has a full |                                         |
+|* `do...while`_                     |32-bit processor.  The size of each |**Advanced I/O**                         |
+|                                    |such type on the Maple is given     |                                         |
+|* `break`_                          |below.                              |* `tone()`_                              |
 |                                    |                                    |                                         |
-|* `/\* \*/`_ (multi-line comment)   |* `double`_                         |* `delayMicroseconds()`_                 |
+|* `continue`_                       |The ``word`` type is (deliberately) |* `noTone()`_                            |
+|                                    |:ref:`not supported                 |                                         |
+|* `return`_                         |<language-no-word>`.                |* `shiftOut()`_                          |
 |                                    |                                    |                                         |
-|* `#define`_                        |* `string`_                         |                                         |
-|                                    |                                    |**Math**                                 |
-|* `#include`_                       |* `array`_                          |                                         |
-|                                    |                                    |* `min()`_                               |
+|* `goto`_                           |* `void`_                           |* `pulseIn()`_                           |
 |                                    |                                    |                                         |
-|**Arithmetic Operators**            |**Conversion**                      |* `max()`_                               |
+|                                    |* `boolean`_ (1 byte)               |                                         |
+|**Further syntax**                  |                                    |**Time**                                 |
+|                                    |* `char`_ (1 byte)                  |                                         |
+|* `;`_ (semicolon)                  |                                    |* `millis()`_                            |
+|                                    |* `unsigned char`_ (1 byte)         |                                         |
+|* `{}`_ (curly braces)              |                                    |* `micros()`_                            |
+|                                    |* `byte`_ (1 byte)                  |                                         |
+|* `//`_ (single line comment)       |                                    |* `delay()`_                             |
+|                                    |* `int`_ (4 bytes)                  |                                         |
+|* `/\* \*/`_ (multi-line comment)   |                                    |* `delayMicroseconds()`_                 |
+|                                    |* `unsigned int`_ (4 bytes)         |                                         |
+|* `#define`_                        |                                    |                                         |
+|                                    |* `long`_ (8 bytes)                 |**Math**                                 |
+|* `#include`_                       |                                    |                                         |
+|                                    |* `unsigned long`_ (8 bytes)        |* `min()`_                               |
 |                                    |                                    |                                         |
-|* `=`_ (assignment operator)        |* `char()`_                         |* `abs()`_                               |
+|**Arithmetic Operators**            |* `float`_ (4 bytes)                |* `max()`_                               |
 |                                    |                                    |                                         |
-|* `+`_ (addition)                   |* `byte()`_                         |* `constrain()`_                         |
+|* `=`_ (assignment operator)        |* `double`_ (8 bytes)               |* `abs()`_                               |
 |                                    |                                    |                                         |
-|* `-`_ (subtraction)                |* `int()`_                          |* `map()`_                               |
+|* `+`_ (addition)                   |* `string`_                         |* `constrain()`_                         |
 |                                    |                                    |                                         |
-|* `*`_ (multiplication)             |* `word()`_                         |* `pow()`_                               |
+|* `-`_ (subtraction)                |* `array`_                          |* `map()`_                               |
 |                                    |                                    |                                         |
-|* `/`_ (division)                   |* `long()`_                         |* `sqrt()`_                              |
+|* `*`_ (multiplication)             |                                    |* `pow()`_                               |
+|                                    |**Conversion**                      |                                         |
+|* `/`_ (division)                   |                                    |* `sqrt()`_                              |
+|                                    |* `char()`_                         |                                         |
+|* `%`_ (modulo)                     |                                    |                                         |
+|                                    |* `byte()`_                         |**Trigonometry**                         |
 |                                    |                                    |                                         |
-|* `%`_ (modulo)                     |* `float()`_                        |                                         |
-|                                    |                                    |**Trigonometry**                         |
+|**Comparison Operators**            |* `int()`_                          |* `sin()`_                               |
 |                                    |                                    |                                         |
-|**Comparison Operators**            |**Variable Scope & Qualifiers**     |* `sin()`_                               |
+|* `==`_ (equal to)                  |* `word()`_                         |* `cos()`_                               |
 |                                    |                                    |                                         |
-|* `==`_ (equal to)                  |* `variable scope`_                 |* `cos()`_                               |
+|* `!=`_ (not equal to)              |* `long()`_                         |* `tan()`_                               |
 |                                    |                                    |                                         |
-|* `!=`_ (not equal to)              |* `static`_                         |* `tan()`_                               |
-|                                    |                                    |                                         |
-|* `<`_ (less than)                  |* `volatile`_                       |                                         |
+|* `<`_ (less than)                  |* `float()`_                        |                                         |
 |                                    |                                    |**Random Numbers**                       |
-|* `>`_ (greater than)               |* `const`_                          |                                         |
-|                                    |                                    |* `randomSeed()`_                        |
+|* `>`_ (greater than)               |                                    |                                         |
+|                                    |**Variable Scope & Qualifiers**     |* `randomSeed()`_                        |
 |* `<=`_ (less than or equal to)     |                                    |                                         |
-|                                    |**Utilities**                       |* `random()`_                            |
+|                                    |* `variable scope`_                 |* `random()`_                            |
 |* `>=`_ (greater than or equal to)  |                                    |                                         |
-|                                    |* `sizeof()`_ (sizeof operator)     |                                         |
+|                                    |* `static`_                         |                                         |
 |                                    |                                    |**Bits and Bytes**                       |
-|**Boolean Operators**               |                                    |                                         |
+|**Boolean Operators**               |* `volatile`_                       |                                         |
 |                                    |                                    |* `lowByte()`_                           |
-|* `&&`_ (and)                       |                                    |                                         |
+|* `&&`_ (and)                       |* `const`_                          |                                         |
 |                                    |                                    |* `highByte()`_                          |
 |* `||`_ (or)                        |                                    |                                         |
-|                                    |                                    |* `bitRead()`_                           |
+|                                    |**Utilities**                       |* `bitRead()`_                           |
 |* `!`_ (not)                        |                                    |                                         |
-|                                    |                                    |* `bitWrite()`_                          |
+|                                    |* `sizeof()`_ (sizeof operator)     |* `bitWrite()`_                          |
 |                                    |                                    |                                         |
 |**Pointer Access Operators**        |                                    |* `bitSet()`_                            |
 |                                    |                                    |                                         |
@@ -180,6 +190,27 @@ Arduino Documentation Links
 |                                    |                                    |                                         |
 +------------------------------------+------------------------------------+-----------------------------------------+
 
+.. _language-no-word:
+
+.. note::
+
+   The ``word`` data type is not supported on the Maple.  This is by
+   choice.
+
+   We decided not to include it because, while the Maple has 32-bit
+   words, the word size on an Arduino board is only 16 bits, and code
+   that uses the ``word`` type is likely to rely on that fact.
+
+   By not supporting ``word``, you'll get a compile error when porting
+   Arduino code to your Maple instead of potentially weird,
+   hard-to-debug runtime behavior.
+
+   If you're porting over Arduino code and really want ``word``, you
+   can put the following at the top of the file you're porting::
+
+     typedef uint16 word;
+   
+
 .. _setup(): http://arduino.cc/en/Reference/Setup
 .. _loop(): http://arduino.cc/en/Reference/Loop
 .. _if: http://arduino.cc/en/Reference/If