New documentation content is done. Next step is to theme.

30 files changed, 663 insertions, 272 deletions

diff --git a/docs/source/_static/img/button-new.png b/docs/source/_static/img/button-new.png
new file mode 100644
index 0000000..3fd98be
--- /dev/null
+++ b/docs/source/_static/img/button-new.png
diff --git a/docs/source/_static/img/button-open.png b/docs/source/_static/img/button-open.png
new file mode 100644
index 0000000..466fc10
--- /dev/null
+++ b/docs/source/_static/img/button-open.png
diff --git a/docs/source/_static/img/button-save.png b/docs/source/_static/img/button-save.png
new file mode 100644
index 0000000..7eba286
--- /dev/null
+++ b/docs/source/_static/img/button-save.png
diff --git a/docs/source/_static/img/button-serial-monitor.png b/docs/source/_static/img/button-serial-monitor.png
new file mode 100644
index 0000000..aec9741
--- /dev/null
+++ b/docs/source/_static/img/button-serial-monitor.png
diff --git a/docs/source/_static/img/button-stop.png b/docs/source/_static/img/button-stop.png
new file mode 100644
index 0000000..4812ae9
--- /dev/null
+++ b/docs/source/_static/img/button-stop.png
diff --git a/docs/source/_static/img/button-upload.png b/docs/source/_static/img/button-upload.png
new file mode 100644
index 0000000..0f41eeb
--- /dev/null
+++ b/docs/source/_static/img/button-upload.png
diff --git a/docs/source/_static/img/button-verify.png b/docs/source/_static/img/button-verify.png
new file mode 100644
index 0000000..95abeb8
--- /dev/null
+++ b/docs/source/_static/img/button-verify.png
diff --git a/docs/source/_static/img/ide-blinky.png b/docs/source/_static/img/ide-blinky.png
new file mode 100644
index 0000000..3cccdb4
--- /dev/null
+++ b/docs/source/_static/img/ide-blinky.png
diff --git a/docs/source/_static/img/serial-monitor.png b/docs/source/_static/img/serial-monitor.png
new file mode 100644
index 0000000..6162dab
--- /dev/null
+++ b/docs/source/_static/img/serial-monitor.png
diff --git a/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst
index 8435a1f..ef745f5 100644
--- a/docs/source/arm-gcc.rst
+++ b/docs/source/arm-gcc.rst
@@ -1,34 +1,70 @@
 
 .. _arm-gcc:
 
-============
- GCC on ARM
-============
+GCC for Maple
+=============
 
-This document provides an introduction to using
-:command:`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.
+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/>`_.
 
-Stub.
+Obtaining ``arm-none-eabi-gcc``
+-------------------------------
 
+Recent versions of ``arm-none-eabi-gcc`` and associated tools are
+included with the :ref:`Maple IDE <ide>`.
 
-.. _arm-gcc-avr-gcc-diff:
+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.
 
+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.
 
-Differences with AVR-GCC
-------------------------
+Compiler Flags Used by libmaple
+-------------------------------
 
-people coming from arduino and other Atmel AVR powered microcontroller
-platforms are likely to be used to AVR-GCC.  our compiler is
-different.  explain why (stub).
+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.
 
+.. highlight:: sh
+
+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::
+
+    -fno-rtti -fno-exceptions -Wall
+
+The following flags are among those passed to the assembler::
+
+    -mcpu=cortex-m3 -march=armv7-m -mthumb
+
+.. highlight:: cpp
+
+.. _arm-gcc-avr-gcc:
+
+Switching from AVR-GCC
+----------------------
+
+This section, which is expected to grow over time, describes
+techniques for porting code which uses AVR-GCC features (AVR-GCC is
+the compiler used by many Atmel AVR-based microcontroller boards,
+including Arduino) for use on the Maple.
 
 .. _arm-gcc-attribute-flash:
 
-Tips and Tricks
----------------
+- 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::
 
-* you can use ``__attribute__`` to stick things in flash (stub)
+      uint32 arr[] __attribute__((section (".USER_FLASH"))) = {...};
 
diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst
index 1cfd17f..d42c050 100644
--- a/docs/source/bootloader.rst
+++ b/docs/source/bootloader.rst
@@ -95,8 +95,8 @@ platforms to make everything work this way.
 
 .. _bootloader-rev3:
 
-Maple Rev3/Rev5
----------------
+Maple Rev3/Rev5 - DFU
+---------------------
 
 Maple Rev 3 takes a completely different tack, more along the lines of
 Arduino.  In Rev 3, the device resets into bootloader mode, which
@@ -143,6 +143,11 @@ bringing up the USB serial.
 Maple Rev6 - The Serial Bootloader (Tentative)
 ----------------------------------------------
 
+.. note:: This section documents an in-progress version of the Maple
+   bootloader.  **No Maples yet sold use this bootloader protocol**.
+   It has not been yet been publicly released, and its interface is
+   not stable.
+
 The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac,
 but was unsatisfactory on Windows. Unlike the other operating systems,
 Windows needed to be manually pointed to both the driver to use for
@@ -580,4 +585,98 @@ SOFT_RESET response:
 Flashing A Custom Bootloader
 ----------------------------
 
