more docs

1 files changed, 128 insertions, 147 deletions

diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
index b878ae4..9d452d1 100644
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@@ -2,231 +2,212 @@
 
 .. _troubleshooting:
 
-=======================
- Maple Troubleshooting
-=======================
-
-* :ref:`Hardware Problems <troubleshooting-hardware>`
-
-  * The status LED is throbbing and I can't upload my program!
-  * My board is bricked! I can't upload via the bootloader no matter what!
-  * My 5v peripheral doesn't work! (I2C, SPI, USART, etc)
-  * The reset and D38/serial buttons don't seem to work reliably!
-
-* :ref:`IDE installation problems <troubleshooting-ide-install>`
-
-  * I don't have root/administrator access!
-  * [Linux] I don't use udev!
-
-* :ref:`IDE usage problems <troubleshooting-ide-usage>`
-
-  * [Mac OSX] The "Board" and "Serial Port" menu items are missing!
-
-* :ref:`Common compiler problems <troubleshooting-compilation>`
-
-  * ``NullPointerException``
-  * ``undefined reference to setup()/loop()``
-  * ``error: 'Serial' was not declared in this scope``
-  * ``File(s) not found``
-
-* :ref:`Common upload problems <troubleshooting-upload>`
-
-  * My program is too large!
-  * ``No DFU capable USB device found``
-  * I have multiple Maples installed; how do I know which one will get flashed?
+Troubleshooting
+===============
 
-* :ref:`Command-line issues <troubleshooting-shell>`
+This page documents common problems and their solutions.
 
-  * My flash programs don't seem to stick; they behave like they are RAM!
-  * [Linux] ``cdc_acm 3-1:1.0: no more free acm devices``
+.. contents:: Contents
+   :local:
 
-* :ref:`Tips and tricks <troubleshooting-tips-tricks>`
-
-  * Perpetual bootloader mode
-
-.. _troubleshooting-hardware:
-
-Hardware problems
------------------
+===================
+ Hardware problems
+===================
 
 The status LED is throbbing and I can't upload my program!
+----------------------------------------------------------
 
-    The LED throbs when there has been a failed software
-    :ref:`assertion <language-assert>`.
+The LED throbs when there has been a failed software :ref:`assertion
+<language-assert>`.
 
-    You can still reprogram by resetting the board and uploading
-    during the short window when the bootloader waits for a
-    program.
+You can still reprogram by resetting the board and uploading during
+the short window when the bootloader waits for a program.
 
-    To make this window longer (it can be hard to get the timing
-    right), use :ref:`perpetual bootloader mode
-    <troubleshooting-perpetual-bootloader>`.
+To make this window longer (it can be hard to get the timing right),
+use :ref:`perpetual bootloader mode
+<troubleshooting-perpetual-bootloader>`.
 
 My board is bricked! I can't upload via the bootloader no matter what!
+----------------------------------------------------------------------
 
-    Use the hardcoded serial STM32 serial bootloader to re-flash the
-    bootloader.
+Use the hardcoded serial STM32 serial bootloader to re-flash the
+bootloader.
 
-    .. TODO insert docs on reflashing the bootloader
+.. TODO insert docs on reflashing the bootloader
 
-    If it really is bricked, and you think it's our fault,
-    `contact us <http://leaflabs.com/contact>`_\ !
+If it really is bricked, and you think it's our fault, `contact us
+<http://leaflabs.com/contact>`_\ !
 
 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.
+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.
 
 The reset and D38/serial buttons don't seem to work reliably!
+-------------------------------------------------------------
 
-    A few rev3 boards shipped in May-June 2010 may have had unreliable
-    buttons; see the :ref:`errata page <errata>` for details.  `We're
-    happy to replace these for you <http://leaflabs.com/contact>`_\ !
+A few rev3 boards shipped in May-June 2010 may have had unreliable
+buttons; see the :ref:`errata page <errata>` for details.  `We're
+happy to replace these for you <http://leaflabs.com/contact>`_\ !
 
-.. _troubleshooting-ide-install:
 
-Installation problems
----------------------
+.. _troubleshooting-ide-install:
 
+=======================
+ Installation problems
+=======================
 
 I don't have root/administrator access!
+---------------------------------------
 
