Board-specific values; corresponding QA test generalizations.

Various board-specific #defines and arrays of pins added.

For the changelog (some of this information predates this commit):

* wirish/boards.h now declares the following arrays of pin numbers:

      * boardPWMPins - PWM-capable pins
      * boardADCPins - ADC-capable pins
      * boardUsedPins - pins already in use, e.g. BOARD_BUTTON_PIN

  It also declares a bool boardUsesPin(uint8 pin) function for
  convenient testing of whether a pin is in use.

* wirish/boards/*.h now define:

      * BOARD_USART1_TX_PIN
      * BOARD_USART1_RX_PIN
      * BOARD_USART2_TX_PIN
      * BOARD_USART2_RX_PIN
      * BOARD_USART3_TX_PIN
      * BOARD_USART3_RX_PIN
      * BOARD_NR_GPIO_PINS (renamed from NR_GPIO_PINS)
      * BOARD_NR_USARTS (renamed from NR_USARTS)
      * BOARD_NR_PWM_PINS
      * BOARD_NR_ADC_PINS
      * BOARD_NR_USED_PINS

* wirish/boards/maple_native.h now defines:

      * BOARD_UART4_TX_PIN
      * BOARD_UART4_RX_PIN
      * BOARD_UART5_TX_PIN
      * BOARD_UART5_RX_PIN

  (Unfortunately, wirish/boards/maple_RET6.h cannot, since at least
  one of the UART4/UART5 pins are used already; this will require layout
  changes for a wide-release Maple form factor RET6 board).

* wirish/boards/*.cpp all include the corresponding array definitions.
  They all live in flash by default, thanks to the new __FLASH__ macro
  in wirish/wirish_types.h, which is a synonym for the existing __attr_flash
  #define in libmaple/libmaple_types.h.

The documentation was updated to include this information.  It also
gained various FIXME/TODO comments related to its generalization
across boards.

The quality assurance-related examples (examples/qa-slave-shield.cpp
and examples/test-session.cpp) now make heavy use of board-specific
values to ensure portability.

17 files changed, 316 insertions, 81 deletions

diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst
index ef745f5..7ecb5d4 100644
--- a/source/arm-gcc.rst
+++ b/source/arm-gcc.rst
@@ -4,12 +4,11 @@
 GCC for Maple
 =============
 
-This document provides notes on the current usage of
-``arm-none-eabi-gcc``, the `CodeSourcery <http://codesourcery.com>`_
-version of the GNU `GCC <http://gcc.gnu.org/>`_ compilers used to
-compile programs for the Maple.  It is not intended as a reference
-manual for GCC; such manuals are available `elsewhere
-<http://gcc.gnu.org/>`_.
+This document provides notes on using of ``arm-none-eabi-gcc``, the
+`CodeSourcery <http://codesourcery.com>`_ version of the GNU `GCC
+<http://gcc.gnu.org/>`_ compilers used for the Maple boards.  It is
+not intended as a reference manual for GCC; such manuals are available
+`elsewhere <http://gcc.gnu.org/>`_.
 
 Obtaining ``arm-none-eabi-gcc``
 -------------------------------
@@ -17,21 +16,24 @@ Obtaining ``arm-none-eabi-gcc``
 Recent versions of ``arm-none-eabi-gcc`` and associated tools are
 included with the :ref:`Maple IDE <ide>`.
 
-Users who wish to use ``arm-none-eabi-gcc`` in concert with a standard
-Unix toolchain are referred to our :ref:`unix-toolchain` reference,
-which describes how to set up such an environment.
+Users who wish to use ``arm-none-eabi-gcc`` directly, along with a
+standard Unix Make-based toolchain, should read the
+:ref:`unix-toolchain`, which describes how to set up such an
+environment.
 
-LeafLabs mirrors some of the more recent versions of the compiler
-under http://static.leaflabs.com/pub/codesourcery/\ , including
-versions for OS X, win32, and 32-bit Linux.
+LeafLabs maintains `mirrors
+<http://static.leaflabs.com/pub/codesourcery/>`_ for some of the more
+recent versions of the compiler, including versions for OS X, Win32,
+and 32-bit Linux.
 
 Compiler Flags Used by libmaple
 -------------------------------
 
 This section documents the flags passed to ``arm-none-eabi-gcc`` by
-the :ref:`Maple IDE <ide>` and the default Makefile provided with
-:ref:`libmaple <unix-toolchain>`.  The information in this section is
-subject to change without notice.
+the :ref:`Maple IDE <ide>` and the default Makefile provided with the
+:ref:`Unix toolchain <unix-toolchain>`.  The information in this
+section is subject to change between :ref:`libmaple <libmaple>`
+releases.
 
 .. highlight:: sh
 
@@ -40,7 +42,8 @@ The following flags are among those passed to the C compiler::
     -Os -g -mcpu=cortex-m3 -mthumb -march=armv7-m -nostdlib
     -ffunction-sections -fdata-sections -Wl,--gc-sections
 
-The following flags are among those passed to the C++ compiler::
+In addition to those flags just given for the C compiler, the
+following flags are among those passed to the C++ compiler::
 
     -fno-rtti -fno-exceptions -Wall
 
@@ -52,6 +55,15 @@ The following flags are among those passed to the assembler::
 
 .. _arm-gcc-avr-gcc:
 
+Using the C Standard Library
+----------------------------
+
+By default (under both the :ref:`Maple IDE <ide>` and the :ref:`Unix
+toolchain <unix-toolchain>`), ``arm-none-eabi-gcc`` is configured to
+link against `newlib <http://sourceware.org/newlib/>`_, a C standard
+library intended for use with embedded applications.  You are free to
+include of any of its headers.
+
 Switching from AVR-GCC
 ----------------------
 
@@ -63,8 +75,11 @@ including Arduino) for use on the Maple.
 .. _arm-gcc-attribute-flash:
 
 - Replacing ``PROGMEM``: You can direct the linker script provided
-  with libmaple to store a variable in flash by using
-  ``__attribute__((section (".USER_FLASH")))``, like so::
+  with libmaple to store a variable in Flash (instead of RAM) by using
+  the libmaple macro ``__FLASH__``, like so::
 
-      uint32 arr[] __attribute__((section (".USER_FLASH"))) = {...};
+      uint32 array[] __FLASH__ = {0, 1, 2};
 
+  Be aware, however, that if you do that, you can only store values
+  which are compile-time constants, and that if you attempt to change
+  a variable stored in Flash, your program will crash.
diff --git a/source/compatibility.rst b/source/compatibility.rst
index 0d6319f..eb28ad2 100644
--- a/source/compatibility.rst
+++ b/source/compatibility.rst
@@ -41,6 +41,8 @@ means that programs aren't much larger (or are even smaller).
 Header Numbering and Incompatibilities
 --------------------------------------
 
+.. FIXME generalize Maple-specific information
+
 The numbering of headers is different; on the Maple each GPIO has a
 unique number: D0, D1, D2, all the way up to D37 (actually, there are
 :ref:`a few more <jtag>`...). On the Arduino, the analog pins are
diff --git a/source/gpio.rst b/source/gpio.rst
index cebb402..5daf43c 100644
--- a/source/gpio.rst
+++ b/source/gpio.rst
@@ -3,6 +3,8 @@
 GPIO
 ====
 
+.. FIXME generalize this maple-specific information
+
 The Maple features 38 ready-to-use general purpose input/output (GPIO)
 pins for digital input/output, numbered D0 through D37.  These numbers
 correspond to the numeric values next to each header on the Maple
diff --git a/source/i2c.rst b/source/i2c.rst
index b4a996b..e2a7a04 100644
--- a/source/i2c.rst
+++ b/source/i2c.rst
@@ -4,11 +4,16 @@
 |i2c|
 =====
 
+.. FIXME update this documentation once you write the Wire library on
+.. top of libmaple i2c.
+
+.. FIXME generalize Maple-specific documentation
+
 .. note::
 
-   The |i2c| interface is currently only available from the 'i2c' branch
-   of the github `libmaple <http://github.com/leaflabs/libmaple>`_
-   repository.
+   The |i2c| interface is currently only available from the 'refactor'
+   branch of the github `libmaple
+   <http://github.com/leaflabs/libmaple>`_ repository.
 
 |i2c| is a crude and easy-to-hack serial protocol that requires only
 two wires/channels for communication between many devices.  Every
@@ -56,10 +61,8 @@ Function Reference
 ------------------
 
 The function API for |i2c| is not finished! See the `source code
-<http://github.com/leaflabs/libmaple/blob/i2c/libmaple/i2c.h>`_ for
-now.
-
-.. TODO link to libmaple I2C docs once (1) finished, (2) in master
+<https://github.com/leaflabs/libmaple/blob/refactor/libmaple/i2c.h>`_
+for now.
 
 SMBus
 -----
@@ -68,8 +71,6 @@ The STM32 microcontroller has hardware support for SMBus; we simply
 have not written software for it. The SMBAL line for i2c1 is on header
 D4 and for i2c2 is on D31.
 
-.. TODO link to libmaple SMBus docs once (1) finished, (2) in master
-
 .. _i2c-recommended-reading:
 
 Recommended Reading
diff --git a/source/index.rst b/source/index.rst
index 4369fbd..de71411 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -38,6 +38,7 @@ Have fun!
    Bootloader <bootloader>
    Troubleshooting <troubleshooting>
    Known Problems <errata>
+   Notes on GCC's ARM target <arm-gcc>
 
 .. _index-hardware:
 
diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst
index 35c6fbc..7099b69 100644
--- a/source/lang/api/analogread.rst
+++ b/source/lang/api/analogread.rst
@@ -35,6 +35,8 @@ have to do this once, so it's usually done in :ref:`lang-setup`\ ).
 Parameter Discussion
 --------------------
 
+.. FIXME generalize Maple-specific information
+
 The pin parameter is the number of the analog input pin to read from.
 Header pins on the Maple with ADC functionality (marked as "AIN" on
 the silkscreen) are:
@@ -49,24 +51,25 @@ Note
 ----
 
 If the analog input pin is not connected to anything, the value
-returned by analogRead() will fluctuate based on a number of factors
-(e.g. the values of the other analog inputs, how close your hand is to
-the board, etc.) in a seemingly random way.
+returned by ``analogRead()`` will fluctuate due to a number of reasons
+(like the values of the other analog inputs, how close your hand is to
+the board, etc.) in a "random" way.
 
 
 Example
 -------
 
- ::
+::
 
+    int analogPin = 3;     // Potentiometer wiper (middle terminal) connected
+                           // to analog pin 3. outside leads to ground and +3.3V.
+                           // You may have to change this value if your board
+                           // cannot perform ADC conversion on pin 3.
 
-    int analogPin = 3;     // potentiometer wiper (middle terminal) connected
-                           // to analog pin 3. outside leads to ground and +3.3V
     int val = 0;           // variable to store the value read
 
     void setup() {
       pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input
-      SerialUSB.begin();                // set up usb virtual COM port
     }
 
     void loop() {
@@ -97,23 +100,27 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so::
     // be aware that you're losing a lot of precision if you do this
     int adc_reading = analogRead(pin) >> 2;
 
+.. FIXME Mention Native can do analogReference(), when it's time
+
 On the Arduino, the input range and resolution can be changed using
 their implementation of `analogReference()
 <http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
 way its hardware (as of Rev 5) was designed, it's not possible to
 implement analogReference on the Maple, so this function doesn't
 exist.  If your inputs lie in a different voltage range than 0V--3.3V,
-you'll need to bring them into that range before using analogRead.
-Some basic tools to accomplish this are `resistor dividers
-<http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes
+you'll need to bring them into that range before using
+``analogRead()``.  Some basic tools to accomplish this are `resistor
+dividers <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener
+diodes
 <http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
-. However, opamps and other powered components can also be used if
-greater precision is required.
+. However, `operational amplifiers
+<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other
+powered components can also be used if greater precision is required.
 
 See also
 --------
 
-- :ref:`ADC note <adc>`
+- :ref:`ADC tutorial <adc>`
 - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
 
 .. include:: cc-attribution.txt
diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst
new file mode 100644
index 0000000..367adbb
--- /dev/null
+++ b/source/lang/api/board-values.rst
@@ -0,0 +1,155 @@
+.. _lang-board-values:
+
+Board-Specific Constants
+========================
+
+There are a number of board-specific values: constants or variables
+which are different depending on which LeafLabs board you have.
+
+This page lists and documents the board-specific values.  You should
+use these when appropriate in your own programs.  This will help make
+it easier to share your code with other people who have different
+boards.  Some example usages are given :ref:`below
+<lang-board-values-examples>`.
+
+.. contents:: Contents
+   :local:
+
+Constants
+---------
+
+- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on
+  your board.
+
+.. _lang-board-values-but:
+
+- ``BOARD_BUTTON_PIN``: Pin connected to the built-in button (labeled
+  "BUT" on your board's silkscreen).
+
+.. _lang-board-values-led:
+
+- ``BOARD_LED_PIN``: Pin connected to the built-in LED.
+
+- ``BOARD_NR_GPIO_PINS``: Total number of :ref:`GPIO pins <gpio>` that
+  are broken out to headers.  Some of these might already be connected
+  to external hardware (like the built-in LED and button).  To find
+  out if a pin is in use, see :ref:`boardUsesPin()
+  <lang-boardusespin>` (and also :ref:`boardUsedPins
+  <lang-board-values-used-pins>`).
+
+.. _lang-board-values-nr-pwm-pins:
+
+- ``BOARD_NR_PWM_PINS``: Total *number* of GPIO pins that can be used
+  for :ref:`PWM <pwm>`.  The actual *pins* that can do PWM are in the
+  :ref:`boardPWMPins <lang-board-values-pwm-pins>` array.
+
+.. _lang-board-values-nr-adc-pins:
+
+- ``BOARD_NR_ADC_PINS``: Total number of GPIO pins that can be used
+  for :ref:`analog-to-digital conversion <adc>`.  The actual pins that
+  can do ADC conversion are in the :ref:`boardADCPins
+  <lang-board-values-adc-pins>` array.
+
+.. _lang-board-values-nr-used-pins:
+
+- ``BOARD_NR_USED_PINS``: Total number of GPIO pins that are already
+  connected to some external hardware (like a built-in LED) on the
+  board.  The actual pins that that are already used are in the
+  :ref:`boardUsedPins <lang-board-values-used-pins>` array.  To see if
+  a pin is already in use, use the :ref:`boardUsesPin()
+  <lang-boardusespin>` function.
+
+.. _lang-board-values-usart:
+
+- USART (serial port) related constants:
+
+    * ``BOARD_USART1_TX_PIN``, ``BOARD_USART2_TX_PIN``, ``BOARD_USART3_TX_PIN``:
+      TX pins for the 3 USARTS.
+
+    * ``BOARD_USART1_RX_PIN``, ``BOARD_USART2_RX_PIN``, ``BOARD_USART3_RX_PIN``:
+      RX pins for the 3 USARTS.
+
+    * ``BOARD_UART4_TX_PIN``, ``BOARD_UART5_TX_PIN``: TX pins for
+      UARTs 4 and 5 (high-density boards like Maple Native only).
+
+    * ``BOARD_UART4_RX_PIN``, ``BOARD_UART5_RX_PIN``: RX pins for
+      UARTs 4 and 5 (high-density boards like Maple Native only).
+
+    * ``BOARD_NR_USARTS``: Number of serial ports on the board.  This
+      number includes UARTs 4 and 5 if they are available.
+
+.. _lang-board-values-pwm-pins:
+.. _lang-board-values-adc-pins:
+.. _lang-board-values-used-pins:
+
+Pin Arrays
+----------
+
+Some :ref:`arrays <lang-array>` of pin numbers are available which you
+can use to find out certain important information about a given pin.
+
+.. TODO add links to the board-specific hardware information on what
+.. are in these arrays
+
+- ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM
+  <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`.  The total
+  number of these pins is :ref:`BOARD_NR_PWM_PINS
+  <lang-board-values-nr-pwm-pins>`.
+
+- ``boardADCPins``: Pin numbers of each pin capable of :ref:`ADC
+  <adc>` conversion, using :ref:`analogRead() <lang-analogread>`.  The
+  total number of these pins is :ref:`BOARD_NR_ADC_PINS
+  <lang-board-values-nr-adc-pins>`.
+
+- ``boardUsedPins``: Pin numbers of each pin that, by default, is used
+  for some special purpose by the board.  The total number of these
+  pins is :ref:`BOARD_NR_USED_PINS <lang-board-values-nr-used-pins>`.
+  To check if a pin is used for a special purpose, use
+  :ref:`boardUsesPin() <lang-boardusespin>`.
+
+.. _lang-board-values-examples:
+
+Examples
+--------
+
+:ref:`BOARD_LED_PIN <lang-board-values-led>` On the Maple, the
+built-in LED is connected to pin 13.  On the Maple Mini, however, it
+is connected to pin 33.  You can write a "blinky" program that works
+on all LeafLabs boards using ``BOARD_LED_PIN`` and :ref:`toggleLED()
+<lang-toggleled>`::
+
+    void setup() {
+        pinMode(BOARD_LED_PIN, OUTPUT);
+    }
+
+    void loop() {
+        toggleLED();
+        delay(100);
+    }
+
+:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: Similarly, you can
+write a single program that prints a message whenever the button is
+pressed which will work on all LeafLabs boards using
+``BOARD_BUTTON_PIN`` and :ref:`isButtonPressed()
+<lang-isbuttonpressed>`::
+
+    void setup() {
+        pinMode(BOARD_BUTTON_PIN, INPUT);
+    }
+
+    void loop() {
+        if (isButtonPressed()) {
+            SerialUSB.println("You pressed the button!");
+        }
+    }
+
+See Also
+--------
+
+- :ref:`lang-boardusespin`
+- :ref:`lang-isbuttonpressed`
+- :ref:`lang-waitforbuttonpress`
+- :ref:`lang-pinmode`
+- :ref:`lang-toggleled`
+- :ref:`lang-analogread`
+- :ref:`lang-pwmwrite`
diff --git a/source/lang/api/boardusespin.rst b/source/lang/api/boardusespin.rst
new file mode 100644
index 0000000..8dc4c64
--- /dev/null
+++ b/source/lang/api/boardusespin.rst
@@ -0,0 +1,27 @@
+.. highlight:: cpp
+
+.. _lang-boardusespin:
+
+boardUsesPin()
+==============
+
+Each LeafLabs board connects some pins to external hardware.  The most
+important examples of this are the built-in LED and button.  You can
+check if a board uses a particular pin using this function.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: boardUsesPin
+
+See Also
+--------
+
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`boardUsedPins <lang-board-values-used-pins>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
+- :ref:`toggleLED() <lang-toggleled>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
+- :ref:`isButtonPressed() <lang-isbuttonpressed>`
+- :ref:`waitForButtonPress() <lang-waitforbuttonpress>`
+
diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst
index 2e968e7..c5a7c0c 100644
--- a/source/lang/api/constants.rst
+++ b/source/lang/api/constants.rst
@@ -293,23 +293,16 @@ exponent indicators.  Some examples are given in the following table:
 Board-Specific Constants
 ------------------------
 
-This section documents constants whose value might change across
-different LeafLabs boards.  You can use these constants to help ensure
-that your code will be portable across different boards.
+There are several :ref:`board-specific constants <lang-board-values>`
+whose value depends on which LeafLabs board you have.  If you use
+them, it will help make sure that your code will work well on all
+LeafLabs boards, not just the one you have.  This will make it much
+easier to share your code with others.
 
-.. TODO replace "upcoming" when Mini, Native come out
-
-.. _lang-constants-led:
-
-- ``BOARD_LED_PIN``: the number of the pin which connects to the
-  built-in LED.  On the Maple, this is pin 13, but it's not guaranteed
-  to be the same in upcoming boards like the Maple Mini.
-
-.. _lang-constants-but:
-
-- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the
-  built-in button (labeled "BUT").  On the Maple, this is pin 38, but
-  it's not guaranteed to be the same in other boards.
+For example, the pin number connected to the board's built-in LED is
+different on the different boards, but the board-specific constant
+:ref:`BOARD_LED_PIN <lang-board-values-led>` will always be the
+correct value for each board.
 
 See Also
 --------
@@ -325,5 +318,6 @@ See Also
 - :ref:`unsigned long long <lang-unsignedlonglong>`
 - :ref:`float <lang-float>`
 - :ref:`double <lang-double>`
+- :ref:`Board-Specific Values <lang-board-values>`
 
 .. include:: cc-attribution.txt
diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst
index c7a630d..3f086ca 100644
--- a/source/lang/api/hardwaretimer.rst
+++ b/source/lang/api/hardwaretimer.rst
@@ -10,6 +10,12 @@ built-in timer peripherals.  More information on these peripherals
 (including code examples) is available in the :ref:`timers reference
 <timers>`.
 
+.. FIXME update HardwareTimer documentation after redoing it in terms
+.. of the new timer interface.
+
+.. warning:: This class has been deprecated.  It is not available in
+   the current build.
+
 Library Documentation
 ---------------------
 
diff --git a/source/lang/api/isbuttonpressed.rst b/source/lang/api/isbuttonpressed.rst
index dbff0c9..8c350b9 100644
--- a/source/lang/api/isbuttonpressed.rst
+++ b/source/lang/api/isbuttonpressed.rst
@@ -4,7 +4,8 @@ isButtonPressed()
 =================
 
 Check whether the board's built-in button (labeled BUT on the
-silkscreen) is pressed.
+silkscreen) is pressed.  The pin number of the built-in button is
+given by the constant ``BOARD_BUTTON_PIN``.
 
 Library Documentation
 ---------------------
@@ -14,4 +15,6 @@ Library Documentation
 See Also
 --------
 
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
 - :ref:`lang-waitforbuttonpress`
diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst
index 9d50077..cea602b 100644
--- a/source/lang/api/pwmwrite.rst
+++ b/source/lang/api/pwmwrite.rst
@@ -11,6 +11,8 @@ pwmWrite(), the pin will output a steady square wave with the given
 duty cycle.  You can change the duty cycle later by calling pwmWrite()
 again with the same pin and a different duty.
 
+.. FIXME board-specific information
+
 On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
 9, 11, 12, 14, 24, 27, and 28.
 
diff --git a/source/lang/api/toggleled.rst b/source/lang/api/toggleled.rst
index 0cc20c2..54a7d64 100644
--- a/source/lang/api/toggleled.rst
+++ b/source/lang/api/toggleled.rst
@@ -13,5 +13,5 @@ Library Documentation
 See Also
 --------
 
-- :ref:`BOARD_LED_PIN <lang-constants-led>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
 - :ref:`togglePin() <lang-togglepin>`
diff --git a/source/lang/api/waitforbuttonpress.rst b/source/lang/api/waitforbuttonpress.rst
index 34c5066..a5bd45c 100644
--- a/source/lang/api/waitforbuttonpress.rst
+++ b/source/lang/api/waitforbuttonpress.rst
@@ -14,4 +14,6 @@ Library Documentation
 See Also
 --------
 
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
 - :ref:`lang-isbuttonpressed`
diff --git a/source/language-index.rst b/source/language-index.rst
index c949988..531e72c 100644
--- a/source/language-index.rst
+++ b/source/language-index.rst
@@ -26,13 +26,13 @@ programmers familiar with the Arduino language.
 |                                  |                                    |
 +----------------------------------+------------------------------------+
 
-.. Unimplemented in libmaple or not part of current release:
+.. Unimplemented or not part of current release:
 
 .. toctree::
    :hidden:
 
+   lang/unimplemented/tone.rst
    lang/unimplemented/notone.rst
    lang/unimplemented/pulsein.rst
    lang/unimplemented/stringclass.rst
    lang/unimplemented/stringobject.rst
-   lang/unimplemented/tone.rst
diff --git a/source/language.rst b/source/language.rst
index d340aec..ea841f5 100644
--- a/source/language.rst
+++ b/source/language.rst
@@ -10,6 +10,9 @@ 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.
 
+.. TODO Wiring tutorial -- just describe setup()/loop(), then link to
+.. some of the the bajillion external tutorials
+
 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`.
@@ -25,6 +28,21 @@ Maple Language Reference
 The following table summarizes the available core language features.
 A more exhaustive index is available at the :ref:`language-index`.
 
+**Looking for something else?** 
+
+- See the :ref:`libraries` for extra built-in libraries for dealing
+  with different kinds of hardware.
+
+.. FIXME mention Maple Native supports malloc(), free(), operator
+.. new(), and operator delete(), when that is a true thing to say.
+
+- If you're looking for something from the C standard library (like
+  ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
+  <arm-gcc>` used to compile your programs is configured to link
+  against `newlib <http://sourceware.org/newlib/>`_, and allows the
+  use of any of its header files.  However, dynamic memory allocation
+  (``malloc()``, etc.) is not available.
+
 +--------------------------------------------+----------------------------------------------+---------------------------------------------------+
 | Structure                                  | Variables                                    | Functions                                         |
 |                                            |                                              |                                                   |
@@ -40,13 +58,13 @@ A more exhaustive index is available at the :ref:`language-index`.
 |                                            |* :ref:`true <lang-constants-true>` |         |* :ref:`togglePin() <lang-togglepin>`              |
 |* :ref:`for <lang-for>`                     |  :ref:`false <lang-constants-false>`         |                                                   |
 |                                            |                                              |* :ref:`toggleLED() <lang-toggleled>`              |
-|* :ref:`switch/case <lang-switchcase>`      |* :ref:`BOARD_LED_PIN <lang-constants-led>` | |                                                   |
-|                                            |  :ref:`BOARD_BUTTON_PIN <lang-constants-but>`|* :ref:`isButtonPressed() <lang-isbuttonpressed>`  |
-|* :ref:`while <lang-while>`                 |                                              |                                                   |
-|                                            |* :ref:`Constants                             |* :ref:`waitForButtonPress()                       |
-|* :ref:`do...while <lang-dowhile>`          |  <lang-constants>` (:ref:`integers           |  <lang-waitforbuttonpress>`                       |
-|                                            |  <lang-constants-integers>`, :ref:`floating  |                                                   |
-|* :ref:`break <lang-break>`                 |  point <lang-constants-fp>`)                 |**Analog I/O**                                     |
+|* :ref:`switch/case <lang-switchcase>`      |* :ref:`Constants                             |                                                   |
+|                                            |  <lang-constants>` (:ref:`integers           |* :ref:`isButtonPressed() <lang-isbuttonpressed>`  |
+|* :ref:`while <lang-while>`                 |  <lang-constants-integers>`, :ref:`floating  |                                                   |
+|                                            |  point <lang-constants-fp>`)                 |* :ref:`waitForButtonPress()                       |
+|* :ref:`do...while <lang-dowhile>`          |                                              |  <lang-waitforbuttonpress>`                       |
+|                                            |* :ref:`Board-specific values                 |                                                   |
+|* :ref:`break <lang-break>`                 |  <lang-board-values>`                        |**Analog I/O**                                     |
 |                                            |                                              |                                                   |
 |* :ref:`continue <lang-continue>`           |**Data Types**                                |* :ref:`analogRead() <lang-analogread>`            |
 |                                            |                                              |                                                   |
@@ -76,7 +94,7 @@ A more exhaustive index is available at the :ref:`language-index`.
 |**Arithmetic Operators**                    |  <lang-int>`                                 |                                                   |
 |                                            |                                              |* :ref:`delayMicroseconds()                        |
 |* :ref:`= <lang-assignment>`                |* ``unsigned long`` (4 bytes), synonym for    |  <lang-delaymicroseconds>`                        |
-|  (assignment operator)                     |  :ref:`unsigned int <lang-unsignedint>`      |                                                   |
+|  (assignment)                              |  :ref:`unsigned int <lang-unsignedint>`      |                                                   |
 |                                            |                                              |                                                   |
 |* :ref:`+ <lang-arithmetic>` (addition)     |* :ref:`long long <lang-longlong>` (8 bytes)  |**Math**                                           |
 |                                            |                                              |                                                   |
@@ -153,13 +171,13 @@ A more exhaustive index is available at the :ref:`language-index`.
 |                                            |                                              |                                                   |
 |* :ref:`++ <lang-increment>`                |                                              |* :ref:`Serial <lang-serial>`                      |
 |  (increment)                               |                                              |                                                   |
-|                                            |                                              |**Looking for something else?**                    |
+|                                            |                                              |                                                   |
 |* :ref:`- - <lang-increment>`               |                                              |                                                   |
-|  (decrement)                               |                                              | See the :ref:`libraries` page for interfacing with|
-|                                            |                                              | particular types of hardware.  Maple links        |
-|* :ref:`+= <lang-compoundarithmetic>`       |                                              | against `newlib <http://sourceware.org/newlib/>`_ |
-|  (compound add)                            |                                              | and allows the use of any of its functions; see   |
-|                                            |                                              | its documentation for more details.               |
+|  (decrement)                               |                                              |                                                   |
+|                                            |                                              |                                                   |
+|* :ref:`+= <lang-compoundarithmetic>`       |                                              |                                                   |
+|  (compound add)                            |                                              |                                                   |
+|                                            |                                              |                                                   |
 |* :ref:`-=                                  |                                              |                                                   |
 |  <lang-compoundarithmetic>` (compound      |                                              |                                                   |
 |  subtract)                                 |                                              |                                                   |
diff --git a/source/libmaple.rst b/source/libmaple.rst
index 8cc39a3..9faca03 100644
--- a/source/libmaple.rst
+++ b/source/libmaple.rst
@@ -30,12 +30,12 @@ wrappers and code to imitate the Arduino programming library.
 
     git clone git://github.com/leaflabs/libmaple.git
 
-**Table of contents:**
+.. TODO after finishing refactor: create, style, and host a pure
+.. Doxygen libmaple reference docs.  This implies determining a stable
+.. API.
 
-.. toctree::
-   :maxdepth: 2
+.. **Table of contents:**
 
-   Guide to using GCC's ARM target <arm-gcc>
+.. .. toctree::
+..    :maxdepth: 2
 
-.. TODO LATER create, style, and host a pure Doxygen libmaple
-.. reference docs.  This implies determining a stable API.