-Stub (flashing a custom bootloader)
+The STM32 microprocessor on the Maple comes with a built-in hardware
+bootloader that can be used to flash a new (software) bootloader onto
+the chip.  This section describes how to go about this, using a Maple
+Rev 3 or higher (if you have a Maple Rev 1; you don't have a BUT
+button, and won't be able to follow these directions.  A workaround is
+detailed in `this forum posting
+<http://forums.leaflabs.com/topic.php?id=32#post-126>`_).
+
+.. warning:: This section is directed at users wishing to write a
+   custom bootloader for the Maple, or update their bootloader to a
+   more recent version.  It's generally not necessary to do so, and it
+   is possible to make a mistake and e.g. render your Maple unable to
+   communicate with the IDE.  Know what you're doing, and proceed with
+   caution.
+
+.. highlight:: sh
+
+Setup
+^^^^^
+
+In order to follow these instructions, you will need:
+
+- A binary of the bootloader you want to upload
+- Hardware for communicating between the Maple and your computer over
+  serial.
+- `Python <http://python.org>`_ version 2.5 or higher, with the
+  `PySerial <http://pyserial.sourceforge.net/>`_ library installed.
+
+**Step 1: Obtain a bootloader binary**. The first thing you'll need to
+do is to compile your bootloader binary.  Note that an ASCII
+representation of the binary, such as the Intel .hex format, will not
+suffice.  For example, you can run (on a :ref:`suitably configured
+system <unix-toolchain>`) the following to obtain a binary of the
+bootloader currently used on the Maple::
+
+    $ git checkout git://github.com/leaflabs/maple-bootloader.git
+    $ cd maple-bootloader
+    $ make
+    $ ls -lh build/maple-boot.bin # this is the compiled bootloader binary
+
+**Step 2: Connect Maple Serial1 to your computer**.
+There are a variety of ways of doing this.  We use Sparkfun's `FTDI
+breakout boards <http://www.sparkfun.com/products/718>`_, but you
+could use another Maple, an Arduino, etc. -- anything that allows your
+computer to communicate with the Maple you want to reprogram over a
+serial interface.
+
+If you do use an FTDI breakout board, first make sure your Maple is
+disconnected from an external power source, be it battery, USB, or
+barrel jack.  Then, connect the FTDI board's TX pin to ``Serial1``\ 's
+RX pin (pin 8), FTDI RX to ``Serial1`` TX (pin 7), FTDI ground to
+Maple's GND, and its 3.3V pin to Maple's Vin (use the Maple's
+silkscreen for help locating these pins).  At this point, you're ready
+to plug the FTDI board into your computer (via USB).
+
+The ``Serial1`` pins are documented :ref:`here <lang-serial>`.
+
+**Step 3: Put your Maple into serial bootloader mode**.  Do this by
+pressing the RESET button, then *while RESET is held down*, pressing
+and holding the BUT button.  Next, *making sure to keep BUT held
+down*, release the RESET button and wait for a few seconds before
+releasing BUT.
+
+**Step 4: Obtain stm32loader.py**.  The
+script ``stm32loader.py`` is provided with libmaple.  If you have set
+up the :ref:`Unix toolchain <unix-toolchain>`, it is available in
+libmaple/support/stm32loader.py.  Otherwise, you can download it
+directly from `github
+<https://github.com/leaflabs/libmaple/raw/master/support/stm32loader.py>`_
+(click the link, then save the file somewhere on your system).
+
+Flashing the new Bootloader
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We'll use ``new-boot.bin``, ``ser-port``, and ``stm32loader.py`` to
+respectively refer to the absolute paths to the bootloader binary
+(from Step 1), the serial port device file or COMM port (from Steps 2
+and 3), and the stm32loader.py script.
+
+.. highlight:: sh
+
+You can run ::
+
+    $ python stm32loader.py -h
+
+to obtain usage information.  The incantation for uploading a
+bootloader binary ``new-bootloader.bin`` is ::
+
+    $ python stm32loader.py -p ser-port -evw new-boot.bin
+
+If all goes well, you'll see a bunch of output, then "Verification
+OK".  If something goes wrong, the `forum`_ is probably your best bet
+for obtaining help, with IRC (irc.freenode.net, #leafblowers) being
+another option.  If all else fails, you can always `contact us
+directly`_!
diff --git a/docs/source/compatibility.rst b/docs/source/compatibility.rst
index 7eb0a8f..a070b42 100644
--- a/docs/source/compatibility.rst
+++ b/docs/source/compatibility.rst
@@ -17,10 +17,13 @@ that the Maple uses a 32-bit ARM Cortex-M3 architecture chip while the
 Arduinos have 8-bit Atmel AVR chips. The different instruction set
 means that machine code (executable binary programs) is incompatible
 between the two, and a different compiler (actually just a different
-version of `gcc <http://gcc.gnu.org/>`_) is required. The compiler for
-the regular Arduino IDE is the popular :command:`avr-gcc` package; the
-compiler for the Maple version of the IDE is CodeSourcery's edition of
-gcc for the ARM EABI target (:command:`arm-non-eabi-gcc`).
+version of `gcc <http://gcc.gnu.org/>`_) is required.
+
+The compiler for the regular Arduino IDE is the popular
+:command:`avr-gcc` package; the compiler for the Maple version of the
+IDE is CodeSourcery's edition of gcc for the ARM EABI target
+(:command:`arm-non-eabi-gcc`).  A (preliminary) reference on
+:ref:`using arm-none-eabi-gcc <arm-gcc>` is available.
 
 The bitwidth of the processor means that the Maple can process 32-bit
 operations (like adding two 32-bit integers) in a single instruction,
@@ -45,8 +48,8 @@ numbered separately (A0-A5) from the digital pins (D0\ -D13).
 
 The incompatible hardware differences are:
 