-    There are probably hacks or work-arounds to getting programs
-    uploaded without higher level system permissions.  If you can
-    access USB character devices (ACM or ttyUSB style), you should be
-    able to communicate with the Maple and reprogram using an FTDI
-    converter and the serial bootloader, but we haven't tried.
+There are probably hacks or work-arounds to getting programs uploaded
+without higher level system permissions.  If you can access USB
+character devices (ACM or ttyUSB style), you should be able to
+communicate with the Maple and reprogram using an FTDI converter and
+the serial bootloader, but we haven't tried.
 
-    .. TODO: be more helpful
+.. TODO: be more helpful
 
 [Linux] I don't use udev!
+-------------------------
 
-    There is probably a simple way to get autoconfiguration working
-    with devfs; in the meantime, you could try running the entire IDE
-    as root.
+There is probably a simple way to get autoconfiguration working with
+devfs; in the meantime, you could try running the entire IDE as root.
 
-    .. TODO: be more helpful
+.. TODO: be more helpful
 
 .. _troubleshooting-ide-usage:
 
-IDE problems
-------------
+==============
+ IDE problems
+==============
 
-[Mac OSX] The "Board" and "Serial Port" menu items are missing!
+[Mac OS X] The "Board" and "Serial Port" menu items are missing!
+----------------------------------------------------------------
 
-    Sometimes this happens if you try to compile or upload without
-    having a board selected.  The work-around is to restart the
-    IDE. Mysterious!
+Sometimes this happens if you try to compile or upload without having
+a board selected.  The work-around is to restart the IDE. Mysterious!
 
 .. _troubleshooting-compilation:
 
-Common compiler problems
-------------------------
+==========================
+ Common compiler problems
+==========================
 
 ``NullPointerException``
+------------------------
 
-    A classic! Make sure you have selected a board from the pulldown menu. 
+A classic! Make sure you have selected a board from the pulldown menu. 
 
-    .. TODO: remove when Python version is released
+.. TODO: remove when Python version is released
 
 ``undefined reference to setup()/loop()``
+-----------------------------------------
 
-    Your sketch/program either does not include one of the `setup
-    <setup()>`_ or `loop <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.
+Your sketch/program either does not include one of the `setup
+<setup()>`_ or `loop <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.  See also the :ref:`language <language>` documentation.
+You can start with an example program (to see one in the IDE, click on
+File > Examples > Stubs > BareMinimum) to get the basic structure.
+See also the :ref:`language <language>` documentation.
 
-    This is a common error when your entire sketch is blank. 
+This is a common error when your entire sketch is blank.
 
 ``error: 'Serial' was not declared in this scope``
+--------------------------------------------------
 
-    The classic Arduino has only one USART device and uses the unique
-    name "Serial" to control it. Larger devices like the Arduino Mega
-    and the Maple have multiple USARTS referred to as ``Serial1``,
-    ``Serial2``, etc. You probably want ``Serial2`` on the Maple;
-    that's the one connected to pins D0 and D1. See also the
-    :ref:`USART docs <usart>`.
+The classic Arduino has only one USART device and uses the unique name
+"Serial" to control it. Larger devices like the Arduino Mega and the
+Maple have multiple USARTS referred to as ``Serial1``, ``Serial2``,
+etc. You probably want ``Serial2`` on the Maple; that's the one
+connected to pins D0 and D1. See also the :ref:`USART docs <usart>`.
 
 ``File(s) not found``
+---------------------
 
-    There is an intermittent bug with the temporary directory build
-    system that on occasion will lose many of the ``#include``\ d
-    libmaple files. If you recompile everything, it should be fine.
+There is an intermittent bug with the temporary directory build system
+that on occasion will lose many of the ``#include``\ d libmaple
+files. If you recompile everything, it should be fine.
 
-    .. TODO remove when the Python version is released
+.. TODO remove when the Python version is released
 
 .. _troubleshooting-upload:
 
-Common upload problems
-----------------------
+========================
+ Common upload problems
+========================
 
 My program is too large!
+------------------------
 
-    First, make sure you're using the FLASH target instead of RAM;
-    there is several times more FLASH memory available for user
-    programs.
+First, make sure you're using the FLASH target instead of RAM; there
+is several times more FLASH memory available for user programs.
 
 ``No DFU capable USB device found``
+-----------------------------------
 
