docs fixes

11 files changed, 126 insertions, 91 deletions

diff --git a/docs/source/compatibility.rst b/docs/source/compatibility.rst
index 848a3d3..0d6319f 100644
--- a/docs/source/compatibility.rst
+++ b/docs/source/compatibility.rst
@@ -13,17 +13,17 @@ Overview
 --------
 
 The biggest difference between the Maple and most Arduino boards is
-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`).  A (preliminary) reference on
-:ref:`using arm-none-eabi-gcc <arm-gcc>` is available.
+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 (which makes up executable binary program) 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 `avr-gcc
+<http://www.nongnu.org/avr-libc/>`_ 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,
@@ -31,12 +31,12 @@ while an Arduino processor would have to split up large operations
 into several smaller ones. In a lot of cases 8-bit operations are
 plenty (integers 0-255, single characters of text, etc.), but if
 you're dealing with higher resolution data, the speed up could be
-significant. A trade-off is that code could be larger as well; program
-instructions and memory locations can be up to 32-bits each, which in
-the worst case would quadruple program size. In reality, the removal
-of extra instructions and fancy packing together of simple
-instructions means that programs aren't much larger (or are even
-smaller).
+significant.
+
+A trade-off is that code could be larger as well; program instructions
+and memory locations can be up to 32 bits each.  However, removal of
+extra instructions and fancy packing together of simple instructions
+means that programs aren't much larger (or are even smaller).
 
 Header Numbering and Incompatibilities
 --------------------------------------
@@ -63,9 +63,9 @@ The incompatible hardware differences are:
   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
+  an extra GPIO pin (D14) 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
@@ -93,11 +93,13 @@ differences, most of which are improvements:
 
 * :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``,
+  modes with a single call to ``pinMode()``: ``OUTPUT``,
   ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``,