-* |i2c| port: on most Arduinos, the |i2c| port is Analog Input
-  4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5
+* **I2C port**: on most Arduinos, the |i2c| port is Analog Input 4
+  (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5
   (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA).
 
   It should be possible to skywire, sacrificing signal quality (due to
@@ -54,21 +57,22 @@ The incompatible hardware differences are:
   reasonably well in software. This peripheral could potentially be
   rerouted internally, but we haven't looked into it.
 
-* :ref:`PWM <pwm>` on D10: all the other standard Arduino PWM headers have PWM
-  functionality on the Maple (D2,D3,D6,D9,D11), but not D10. We did
-  our best! It may be possible to reroute this peripheral internally
-  using low level configuration, but we haven't looked in to it.
+* :ref:`PWM <pwm>` **on D10**: all the other standard Arduino PWM
+  headers have PWM functionality on the Maple (D2,D3,D6,D9,D11), but
+  not D10. We did our best! It may be possible to reroute this
+  peripheral internally using low level configuration, but we haven't
+  looked in to it.
 
-* No External Voltage Reference: The Arduino has an Aref pin which
+* **No External Voltage Reference**: The Arduino has an Aref pin which
   allows the use of an external ADC voltage reference; the Maple has
   an extra GPIO pin (14) with PWM capability in this spot, and does
   not allow an external voltage reference to be configured.
 
-* EEPROM: the Maple does not have any internal EEPROM. This
+* **EEPROM**: the Maple does not have any internal EEPROM. This
   functionality can be emulated with regular persistent flash memory,
   or with an external EEPROM chip.
 
-* ISP Programming: the Maple does not use an ISP/ICSP bus for
+* **ISP Programming**: the Maple does not use an ISP/ICSP bus for
   debugging; it uses :ref:`JTAG <jtag>`.
 
 
@@ -76,14 +80,18 @@ Software Language/Library Changes
 ---------------------------------
 
 With :ref:`a few exceptions <language-missing-features>`, the entire
-Arduino language is supported.  However, there are some subtle
+Wiring/Arduino language is supported.  However, there are some subtle
 differences, most of which are improvements:
 
-* 32-bit integers: many standard functions either expect or return
+* **32-bit integers**: many standard functions either expect or return
   full 32-bit (4 byte) integer values instead of the regular 16-bit (2
   byte) Arduino values.
 
-* :ref:`pinMode() <lang-pinmode>` types: any :ref:`GPIO <gpio>`
+* **64-bit doubles**: The :ref:`double <lang-double>` type is a full
+  double-precision floating point type on the Maple; it is a
+  single-precision floating point value on the Arduino.
+
+* :ref:`pinMode() <lang-pinmode>` **types**: any :ref:`GPIO <gpio>`
   (including analog pins) can be configured into one of the following
   modes with a single call to ```pinMode()``: ``OUTPUT``,
   ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``,
@@ -91,41 +99,162 @@ differences, most of which are improvements:
   be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the
   :ref:`GPIO documentation <gpio>` for more information.
 
-* ``Serial1`` syntax: like the `Arduino Mega
+* :ref:`Serial port <lang-serial>` **syntax**: like the `Arduino Mega
   <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has
   multiple :ref:`USART ports <lang-serial>`.  By default, ``Serial``
   is not mapped to any of them, use ``Serial1`` through ``Serial3``
   instead.
 
-* 16-bit :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which
+* **16-bit** :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which
   means that calls to :ref:`analogWrite() <lang-analogwrite>` take
   values between 0 (always off) and 255 (always on).  The Maple
   supports 16-bit PWM, so the corresponding values should be between 0
   (always off) and 65535 (always on).
 
-* 12-bit :ref:`ADC <adc>`: Arduino boards support 10-bit ADC, which
+* **12-bit** :ref:`ADC <adc>`: Arduino boards support 10-bit ADC, which
   means that calls to :ref:`analogRead() <lang-analogread>` will
   return values between 0 and 1023.  The Maple supports 12-bit ADC, so
   the same call will instead return values between 0 and 4095.
 
-Stub (unfinished)
+Shield and Device Compatibility
+-------------------------------
+
+.. TODO update for 0.0.9
+
+.. list-table::
+   :header-rows: 1
+
+   * - Shield/Device
+     - Compatible?
+     - Notes
+
+   * - Ethernet shield
+     - Yes!
+     - Tested; no library yet
+
+   * - WiFi Shield
+     - Yes!
+     - Tested; no library yet (expected for 0.0.9)
+
+   * - MIDI shield
+     - Yes!
+     - Tested; no library yet
+
+   * - XBee shield
+     - Unknown
+     -
+
+   * - Bluetooth shield
+     - Unknown
+     -
+
+   * - Cellular shield
+     - Unknown
+     -
+
+Library Porting Status
+----------------------
+
+The state of currently ported Arduino libraries is the
+:ref:`libraries`.
+
+.. TODO update for 0.0.9; update as libraries are ported.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Library
+     - Ported?
+     - Notes
+
+   * - Wire
+     - Preliminary
+     - In progress; see :ref:`library reference <libraries-wire>`.
+
+   * - LiquidCrystal
+     - **Yes**
+     - :ref:`Included since IDE 0.0.7 <libraries-liquid-crystal>`
+
+   * - Ethernet
+     - Not yet
+     - Planned
 
-.. class:: ported-feature
+   * - EEPROM
+     - No
+     - The Maple doesn't have EEPROM; use flash instead.  Perhaps this
+       library could be emulated?
 
-I am supported!
+   * - Firmata
+     - Not yet
+     - Planned
 
-This should be ordinary
+   * - Matrix
+     - Not yet
+     - Planned
 
-.. class:: non-ported-feature
+   * - SoftwareSerial
+     - Not yet
+     - Planned
 
-I can't do it :(
+   * - Sprite
+     - Not yet
+     - Planned
 
-Also ordinary
+   * - Stepper
+     - Not yet
+     - Planned
 
-.. class:: partly-ported-feature
+Sketch and Library Porting HOWTO
+--------------------------------
 
-I sorta work
+In addition to the suggestions in this section, you may find many of
+the individual :ref:`language reference <language>` pages useful.  As
+appropriate, these have "Arduino Compatibility" sections; one good
+example is the :ref:`analogWrite() <lang-analogwrite-compatibility>`
+function.
 
-And I am also ordinary
+- Check the hardware and header differences above, and see if your
+  project or shield needs to be modified (eg, add 3.3V level
+  converters or reroute PWM to header D10).
 
+- Check for ported library functionality. We intend to port all of the
+  core and popular libraries (like Wire, Ethernet, and the LCD screen
+  driver), but this task is not yet finished. (Patches are welcome!)
 
+- Check for peripheral conflicts; changing the configuration of timers
+  and bus speeds for a feature on one header may impact all the
+  features on that hardware "port".  For example, changing the timer
+  prescaler to do long PWM pulses could impact |i2c| communications on
+  nearby headers.
+
+- Rewrite any low-level code. This could potentially be very
+  difficult, but hopefully you've used the Arduino libraries to
+  abstract away the registers and other hardware-specific
+  details. Your sketch probably doesn't have any low-level code; a
+  library which wraps a particular peripheral very well may.  Some
+  help is available in the :ref:`arm-gcc` reference.
+
+- Redeclare variable sizes if necessary: generics like ``int`` will
+  probably work unless you depend on side-effects like rollover.
+
+- Check every ``pinMode()``: the Maple has more modes for GPIO
+  pins. For example, make sure to set analog pins to ``INPUT_ANALOG``
+  before reading and PWM pins to ``PWM`` before writing.  The full set
+  of pin modes is documented in the :ref:`lang-pinmode` reference.
+
+- Modify PWM writes: ``pinMode()`` must be set to ``PWM``, the
+  frequency of the PWM pulse configured, and the duty cycle written
+  with up to 16-bit resolution.
+
+- Modify ADC reads: :ref:`lang-analogread` takes the full pin number
+  (not 0-5) and returns a full 12-bit reading. The ADC pin must have
+  its ``pinMode()`` set to ``INPUT_ANALOG``.
+
+- Possibly convert all Serial-over-USB communications to use
+  :ref:`lang-serialusb` instead of a USART :ref:`serial port
+  <lang-serial>`. The Maple has a dedicated USB port which is not
+  connected to the USART TX/RX pins in any way.
+
+- Check timing: Maple clock cycles are just 13.9 nanoseconds, though
+  the peripheral bus speeds (which limit GPIO output) are clocked
+  slower.
diff --git a/docs/source/epilog.rst b/docs/source/epilog.rst
index 4234dd9..e64103c 100644
--- a/docs/source/epilog.rst
+++ b/docs/source/epilog.rst
@@ -6,56 +6,3 @@
 .. _forum: http://forums.leaflabs.com
 .. _contact: http://leaflabs.com/contact/
 .. _contact us directly: http://leaflabs.com/contact/
-
-.. Arduino built-in functions
-
-.. _setup(): http://arduino.cc/en/Reference/Setup
-.. _loop():  http://arduino.cc/en/Reference/Loop
-
-.. _pinMode():      http://arduino.cc/en/Reference/PinMode
-.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite
-.. _digitalRead():  http://arduino.cc/en/Reference/DigitalRead
-
-.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference
-.. _analogRead():      http://arduino.cc/en/Reference/AnalogRead
-.. _analogWrite():     http://arduino.cc/en/Reference/AnalogWrite
-
-.. _tone():     http://arduino.cc/en/Reference/Tone
-.. _noTone():   http://arduino.cc/en/Reference/NoTone
-.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut
-.. _pulseIn():  http://arduino.cc/en/Reference/PulseIn
-
-.. _millis():            http://arduino.cc/en/Reference/Millis
-.. _micros():            http://arduino.cc/en/Reference/Micros
-.. _delay():             http://arduino.cc/en/Reference/Delay
-.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds
-
-.. _min():       http://arduino.cc/en/Reference/Min
-.. _max():       http://arduino.cc/en/Reference/Max
-.. _abs():       http://arduino.cc/en/Reference/Abs
-.. _constrain(): http://arduino.cc/en/Reference/Constrain
-
-.. _map():  http://arduino.cc/en/Reference/Map
-.. _pow():  http://arduino.cc/en/Reference/Pow
-.. _sqrt(): http://arduino.cc/en/Reference/Sqrt
-
-.. _sin(): http://arduino.cc/en/Reference/Sin
-.. _cos(): http://arduino.cc/en/Reference/Cos
-.. _tan(): http://arduino.cc/en/Reference/Tan
-
-.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed
-.. _random():     http://arduino.cc/en/Reference/Random
-
-.. _lowByte():  http://arduino.cc/en/Reference/LowByte
-.. _highByte(): http://arduino.cc/en/Reference/HighByte
-.. _bitRead():  http://arduino.cc/en/Reference/BitRead
-.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite
-.. _bitSet():   http://arduino.cc/en/Reference/BitSet
-.. _bitClear(): http://arduino.cc/en/Reference/BitClear
-.. _bit():      http://arduino.cc/en/Reference/Bit
-
-.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt
-.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt
-
-.. _interrupts():   http://arduino.cc/en/Reference/Interrupts
-.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts
diff --git a/docs/source/errata.rst b/docs/source/errata.rst
index 4b03513..a3bb66a 100644
--- a/docs/source/errata.rst
+++ b/docs/source/errata.rst
@@ -7,10 +7,148 @@
 This page is a collection of known issues and warnings for each
 revision of the Maple board. The failure modes aren't design errors,
 but are easy ways to break or damage your board permanently. For a
-list of differences between the Maple and Arduinos, see the page on
-:ref:`compatibility <compatibility>`.
+list of differences between the Maple and Arduinos, see the
+:ref:`compatibility reference <compatibility>`.
 
 .. contents:: Contents
    :local:
 
-Stub.
+Maple Rev 5
+-----------
+
+These boards went on sale in November 2010.  They have white buttons,
+and "r5" in small print near the "LeafLabs Maple" text next to the
+"infinity-leaf" logo, among other changes:
+
+.. figure:: /_static/img/maple_rev5.png
+   :align: center
+   :alt: Maple Rev 5
+
+Known issues:
+
+* **GPIO 39-43 not configured**: this is really more of a software
+  "TODO" item.  Some of the JTAG header pins are numbered 39-43. These
+  STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a
+  :ref:`JTAG <jtag>` device is not connected, but we have not enabled
+  them in software and thus they can not be accessed with the regular
+  :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions.
+
+Potential failure modes:
+
+* **TTL voltage on non-tolerant pins**: not all header pins are 5V
+  compatible; connecting certain serial devices in the wrong way could
+  over voltage the pins.  The :ref:`Pin-Mapping Mega Table
+  <pin-mapping-mega-table>` details which pins are 5V-tolerant.
+
+Maple Rev 3
+-----------
+
+This batch of boards went on sale beginning in May 2010. They have a
+darker red silkscreen and the "infinity-leaf" logo:
+
+.. figure:: /_static/img/maple_rev3.png
+   :align: center
+   :alt: Maple Rev 3
+
+Known issues:
+
+* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010
+  have questionable RESET and BUT buttons.
+
+  What seems to have happened is that the flux remover we used to
+  clean the boards before shipping eroded the plastic internals, which
+  resulted in intermittent functionality. All buttons on all shipped
+  boards did function in testing, but some may have been unreliable in
+  regular use.
+
+  If you have this problem, we will be happy to ship you new buttons
+  if you think you can re-solder them yourself, or you can ship us
+  your board and we will swap out that part.
+
+  For reference, the button part number is KMR211GLFS and the flux
+  remover we used is "Precision Electronics Cleaner" from RadioShack,
+  which is "Safe on most plastics" and contains Dipropylene glycol
+  monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol
+  methyl ether acetate (really?), and carbon dioxide.
+
+* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on
+  USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line
+  between the STM32 and the headers. These resistors increase the
+  impedance of the lines for ADC reads and affect the open drain GPIO
+  functionality of the pins.
+
+  These resistors were accidentally copied over from older Arduino USB
+  designs, where they appear to protect the USB-Serial converter from
+  TTL voltage on the headers.
+
+* **GPIO 39-43 not configured**: this is really more of a software
+  "TODO" item.  Some of the JTAG header pins are numbered 39-43. These
+  STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a
+  :ref:`JTAG <jtag>` device is not connected, but we have not enabled
+  them in software and thus they can not be accessed with the regular
+  :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions.
+
+* **Silkscreen Errors**: the silkscreen on the bottom indicated PWM
+  functionality on pin 25 and listen the external header GND pin as
+  number 38 (actually 38 is connected to the BUT button). We manually
+  sharpied over both of these mistakes.
+
+* **PWM Marketing Mistake**: We originally sold the Maple advertising
+  22 channels of 16-bit hardware PWM; actually the Maple only has 15.
+
+Potential failure modes:
+
+* **TTL voltage on non-tolerant pins**: not all header pins are 5V
+  compatible; connecting certain serial devices in the wrong way could
+  over voltage the pins.  The :ref:`Pin-Mapping Mega Table
+  <pin-mapping-mega-table>` details which pins are 5V-tolerant.
+
+Maple Rev 1
+-----------
+
+This batch of 100 boards shipped in later 2009. They have a red
+silkscreen and the logo is a single pixelated leaf:
+
+.. figure:: /_static/img/maple_rev1.png
+   :align: center
+   :alt: Maple Rev 1
+
+Known issues:
+
+* **ADC noise**: generally very high, in particular when the USB port
+  is being used for communications (including keep-alive pings when
+  connected to a computer).
+
+  This issue was resolved in Rev 3 with a 4-layer design and a
+  geometrically isolated ADC V\ :sub:`ref` plane.
+
+* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on
+  USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line
+  between the STM32 and the headers. These resistors increase the
+  impedance of the lines for ADC reads and affect the open drain GPIO
+  functionality of the pins.
+
+  These resistors were accidentally copied over from older Arduino USB
+  designs, where they appear to protect the USB-Serial converter from
+  TTL voltage on the headers.
+
+* **Silkscreen Differences**: the pin numbering scheme on Rev 1 is
+  different from Rev 3, and thus Rev 3 software is difficult to use
+  with Rev 1 boards. Notably, the analog input bank is labeled A0-A4
+  on Rev 1 but 15-20 on Rev 3, and the extra header bank does not have
+  a pinout table on the bottom.
+
+* **No BUT Button**: the BUT button, useful for serial bootloading,
+  was only added in Rev 3. As a workaround, you can directly short the
+  appropriate MCU pin to Vcc; see `this forum posting
+  <http://forums.leaflabs.com/topic.php?id=32#post-126>`_.
+
+* **PWM Marketing Mistake**: We originally sold the Maple advertising
+  22 channels of 16-bit hardware PWM; actually the Maple only has 15.
+
+Potential failure modes:
+
+* **TTL voltage on non-tolerant pins**: not all header pins are 5v
+  compatible; connecting certain serial devices in the wrong way could
+  over voltage the pins. The :ref:`Pin-Mapping Mega Table
+  <pin-mapping-mega-table>` details which pins are 5V-tolerant.
diff --git a/docs/source/hardware.rst b/docs/source/hardware.rst
deleted file mode 100644
index 1fa3554..0000000
--- a/docs/source/hardware.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-.. _hardware:
-
-=================================
- Hardware-Specific Documentation
-=================================
-
-This page indexes the Maple's capabilities for interacting with
-external hardware peripherals.  For information about a particular
-device or protocol, see its individual reference page.
-
-Individual reference pages:
-
-.. toctree::
-   :maxdepth: 2
-
-   i2c
-   pwm
-   gpio
-   usb
-   jtag
-   adc
-   spi
-   usart
-   timers
diff --git a/docs/source/ide.rst b/docs/source/ide.rst
index 00dcf03..f38f6cd 100644
--- a/docs/source/ide.rst
+++ b/docs/source/ide.rst
@@ -1,23 +1,130 @@
 .. _ide:
 
-Maple IDE Documentation
-=======================
+Maple IDE
+=========
 
-Stub.
+.. figure:: /_static/img/ide-blinky.png
+   :align: center
+   :alt: Maple IDE
 
-.. TODO stub sections for all the other buttons, etc.
+This page documents the basic functionality of the Maple IDE.
+Specifically, it describes the operation of the buttons on the main
+toolbar.  It is expected to become more comprehensive over time.
 
-.. _ide-serial-monitor:
-
-Serial Monitor
---------------
+The :ref:`Maple Quickstart <maple-quickstart>` is another source of
+information on the IDE; it is especially useful for setting up a
+computer for the first time.
 
 .. _ide-verify:
 
 Verify
 ------
 
+.. image:: /_static/img/button-verify.png
+   :align: left
+
+Click Verify to compile the current sketch.
+
+.. _ide-stop:
+
+Stop
+----
+
+.. image:: /_static/img/button-stop.png
+
+Click Stop to cancel a compilation.
+
+.. _ide-new:
+
+New
+---
+
+.. image:: /_static/img/button-new.png
+
+Click New to begin a fresh sketch.
+
+.. _ide-open:
+
+Open
+----
+
+.. image:: /_static/img/button-open.png
+
+Click Open to open a new sketch.  By default, this will look in you
+*sketchbook*, which is a directory on your system which contains all
+of your sketches.  The default directory of your sketchbook varies by
+operating system; you can change it in the IDE preferences.
+
+.. _ide-save:
+
+Save
+----
+
+.. image:: /_static/img/button-save.png
+
+Click Save to save the currently opened sketch.
+
 .. _ide-upload:
 
 Upload
 ------
+
+.. image:: /_static/img/button-upload.png
+
+Click Upload to send the compiled sketch to your Maple to run.  Before
+you click Upload, you must have a memory location and serial port
+selected.  The memory location, either Flash or RAM, determines
+whether the compiled sketch binary will be stored on the Maple.  You
+can choose this using the Tools > Board menu.  The serial port
+corresponds to the Serial-over-USB connection the Maple has
+established with your computer.  This looks like "COM1", "COM2",
+etc. on Windows, "/dev/tty.usbmodemXXX" on Mac (where "XXX" is some
+sequence of letters and numbers), or "/dev/ttyACMXXX" on Linux (again,
+where "XXX" is some sequence of letters and numbers).  You can choose
+a serial port using the Tools > Serial Port menu.
+
+If you click Upload without having made these choices; The IDE
+*should* prompt you to do so.  However, if you're trying to upload and
+are unsuccessful, make sure you've made choices for both board and
+serial port.
+
+For more help, the upload process is documented in more detail (with
+screenshots) in the :ref:`quickstart <maple-quickstart-upload>`.
+
+If all else fails, try putting your Maple in :ref:`perpetual
+bootloader mode <troubleshooting-perpetual-bootloader>` before
+uploading.
+
+In any case, you can always find us on the `forum`_ or `contact us
+directly`_.
+
+.. _ide-serial-monitor:
+
+Serial Monitor
+--------------
+
+.. image:: /_static/img/button-serial-monitor.png
+
+Click Serial Monitor to open up a communications channel between your
+PC and the Maple's :ref:`Serial-over-USB <lang-serialusb>`
+(``SerialUSB``) virtual serial port.
+
+If the serial monitor is open, any information sent to the computer
+(e.g. using :ref:`SerialUSB.println() <lang-serialusb-println>` will
+be displayed in the large text area.  You can send data to the Maple
+(to be read with e.g. :ref:`SerialUSB.read() <lang-serialusb-read>`)
+by typing into the small text box and either hitting the Enter key or
+pressing the Send button.
+
+Here is an example serial monitor session with the InteractiveTest
+sketch (which you can load in the IDE by choosing menu item File >
+Examples > Maple > InteractiveTest):
+
+.. image:: /_static/img/serial-monitor.png
+
+This is the result of typing "?" in the text box and clicking Send.
+
+.. note:: You cannot upload a sketch while the serial monitor is open.
+   If you click :ref:`Upload <ide-upload>` while the serial monitor is
+   open, the IDE will close it for you before proceeding with the
+   upload.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 32fa28f..42d1bd0 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -17,7 +17,7 @@ If you're having problems, you might want to visit the
 <http://forums.leaflabs.com/>`_ to ask questions to the LeafLabs team
 and other Maple users.  Good luck, and have fun!
 
-Table of contents:
+General documentation:
 
 .. toctree::
    :maxdepth: 1
@@ -30,15 +30,24 @@ Table of contents:
    Library Reference <libraries>
    Command-Line Tools and APIs <libmaple>
    Troubleshooting <troubleshooting>
-   Hardware-Specific Documentation <hardware>
    External Interrupts <external-interrupts>
    Bootloader <bootloader>
    Known Problems <errata>
    Language Reference Index <language-index>
 
-Indices and tables
-==================
+.. _index-hardware:
 
-* :ref:`genindex`
-* :ref:`search`
+Hardware features:
 
+.. toctree::
+   :maxdepth: 1
+
+   i2c
+   pwm
+   gpio
+   usb
+   jtag
+   adc
+   spi
+   usart
+   timers
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index 9b8ee14..7cfba5f 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -32,7 +32,7 @@ Wiring Diagram
    JTAG wiring diagram to connect a standard 20-pin ARM JTAG device to
    the 8-pin JTAG port on the Maple.
 
-.. TODO jtag wiring diagram (above) looks terrible; replace it
+.. FIXME jtag wiring diagram (above) looks terrible; replace it
 
 The Maple has holes for a 8-pin JTAG header but that header is not
 soldered on by default. If you know ahead of time that you'll be
@@ -56,8 +56,7 @@ Compatible Devices
 
 We have had good experience with the `Olimex ARM-USB-OCD
 <http://www.olimex.com/dev/arm-usb-ocd.html>`_ device, which costs
-about 55 euro plus shipping (as of October 2010).
-
+about 55 euro plus shipping (as of November 2010).
 
 Recommended Reading
 -------------------
diff --git a/docs/source/lang/analogwrite.rst b/docs/source/lang/analogwrite.rst
index 3d05f44..2c50a42 100644
--- a/docs/source/lang/analogwrite.rst
+++ b/docs/source/lang/analogwrite.rst
@@ -25,6 +25,8 @@ analogWrite()
 .. contents:: Contents
    :local:
 
+.. _lang-analogwrite-compatibility:
+
 Arduino Compatibility
 ---------------------
 
diff --git a/docs/source/lang/serial.rst b/docs/source/lang/serial.rst
index f96547d..ca89b31 100644
--- a/docs/source/lang/serial.rst
+++ b/docs/source/lang/serial.rst
@@ -20,25 +20,24 @@ pins summarized in the following table:
    :header-rows: 1
 
    * - Serial port
-     - Pins (TX, RX)
+     - TX, RX, CK
+     - CTS, RTS (if present)
 
    * - ``Serial1``
-     - 7, 8
+     - 7, 8, 6
+     -
 
    * - ``Serial2``
-     - 1, 0
+     - 1, 0, 10
+     - 2, 3
 
    * - ``Serial3``
-     - 29, 30
+     - 29, 30, 31
+     - 32, 33
 
 Thus, if you use a particular serial port, you cannot also use its
 communication pins for other purposes at the same time.
 
-Unlike the Arduino, none of these serial ports is connected to the USB
-port on the Maple board.  Thus, to use these pins to communicate with
-your personal computer, you will need an additional USB-to-serial
-adaptor.
-
 If you want to communicate with the Maple using the provided USB port,
 use :ref:`SerialUSB <lang-serialusb>` instead.
 
@@ -60,8 +59,8 @@ means that you can use any of these functions on any of ``Serial1``,
 
 .. cpp:class:: HardwareSerial
 
-   Serial port class.  Predefined instances are Serial1, Serial2, and
-   Serial3.
+   Serial port class.  Predefined instances are ``Serial1``,
+   ``Serial2``, and ``Serial3``.
 
 .. cpp:function:: HardwareSerial::begin(unsigned int baud)
 
@@ -73,7 +72,7 @@ means that you can use any of these functions on any of ``Serial1``,
 .. cpp:function:: HardwareSerial::end()
 
    Disables the USART associated with this object, allowing any
-   associated TX and RX pins to be used for other purposes.
+   associated communication pins to be used for other purposes.
 
 .. cpp:function:: unsigned int HardwareSerial::available()
 
@@ -203,6 +202,14 @@ means that you can use any of these functions on any of ``Serial1``,
    ``println()`` functions is likely to be more useful when printing
    multiple characters, when formatting numbers for printing, etc.
 
+Arduino Compatibility Note
+--------------------------
+
+Unlike the Arduino, none of the Maple's serial ports is connected to
+the USB port on the Maple board (for that, use :ref:`SerialUSB
+<lang-serialusb>`).  Thus, to use these pins to communicate with your
+personal computer, you will need an additional USB-to-serial adaptor.
+
 .. TODO LATER port these examples over
 
 .. Examples
diff --git a/docs/source/lang/serialusb.rst b/docs/source/lang/serialusb.rst
index 9beee82..af3a7e0 100644
--- a/docs/source/lang/serialusb.rst
+++ b/docs/source/lang/serialusb.rst
@@ -71,6 +71,8 @@ world!")``.
 
    Returns the number of bytes available for reading.
 
+.. _lang-serialusb-read:
+
 .. cpp:function:: unsigned char USBSerial::read()
 
    Returns the next available, unread character.  If there are no
diff --git a/docs/source/lang/unimplemented/stringclass.rst b/docs/source/lang/unimplemented/stringclass.rst
index cdd385d..b893e83 100644
--- a/docs/source/lang/unimplemented/stringclass.rst
+++ b/docs/source/lang/unimplemented/stringclass.rst
@@ -3,7 +3,4 @@
 String Class
 ============
 
-Stub.
-
-
 .. include:: /lang/cc-attribution.txt
diff --git a/docs/source/language.rst b/docs/source/language.rst
index 350b0c3..463041e 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -222,8 +222,6 @@ more exhaustive index is available at the :ref:`language-index`.
 Missing Arduino Features
 ------------------------
 
-Stub TODO: fill in other missing features
-
 **analogReference()**
 
     It is not possible to implement this function on the Maple
@@ -252,6 +250,20 @@ Stub TODO: fill in other missing features
 
         typedef uint16 word;
 
+Unimplemented Arduino Features
+------------------------------
+
+The following Wiring/Arduino features are currently unimplemented on
+the Maple.  However, they will be present in future versions:
+
+- `interrupts() <http://arduino.cc/en/Reference/Interrupts>`_
+- `noInterrupts() <http://www.arduino.cc/en/Reference/NoInterrupts>`_
+- `noTone() <http://www.arduino.cc/en/Reference/NoTone>`_
+- `pulseIn() <http://www.arduino.cc/en/Reference/PulseIn>`_
+- `shiftOut() <http://www.arduino.cc/en/Reference/ShiftOut>`_
+- `String <http://arduino.cc/en/Reference/StringObject>`_
+- `tone() <http://www.arduino.cc/en/Reference/Tone>`_
+
 .. _our reference page: http://leaflabs.com/docs/external-interrupts/
 
 .. _newlib: http://sourceware.org/newlib/
diff --git a/docs/source/libmaple-api.rst b/docs/source/libmaple-api.rst
deleted file mode 100644
index d5b90b6..0000000
--- a/docs/source/libmaple-api.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _libmaple_api:
-
-========================
- libmaple API reference
-========================
-
-This page documents the lower-level features of libmaple, which may be
-of use to programmers who don't wish to use the Arduino-style
-environment provided by the `Maple IDE <maple-ide-install>`_.
-
-Stub.
diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst
index b161afb..b76c7c8 100644
--- a/docs/source/libmaple.rst
+++ b/docs/source/libmaple.rst
@@ -2,19 +2,19 @@
 
 .. _libmaple:
 
-====================
- libmaple Reference
-====================
+``libmaple`` Reference
+======================
 
 .. image:: /_static/img/libmaple-screenshot-small.png
    :align: center
    :alt: libmaple screenshot
 
-`LeafLabs libmaple <libmaple-libmaple>`_ is the low level library we have developed for for the ARM
-Cortex-M3 chips manufactured by STMicroelectronics used in the Maple
-boards (the `STM32F103x`_ series). We found the generic peripheral
-libraries too painful to build on top of, and reimplemented the
-functionality we needed in a simpler (and less general) form.
+`LeafLabs libmaple <libmaple-libmaple>`_ is the low level library we
+have developed for for the ARM Cortex-M3 chips manufactured by
+STMicroelectronics used in the Maple boards (the `STM32F103x`_
+series). We found the generic peripheral libraries too painful to
+build on top of, and reimplemented the functionality we needed in a
+simpler (and less general) form.
 
 .. _libmaple-libmaple: http://github.com/leaflabs/libmaple
 .. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103
@@ -22,7 +22,7 @@ functionality we needed in a simpler (and less general) form.
 This library is transparently included in the `Maple IDE
 <http://leaflabs.com/docs/maple-ide/>`_, but we develop it separately
 using good old Unix command line tools and release it for advanced
-users who might chafe at the “sketch” programming model of the
+users who might chafe at the "sketch" programming model of the
 IDE. Included are some examples, a Makefile, and the compatibility
 wrappers and code to imitate the Arduino programming library.
 
@@ -36,5 +36,7 @@ wrappers and code to imitate the Arduino programming library.
    :maxdepth: 2
 
    Unix Toolchain Quickstart <unix-toolchain>
-   libmaple API reference <libmaple-api>
    Guide to using GCC's ARM target <arm-gcc>
+
+.. TODO LATER create, style, and host a pure Doxygen libmaple
+.. reference docs.  This implies determining a stable API.
diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst
index 6ecdf07..4c87539 100644
--- a/docs/source/libraries.rst
+++ b/docs/source/libraries.rst
@@ -7,6 +7,9 @@
  Maple Library Reference
 =========================
 
+.. Note: if you port an Arduino library and document it here, be sure
+.. to update compatibility.rst to reflect that fact.
+
 This page briefly summarizes the Arduino libraries that have been
 ported to Maple. You can use a library from within a sketch by going
 to Sketch > Import Library... from within the IDE, then choosing the
diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst
index 6d99a4a..ca902f3 100644
--- a/docs/source/maple-quickstart.rst
+++ b/docs/source/maple-quickstart.rst
@@ -66,6 +66,8 @@ bottom window, and then a confirmation message will appear:
    :align: center
    :alt: Code verified successfully.
 
+.. _maple-quickstart-upload:
+
 Upload that program!
 --------------------
 
@@ -127,7 +129,7 @@ OS X:
    :alt: Board type and serial port for the OS X
 
 Then press the "Upload" button to upload your program to the
-Maple. 
+Maple.
 
 .. image:: /_static/img/upload-button.png
    :align: center
diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst
index 42dc1a5..fd72842 100644
--- a/docs/source/pwm.rst
+++ b/docs/source/pwm.rst
@@ -1,10 +1,9 @@
 .. _pwm:
 
-==============================
- Pulse-Width Modulation (PWM)
-==============================
+PWM
+===
 
-Pulse Width Modulation is a basic technique to create repeated square
+Pulse Width Modulation (PWM) is a basic technique to create repeated square
 waves (digital high/low voltage transitions) of user defined length
 and duty cycle. It can be used as a way to encode an "analog" signal
 on a single digital (high/low) line using the time between transitions
@@ -42,7 +41,7 @@ to track down exactly which timer *channel* corresponds to each pin.
    Timer1 | D6,D7,D8
    Timer2 | D0,D1,D2,D3
    Timer3 | D11,D12,D27,D28
-   Timer4 | D5,D9,D14,D24 
+   Timer4 | D5,D9,D14,D24
 
 Background
 ----------
@@ -96,11 +95,11 @@ Function Reference
 
 ``pinMode(pin_num, PWM)``
 
-    This command is usually called from `setup()`_ to tell the
-    microcontroller that pin_num should be configured to PWM
-    output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` is
-    also available (see the list of :ref:`GPIO modes <gpio-modes>` for
-    more information).
+    This command is usually called from :ref:`setup() <lang-setup>` to
+    tell the microcontroller that pin_num should be configured to PWM
+    output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN``
+    is also available (see the list of :ref:`GPIO modes <gpio-modes>`
+    for more information).
 
 .. _pwm-pwmwrite:
 
@@ -144,8 +143,8 @@ Function Reference
     For instance, an 8MHz frequency can be achieved by setting
     ``prescale`` to 9, since 72MHz / 9 = 8MHz.
 
-    This function is normally called once from, `setup()`_, but the
-    timer can be reconfigured with a new prescaler at any time.
+    This function is normally called once from, :ref:`lang-setup`, but
+    the timer can be reconfigured with a new prescaler at any time.
 
      * Configure the prescaler and overflow values to generate a timer
      * reload with a period as close to the given number of
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
index 7b80a3f..0c10d01 100644
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@@ -41,8 +41,8 @@ My 5v peripheral doesn't work! (I2C, SPI, USART, etc)
 
 Yup, the Maple is a 3.3v board. You may need to use a level
 converter. See the :ref:`compatibility <compatibility>`, :ref:`GPIO
-<gpio>`, or other :ref:`hardware specific documentation <hardware>`
-for more information.
+<gpio>`, or other :ref:`hardware specific documentation
+<index-hardware>` for more information.
 
 The reset and D38/serial buttons don't seem to work reliably!
 -------------------------------------------------------------
diff --git a/docs/source/usart.rst b/docs/source/usart.rst
index 19b054f..c0334a9 100644
--- a/docs/source/usart.rst
+++ b/docs/source/usart.rst
@@ -10,82 +10,18 @@
 Hardware/Circuit Design
 -----------------------
 
-The Maple has 3 separate USART devices: ``Serial1``, ``Serial2``, and
-``Serial3``. In the most simple use case, the RX and TX pins are used
-to send data at a predetermined baudrate with the line voltage level
-relative to ground.
-
-+-----------+--------+-----+
-|Port       |Function|Pin  |
-+===========+========+=====+
-|``Serial1``|TX      |D7   |
-|           |        |     |
-|           |RX      |D8   |
-|           |        |     |
-|           |CK      |D6   |
-+-----------+--------+-----+
-|``Serial2``|TX      |D1   |
-|           |        |     |
-|           |RX      |D0   |
-|           |        |     |
-|           |CK      |D10  |
-|           |        |     |
-|           |CTS     |D2   |
-|           |        |     |
-|           |RTS     |D3   |
-+-----------+--------+-----+
-|``Serial3``|TX      |D29  |
-|           |        |     |
-|           |RX      |D30  |
-|           |        |     |
-|           |CK      |D31  |
-|           |        |     |
-|           |CTS     |D32  |
-|           |        |     |
-|           |RTS     |D33  |
-+-----------+--------+-----+
-
-.. TODO make above less ugly
+The Maple has 3 separate USART devices. In the most simple use case,
+the RX and TX pins are used to send data at a predetermined baudrate
+with the line voltage level relative to ground.  Their usage is
+documented in the :ref:`Serial Ports <lang-serial>` language reference
+page.
 
 Compatible Devices and Specifications
 -------------------------------------
 
-We have successfully used the Maple USART ports with an FT232R-based USB-serial converter at up to 115200 baud; higher speeds should certainly be possible.
-
-Function Reference
-------------------
-
-In the following, you may replace ``SerialN`` with ``Serial1``,
-``Serial2``, or ``Serial3``.
-
-``SerialN.begin(baudrate)``
-
-    ``SerialN.begin`` is usually called in `setup()`_ to configure the
-    baudrate of the given serial port and to set up the header pins
-    appropriately. It can be called at any time to reconfigure a port
-    or to change the baudrate. 9600 baud is the generic speed most
-    widely supported by other devices and terminals.
-
-``SerialN.print(...)``/\ ``SerialN.println(...)``
-
-    Writes data into the port buffer to be transmitted as soon as
-    possible. Accepts strings (``char*``). If a raw integer is
-    passed, the corresponding ASCII character will be transmitted; to
-    print out a number in human readable form add a second parameter
-    with the base system. 
-
-    For example, to print out the decimal number '1234' use
-    ``SerialN.print(1234, DEC)``; to print out the binary number
-    '1001', use ``SerialN.print(9, BIN)``.
-
-``SerialN.available()``/\ ``SerialN.read()``
-
-    ``SerialN.read()`` will return the next unread character that has
-    been received over the port. ``SerialN.available()`` returns how
-    many such bytes are available (or zero if none are). If none are
-    available, ``SerialN.read()`` will block/fail, so the usual
-    program structure is to poll with ``SerialN.available`` and only
-    read if a nonzero value is returned.
+We have successfully used the Maple USART ports with an FT232R-based
+USB-serial converter at up to 115200 baud; higher speeds should
+certainly be possible.
 
 Recommended Reading
 -------------------