-    This probably means you don't have a Maple plugged in or powered on! 
+This probably means you don't have a Maple plugged in or powered on! 
 
 I have multiple Maples installed; how do I know which one will get flashed?
+---------------------------------------------------------------------------
 
-    Because the Maple IDE uses DFU to upload programs, you can't
-    select a particular Maple from the Serial Port menu to upload to a
-    particular board. There's no solution to this problem for now:
-    you'll have to just plug in the Maples one at a time. If this is a
-    real problem let us know and we'll see if we can come up with a
-    better solution.
+Because the Maple IDE uses DFU to upload programs, you can't select a
+particular Maple from the Serial Port menu to upload to a particular
+board. There's no solution to this problem for now: you'll have to
+just plug in the Maples one at a time. If this is a real problem let
+us know and we'll see if we can come up with a better solution.
 
 .. _troubleshooting-shell:
 
-Command-line issues
--------------------
+=====================
+ Command-line issues
+=====================
 
 My flash programs don't seem to stick; they behave like they are RAM!
+---------------------------------------------------------------------
 
-    Make sure you :command:`make clean` when switching between FLASH
-    and RAM targets; :command:`make` isn't smart enough to rebuild
-    everything that needs to be for the new target.
+Make sure you :command:`make clean` when switching between FLASH and
+RAM targets; :command:`make` isn't smart enough to rebuild everything
+that needs to be for the new target.
 
 [Linux] ``cdc_acm 3-1:1.0: no more free acm devices``
+-----------------------------------------------------
 
-    This is a nasty one! It means that all 32 possible CDC_ACM serial
-    devices (:file:`/dev/ttyACM25`, etc.) have been used up.
+This is a nasty one! It means that all 32 possible CDC_ACM serial
+devices (:file:`/dev/ttyACM25`, etc.) have been used up.
 
-    The usual cause is using a serial port monitor and not closing it
-    before restarting the Maple or uploading a new program.  The
-    operating system doesn't like that, and locks up that
-    device. After reset the Maple comes back up as a new device. If
-    you develop heavily and don't restart you'll blow right through
-    all 32 devices.
+The usual cause is using a serial port monitor and not closing it
+before restarting the Maple or uploading a new program.  The operating
+system doesn't like that, and locks up that device. After reset the
+Maple comes back up as a new device. If you develop heavily and don't
+restart you'll blow right through all 32 devices.
 
-    The lazy solution is to always close the monitor before
-    restarting, and if you get this error in :file:`dmesg` after a
-    dfu-util "Not Found" error, restart you machine.
+The lazy solution is to always close the monitor before restarting,
+and if you get this error in :file:`dmesg` after a dfu-util "Not
+Found" error, restart you machine.
 
-    The hacker solution is to restart your cdc_acm kernel module. On
-    Ubuntu 09.10, this goes a little something like::
+The hacker solution is to restart your cdc_acm kernel module. On
+Ubuntu 09.10, this goes a little something like::
 
-      $ sudo rmmod cdc-acm
-      $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko
+  $ sudo rmmod cdc-acm
+  $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko
 
 .. _troubleshooting-tips-tricks:
 
-Tips and Tricks
----------------
+=================
+ Tips and Tricks
+=================
 
 .. _troubleshooting-perpetual-bootloader:
 
-**Perpetual Bootloader Mode**
+Perpetual Bootloader Mode
+-------------------------
 
 In this mode, Maple stays a DFU device and does not jump to user code
 until the next reset.  This is useful for guaranteeing that your Maple
@@ -234,13 +215,13 @@ will be available for reprogramming.
 
 To put your Maple into perpetual bootloader mode:
 
-1. Plug your Maple into the USB port.
+#. Plug your Maple into the USB port.
 
-2. Hit the reset button on your Maple (it's the small button at the
-bottom left, labeled RESET).  Notice that it blinks quickly 6 times,
-then blinks slowly a few more times.
+#. Hit the reset button on your Maple (it's the small button at the
+   bottom left, labeled RESET).  Notice that it blinks quickly 6
+   times, then blinks slowly a few more times.
 
-3. Hit reset again, and this time push and hold the other button
-during the 6 fast blinks (the button is on the top right; it is
-labeled BUT). You can release it once the slow blinks start.
+#. Hit reset again, and this time push and hold the other button
+   during the 6 fast blinks (the button is on the top right; it is
+   labeled BUT). You can release it once the slow blinks start.