-  ``INPUT_PULLDOWN``. Additionally, the PWM and Analog Input pins can
-  be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the
-  :ref:`GPIO documentation <gpio>` for more information.
+  ``INPUT_PULLDOWN``. Additionally, the PWM pins (labeled "PWM" on the
+  Maple's silkscreen) can be configured in ``PWM`` and
+  ``PWM_OPEN_DRAIN`` modes, and the analog input pins (labeled "AIN")
+  can be configured in ``INPUT_ANALOG`` mode. See the :ref:`GPIO
+  documentation <gpio>` for more information.
 
 * :ref:`Serial port <lang-serial>` **syntax**: like the `Arduino Mega
   <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has
diff --git a/docs/source/errata.rst b/docs/source/errata.rst
index 8feb6ea..657abd9 100644
--- a/docs/source/errata.rst
+++ b/docs/source/errata.rst
@@ -24,20 +24,20 @@ Maple Rev 5
 Known issues:
 
 * **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the
-    corresponding "AIN" is missing from its silkscreen.
+  corresponding "AIN" is missing from its silkscreen.
 
 * **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
+  STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when 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
+* **High voltage on non-tolerant pins**: not all header pins are 5V
+  compatible; so e.g. 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
diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst
index 4017862..cebb402 100644
--- a/docs/source/gpio.rst
+++ b/docs/source/gpio.rst
@@ -11,7 +11,7 @@ silkscreen.
 Many of these pins may additionally be used for special features or
 peripheral functions.  This page documents those capabilities, by pin.
 
-The current and voltage limitations have not been copied over from the
+The current and voltage limitations have been copied over from the
 STM32 datasheet (see the :ref:`Recommended Reading
 <gpio-recommended-reading>` for a link).  In particular, a number of
 GPIO pins are 5V tolerant (which means that applying 5 volts to a pin
@@ -31,6 +31,9 @@ peripheral type. The "STM32" column refers to the port and number that
 the header is connected to on the microcontroller.  The "5V?" column
 documents whether or not the pin is 5 volt tolerant (see above).
 
+.. TODO silkscreen pictures which let you know what each abbreviation
+.. means, with links to the relevant documentation.
+
 .. csv-table::
    :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?"
 
@@ -83,13 +86,17 @@ GPIO Modes
 Function Reference
 ------------------
 
-.. doxygenfunction:: pinMode
+- :ref:`pinMode() <lang-pinmode>`
+
+- :ref:`digitalRead() <lang-digitalread>`
 
-.. doxygenfunction:: digitalRead
+- :ref:`digitalWrite() <lang-digitalwrite>`
 
-.. doxygenfunction:: digitalWrite
+- :ref:`analogRead() <lang-analogread>`
 
-.. doxygenfunction:: analogRead
+- :ref:`pwmWrite() <lang-pwmwrite>` (Maple's equivalent to
+  ``analogWrite()``; see the :ref:`analogWrite() reference
+  <lang-analogwrite>` for differences from the Arduino version).
 
 .. _gpio-recommended-reading:
 
diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst
index 8350cc5..874ee82 100644
--- a/docs/source/hardware/maple.rst
+++ b/docs/source/hardware/maple.rst
@@ -28,11 +28,6 @@ have a light red silkscreen and a single pixelated leaf as a logo.
    :align: center
    :alt: Maple Rev 1
 
-.. rubric:: Footnotes
-
-.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal
-   testing.
-
 Rev 3
 ^^^^^
 
@@ -60,6 +55,8 @@ them.
    :align: center
    :alt: Maple Rev 5
 
+.. _hardware-maple-powering:
+
 Powering the Maple
 ------------------
 
@@ -102,3 +99,8 @@ at the command line with ::
 
     $ git clone git://github.com/leaflabs/maple.git
 
+.. rubric:: Footnotes
+
+.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal
+   testing.
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 5c1718f..4369fbd 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -67,11 +67,11 @@ Have fun!
 
 .. TODO write/include these upon Mini and Native release
 
-.. toctree::
-   :hidden:
+.. .. toctree::
+..    :hidden:
 
-   hardware/maple-mini.rst
-   hardware/maple-native.rst
+..    hardware/maple-mini.rst
+..    hardware/maple-native.rst
 
 .. _index-reference:
 
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index e3c8111..858021e 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -4,6 +4,9 @@
  JTAG
 ======
 
+.. TODO update adapter schematic, add information on using it with our
+.. devices.
+
 JTAG is an interface for low-level debugging of digital devices. It
 gives instruction by instruction control over the microprocessor and
 allows data to be read and written to arbitrary memory and register
diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst
index c71b2c3..53a225d 100644
--- a/docs/source/lang/api/hardwarespi.rst
+++ b/docs/source/lang/api/hardwarespi.rst
@@ -39,17 +39,29 @@ pins for other purposes.
 Library Documentation
 ---------------------
 
+Using the SPI Class
+^^^^^^^^^^^^^^^^^^^
+
+You can declare that you want to use SPI in your sketch by putting
+``HardwareSPI Spi(number);`` with your variables, where ``number`` is
+1 or 2, depending on which SPI you want to use.  Then you can use the
+functions described in the next section.  For example::
+
+   // Use SPI 1
+   HardwareSpi Spi(1);
+
+   void setup() {
+       Spi.begin(SPI_18MHZ);
+   }
+
+   void loop() {
+       // Get the next byte from the peripheral
+       uint8 byte = Spi.recv();
+   }
+
 HardwareSPI Class Reference
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can use the SPI interface by including a declaration ``HardwareSPI
-Spi(number);`` at the start of the sketch or program.  The ``number``
-must be either 1 or 2 and specifies which port to use.  Once this is
-done, you can call any of the methods documented here using
-``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send
-the value ``0x13`` into the port buffer to be transmitted as soon as
-possible.
-
 .. cpp:class:: HardwareSPI
 
    Class for interacting with SPI.
diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
index 3e5424c..c7a630d 100644
--- a/docs/source/lang/api/hardwaretimer.rst
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -21,6 +21,9 @@ documented below on one of the predefined ``HardwareTimer`` instances.
 For example, to set the prescale factor on timer 1 to 5, call
 ``Timer1.setPrescaleFactor(5)``.
 
+.. TODO add code examples that people can copy and paste in case
+.. they're unfamiliar with namespace syntax
+
 .. cpp:class:: HardwareTimer
 
    Class for interacting with a timer.  There are four predefined
diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst
index 08fa5c1..899f720 100644
--- a/docs/source/maple-quickstart.rst
+++ b/docs/source/maple-quickstart.rst
@@ -6,6 +6,8 @@
  Maple Quickstart Guide
 ========================
 
+.. TODO update the images since we changed "to FLASH" -> "to Flash"
+
 You'll need a `Maple board <http://leaflabs.com/store/>`_, a `Mini-B
 USB cable <http://www.google.com/products?q=mini-b+usb+cable>`_, a
 functional computer, and possibly root (or "administrator") access to
@@ -58,9 +60,9 @@ Next, select Tools > Board > "LeafLabs Maple ... to FLASH":
    :align: left
    :alt: Verify button
 
-Now press the "verify" button (furthest to the left with a "play"
-arrow) to compile the code.  Some output should scroll by in the
-bottom window, and then a confirmation message will appear:
+Now press the "Verify" button (the "play" symbol; see image at left)
+to compile the code.  Some output should scroll by in the bottom
+window, and then a confirmation message will appear:
 
 .. image:: /_static/img/verify-success.png
    :align: center
@@ -71,11 +73,12 @@ bottom window, and then a confirmation message will appear:
 Upload that program!
 --------------------
 
-Now it's (finally!) time to plug in your Maple. Use a mini-b cable,
-making sure that the power source jumper is on the USB header first.
-We ship Maples with the power source jumper configured that way, so
-you shouldn't have to do anything.  For reference, it should look like
-this:
+Now it's time to plug in your Maple.  Use a Mini-B cable, making sure
+that the :ref:`power source jumper <hardware-maple-powering>` is on
+the USB header first.  We ship the Maple with the power source jumper
+configured that way, so you shouldn't have to do anything.  For
+reference, it should look like this (don't worry if a jumper is
+hanging half off of the CHRG header):
 
 .. image:: /_static/img/plugged-in-maple.png
    :align: center
@@ -105,10 +108,10 @@ it's there.  If it ever starts throbbing in a slow, smooth pattern,
 then you've got a problem: see the :ref:`troubleshooting
 <troubleshooting>` page for help.
 
-If all systems are go, select the Board type and Serial Port
-(something like :file:`COM3`, :file:`/dev/ttyACM0`, or
-:file:`/dev/tty.usbmodemfa221`, depending on your platform, from the
-Tools menu:
+If all systems are go, select the Maple's serial port in the Tools >
+Serial Port menu.  The Maple will appear as something like
+:file:`COMx`, :file:`/dev/ttyACMx`, or :file:`/dev/tty.usbmodemxxxxx`,
+depending on your platform, like so:
 
 Windows XP:
 
@@ -137,12 +140,13 @@ Maple.
 
 You should see some text and a progress bar flash by in the status
 window of the IDE, then some blinky patterns on the Maple, and then a
-constant blinking on and off.
+constant blinking on and off.  Congratulations!  You've successfully
+uploaded your first program to the Maple.
 
-Go ahead and modify the file a little bit: if you change the
-'delay(1000);' numbers to a different value the speed of the blink
-will change. The value is a time in milliseconds to pause before
-continuing with the program, so by default the LED will be on for 1
+Next, go ahead and modify the file a little bit.  If you change the
+``delay(1000);`` lines to a different value, the speed of the blink
+will change.  The value is a time in milliseconds to pause before
+continuing with the program, so by default, the LED will be on for 1
 second, then off for 1 second, etc.  Any time you make any changes, go
 through the same Verify and Upload process to upload the new version
 of your program to your Maple.
@@ -166,18 +170,18 @@ Use the serial port monitor!
 ----------------------------
 
 As a last step to make sure everything has been configured correctly,
-let's upload a hello world program that will send text from the Maple
-back to the IDE over the USB connection. From the File menu, select
-Examples > Stubs > HelloWorld (similarly to when you selected the
-Blink program), and make sure the correct board and serial port
-targets are selected from the Tools pull-down.
-
-Open the serial monitor window (button on the far right) and make sure
-the 9600 baud speed is selected. Then go back to the code editing
-window and upload your program (Upload will recompile your code
-automatically if there's been any change since the last Verify). You
-should get text spit at you over the serial monitor right after the
-program is uploaded. Shout back! We can hear you!
+let's upload a "Hello, world!" program that will send text from the
+Maple back to the IDE over the USB connection. From the File menu,
+select Examples > Stubs > HelloWorld (similarly to when you selected
+the Blink program), and make sure the correct board and serial port
+targets are selected from the Tools menu.
+
+Open the Serial Monitor window (on the far right of the toolbar) and
+make sure the 9600 baud speed is selected. Then go back to the code
+editing window and upload your program (Upload will recompile your
+code automatically if there's been any change since the last
+Verify). You should get text spit at you over the serial monitor right
+after the program is uploaded.  Shout back!  We can hear you!
 
 Go forth exuberantly!
 ---------------------
@@ -191,10 +195,11 @@ or maybe now is a good time for a trip to the kitchen for a delicious
 If you blew through this guide and are the kind of person who drinks
 their coffee straight, has more than a 100 lines of vim or emacs
 customization, and doesn't even have a mouse plugged into their
-computer, you may want to look at the :ref:`Unix Toolchain quickstart
+computer, you may want to look at the :ref:`Unix toolchain quickstart
 <unix-toolchain>` guide.  It's the tutorial for getting working with
-your old friends :command:`make`, :command:`jtag`, and :command:`gcc`.
+your old friends :command:`make`, :command:`gcc`, and :command:`jtag`.
 
 Let us know what you come up with! Tag us with #leaflabs on Twitter,
-post in the `forum`_, track us down in the real world, whatever. We
-love projects!
+post in the `forum`_, post on `our wiki's Projects page
+<http://wiki.leaflabs.com/index.php?title=Projects>`_, track us down
+in the real world, whatever. We love projects!
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
index f3052d9..9146ebe 100644
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@@ -106,10 +106,10 @@ A classic! Make sure you have selected a board from the pulldown menu.
 -----------------------------------------
 
 Your sketch/program either does not include one of the :ref:`setup()
-<lang-setup>` or `loop() <lang-loop>` functions, or it was not found
-by the compiler. Your program must include both ``void setup()`` and
-``void loop()`` functions; they don't have to do anything, but they
-**must** be there.
+<lang-setup>` or :ref:`loop() <lang-loop>` functions, or it was not
+found by the compiler. Your program must include both ``void setup()``
+and ``void loop()`` functions; they don't have to do anything, but
+they **must** be there.
 
 You can start with an example program (to see one in the IDE, click on
 File > Examples > Stubs > BareMinimum) to get the basic structure.
diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst
index 836f777..d49b642 100644
--- a/docs/source/unix-toolchain.rst
+++ b/docs/source/unix-toolchain.rst
@@ -6,11 +6,12 @@
  Unix Toolchain Quickstart
 ===========================
 
-This is a tutorial for using the Maple with a standard Unix toolchain.
-It's not necessary to do this in order to program the Maple; you can
-always :ref:`install the Maple IDE <maple-ide-install>` instead.
+This is a tutorial for using the Maple with a standard Unix toolchain
+(make, gcc, etc.).  It's not necessary to do this in order to program
+the Maple; you can always :ref:`install the Maple IDE
+<maple-ide-install>` instead.
 
-You'll need a Maple board, a mini-b USB cable, a functional computer,
+You'll need a Maple board, a Mini-B USB cable, a functional computer,
 and root access to that computer. This guide assumes you've had
 success with the IDE on your machine and that you are fairly
 comfortable with the Unix command line; some previous experience with