Finish redoing the Unix toolchain.

General:

- Beef up "Start your own project" section, mention the example
  libmaple project page on the wiki.

- Tune the "Get updates" page to encourage people to run libmaple
  master.

- Fix the stupid JTAG section to acknowledge the fact that we don't
  officially support it. Mention the JTAG how-to on the wiki.

Linux:

- Better visual distinction for which instructions belong to which
  distributions.

- Fixed instructions for 64-bit distributions.

- Clean up libmaple/arm-none-eabi-* instructions and udev rules.

OS X:

- Minor language tweaks.

Windows:

- Mention (new at time of writing) libmaple script
  support/scripts/win-list-com-ports.py, which lists available serial
  ports.

- Audit other sections for missing Windows-specific instructions, and
  add them.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 280 insertions, 200 deletions

diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index 4fc21ea..e3d2a30 100644
--- a/source/unix-toolchain.rst
+++ b/source/unix-toolchain.rst
@@ -17,6 +17,7 @@ update this document.
 
 .. contents:: Contents
    :local:
+   :depth: 2
 
 Requirements
 ------------
@@ -27,12 +28,13 @@ with the IDE on your machine (this is important on Windows, as this
 document doesn't cover :ref:`driver installation
 <maple-ide-install-windows-drivers>`).
 
-On Linux and OS X, some previous experience with editing your shell
-startup script (.bashrc, .tcshrc, etc.) and using `GCC
+On Linux and OS X, you need to know how to use a shell and edit your
+shell startup script (.bashrc, .tcshrc, etc.). (The Windows
+instructions are more detailed, since we assume many Windows users
+will be newer to the Unix shell). Some experience using `GCC
 <http://gcc.gnu.org/>`_ and `make
-<http://www.gnu.org/software/make/>`_ is recommended. (The Windows
-instructions are more detailed, since we assume most Windows users
-will be new to the Unix shell).
+<http://www.gnu.org/software/make/>`_ is recommended, but is not
+required.
 
 Setup
 -----
@@ -42,117 +44,156 @@ Setup
 Linux
 ^^^^^
 
-**1. Collect and Install Tools**
+1. Collect and Install Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 First, you'll need some tools.
 
-On Debian-based distributions (including Ubuntu)::
+.. warning:: Due to firmware bugs in our :ref:`bootloader
+   <bootloader>`, you must use recent versions of ``dfu-util``, or
+   uploads will not work.  ``dfu-util`` versions 0.6 and greater
+   should work.
 
-  $ sudo aptitude install build-essential git-core wget screen dfu-util \
-                          openocd python python-serial
+**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**:
 
-On Red Hat-based distributions (including Fedora)::
+  Install mandatory and optional tools with ::
 
-  $ yum install screen wget git python pyserial dfu-util openocd make
+    $ sudo apt-get install build-essential git-core screen dfu-util python python-serial
 
-On other distributions, you'll need to figure this out for yourself
-(let us know if you do!).
+  On *64-bit distros only*, you will also need to install some 32-bit
+  libraries needed by the LeafLabs-supported :ref:`ARM GCC toolchain
+  <arm-gcc>` with ::
 
-The following are **mandatory**:
+    # 64-bit systems only!
+    $ sudo apt-get install ia32-libs
 
-* `Git <http://git-scm.com/>`_ is a distributed version control
-  system. We use it to track our source code.
+  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+  with ::
 
-* `dfu-util <http://wiki.openmoko.org/wiki/Dfu-util>`_ is a tool from
-  the `OpenMoko`_ project. It is used to upload programs to the Maple
-  over USB.
+    # Optional
+    $ sudo apt-get remove brltty
 
-.. warning:: Due to firmware bugs in our :ref:`bootloader
-   <bootloader>`, you must use recent versions of ``dfu-util``, or
-   uploads will not work.  ``dfu-util`` versions 0.6 and greater
-   should work.
+  Brltty provides braille access to the console.  It has been reported
+  to cause conflicts with Maple.
 
-.. _OpenMoko: http://openmoko.com/
+**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**:
 
-* `make <http://www.gnu.org/software/make/>`_ is used to direct
-  compilation.
+  Install mandatory and optional tools with ::
 
-* `Python <http://python.org>`_ is a programming language. Our reset
-  script, which sends control signals to the board which cause it to
-  to reset and enter the :ref:`bootloader <bootloader>`, is written in
-  Python (and works with Python 2 or 3). Most Linux distributions
-  these days include Python by default.
+    $ sudo yum install screen git python pyserial dfu-util make
 
-* `PySerial`_ is a Python library for interacting with serial port
-  devices. It's needed by our reset script. PySerial can also be
-  installed with `easy_install
-  <http://peak.telecommunity.com/DevCenter/EasyInstall>`_.
+  On *64-bit distros only*, you will also need to install 32-bit
+  libraries needed by the LeafLabs-supported :ref:`ARM GCC toolchain
+  <arm-gcc>` with ::
 
-The following are **optional**:
+    # 64-bit systems only!
+    $ sudo yum install glibc.i686
 
-* `wget <http://www.gnu.org/s/wget/>`_ is a tool for downloading files
-  from the command line. You could also pull in the required downloads
-  using a web browser.
+  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+  with one of these::
 
-* `screen <http://www.gnu.org/s/screen/>`_ is a screen manager we use
-  to connect to serial port devices.  Some popular alternatives are
-  Minicom and Kermit.
+    # Optional, 64-bit systems:
+    $ sudo yum erase brltty.x86_64
 
-* `openocd <http://openocd.sourceforge.net/web/>`_ is a `JTAG
-  <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control
-  program. It is used with an ARM JTAG device to do in-circuit
-  debugging (uploading new code, connecting to `GDB
-  <http://www.gnu.org/s/gdb/>`_, etc.).
+    # Optional, 32-bit systems:
+    $ sudo yum erase brltty.i686
 
-.. _OpenMoko: http://openmoko.com/
+  Brltty provides braille access to the console.  It has been
+  reported to cause conflicts with Maple.
+
+**Other Linux distributions**:
 
-**2. Fetch libmaple and Compiler Toolchain** ::
+  On other distributions, you'll need to figure this out for yourself
+  (please `contact`_ us if you have instructions for distros not
+  covered here!).
+
+  Mandatory tools:
+
+  * `Git`_ is a distributed version control system. We use it to track
+    our source code.
+
+  * `dfu-util`_ is a tool from the `OpenMoko`_ project. It is used to
+    upload programs to the Maple over USB.
+
+  * `Make <http://www.gnu.org/software/make/>`_ is used to direct
+    compilation.
+
+  * `Python <http://python.org>`_ is a programming language. Our reset
+    script, which sends control signals to the board which cause it to
+    to reset and enter the :ref:`bootloader <bootloader>`, is written
+    in Python (and works with Python 2 or 3). Most Linux distributions
+    these days include Python by default.
+
+  * `PySerial`_ is a Python library for interacting with serial port
+    devices. It's needed by our reset script. PySerial can also be
+    installed with `easy_install
+    <http://peak.telecommunity.com/DevCenter/EasyInstall>`_.
+
+  Optional tools:
+
+  * `screen <http://www.gnu.org/s/screen/>`_ is a screen manager used
+    here to connect to serial port devices.  (Some popular
+    alternatives are `Minicom
+    <http://alioth.debian.org/projects/minicom/>`_ and `Kermit
+    <http://www.kermitproject.org/>`_).
+
+2. Fetch ``libmaple`` and Compiler Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, make a Git clone of :ref:`libmaple`::
 
   $ cd ~
   $ git clone git://github.com/leaflabs/libmaple.git libmaple
-  $ cd libmaple
-  $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz
-  $ tar xvzf gcc-arm-none-eabi-latest-linux32.tar.gz
-  $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up
 
-In this step, you make a Git clone of the `libmaple repository
-<https://github.com/leaflabs/libmaple>`_, then download and extract
-the ARM compiler toolchain.
+Next, download the `Linux ARM GCC toolchain
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz>`_
+you'll use to build your programs. Extract the archive into a
+directory named :file:`arm`. Put resulting :file:`arm/bin`
+subdirectory somewhere in your ``PATH``. For example, if you have
+`wget <http://www.gnu.org/software/wget/>`_ installed, you can run::
 
-The directory :file:`arm/bin/` will need to be added to your ``PATH``;
-you can check that this worked by entering ``arm-none-`` and hitting
-tab to auto-complete (your shell should show a bunch of results).
-Regardless of where you put the toolchain, make sure to preserve its
-internal directory layout.
+  $ cd ~/libmaple
+  $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz
+  $ tar xvf gcc-arm-none-eabi-latest-linux32.tar.gz
+  $ export PATH=$PATH:~/libmaple/arm/bin
 
-After you're done, you'll probably want to update your shell startup
-script so :file:`~/libmaple/arm/bin` stays in your ``PATH``.
+You can check that this worked by entering ``arm-none-`` and hitting
+tab to auto-complete; your shell should show a bunch of results. After
+you're done, you'll probably want to update your shell startup script
+so the :file:`arm/bin` directory stays in your ``PATH``.
 
 .. _toolchain-udev:
 
-**3. Install udev Rules**
+3. Install udev Rules
+~~~~~~~~~~~~~~~~~~~~~
 
-From the libmaple directory, copy our udev rules to ``/etc/udev/rules.d``::
+From the libmaple directory, copy our udev rules [#fudev]_ to
+``/etc/udev/rules.d``::
 
   $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules
 
-On Debian, run ``$ groups``. Make sure the output includes "plugdev".
-If not, add yourself to that group. Then run ::
+Then restart udev.
+
+**Debian-based distros**:
+
+  Make sure you are in the plugdev group (e.g. by running ``$ groups``
+  and seeing if the output includes "plugdev").  If not, add yourself
+  to it (e.g. ``$ sudo usermod -a -G plugdev <your-username>``, then
+  log out and log back in). Then run::
+
+    $ sudo restart udev
 
-  $ sudo restart udev
+**Red Hat-based distros**:
 
-On Red Hat, run ::
+  ::
 
- $ udevadm control --reload-rules
+    $ udevadm control --reload-rules
 
-As a security precaution on Linux, unknown USB devices can only be
-accessed by root. This udev script identifies the Maple based on its
-vendor and product IDs, mounts it to :file:`/dev/maple`, and (on
-Debian-based distros) grants read/write permissions to the ``plugdev``
-group. After restarting ``udev`` you'll need to fully unplug or power
-cycle any Maples connected to the computer.
+After restarting ``udev``, you'll need to unplug and re-plug your
+Maple.
 
-**So far, so good?**
+So far, so good?
+~~~~~~~~~~~~~~~~
 
 Great! Test your setup by :ref:`compiling a sample program
 <toolchain-test>`.
@@ -164,24 +205,25 @@ OS X
 
 These instructions have been tested successfully on OS X 10.6.4.
 
-**1. Collect and Install Tools**
+1. Collect and Install Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You will need the following tools\ [#fpackman]_ to get started:
+First, you'll need some tools. [#fpackman]_
 
-* `XCode <http://developer.apple.com/technologies/xcode.html>`_: If
-  you're reading this, you've probably already got this. Provides
-  compilers and other basic tools of the trade.  While XCode was once
-  free of charge, Apple has since begun charging for it; if you'd
-  rather not pay, you can probably get by with just a `make
-  <http://www.gnu.org/software/make/>`_ binary.
+* `XCode <http://developer.apple.com/technologies/xcode.html>`_:
+  Provides compilers and other basic tools of the trade.  XCode was
+  once free of charge, but Apple has since begun charging for it. If
+  you'd rather not pay, you can probably get by with just a `make
+  <http://www.gnu.org/software/make/>`_ binary, but you're on your
+  own.
 
-* `Git <http://git-scm.com/>`_: All of our code is tracked by a
-  distributed versioning system called Git. A `Mac installer
+* `Git`_: All of our code is tracked by a distributed versioning
+  system called Git. A `Mac installer
   <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_
   is available.
 
-* `dfu-util <http://wiki.openmoko.org/wiki/Dfu-util>`_: A tool from
-  `OpenMoko`_ that we use to upload programs to the Maple over USB.
+* `dfu-util`_: A tool from `OpenMoko`_ that we use to upload programs
+  to the Maple over USB.
 
   .. warning:: Due to firmware bugs in our :ref:`bootloader
      <bootloader>`, you must use recent versions of ``dfu-util``, or
@@ -229,8 +271,8 @@ You will need the following tools\ [#fpackman]_ to get started:
 * `PySerial`_: our reset script (which sends control signals over the
   USB-serial connection to restart and enter the bootloader) is
   written in Python, and requires the PySerial library. Download and
-  untar the `latest version <http://pypi.python.org/pypi/pyserial>`_,
-  then install with ::
+  extract the `latest version
+  <http://pypi.python.org/pypi/pyserial>`_, then install with ::
 
       $ cd /path/to/pyserial-x.y
       $ python setup.py build
@@ -241,9 +283,10 @@ You will need the following tools\ [#fpackman]_ to get started:
 
       $ easy_install pyserial
 
-**2. Fetch libmaple and Compiler Toolchain**
+2. Fetch ``libmaple`` and Compiler Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You first need to clone libmaple::
+First, make a `Git`_ clone of :ref:`libmaple`::
 
   $ cd ~
   $ git clone git://github.com/leaflabs/libmaple.git
@@ -251,22 +294,22 @@ You first need to clone libmaple::
 Next, `download the cross-compilers
 <http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_
 you'll use to build libmaple and your own programs. (These are just
-special-purpose versions of GCC). Let's say you saved these as
+special-purpose versions of :ref:`GCC <arm-gcc>`).
 
-  :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz`
-
-You can unpack the archive and let the shell know where everything
-lives with ::
+Let's say you saved these into
+:file:`~/Downloads/gcc-arm-none-eabi-latest-osx32.tar.gz`. Then unpack
+the archive and tell the shell about its contents with::
 
   $ cd ~/Downloads
-  $ tar -xvzf gcc-blah-blah-osx32.tar.gz
+  $ tar -xvf gcc-arm-none-eabi-latest-osx32.tar.gz
   $ mv arm ~/libmaple/arm
   $ export PATH=$PATH:~/libmaple/arm/bin
 
-After that's done, you'll probably want to update your shell startup
-script so :file:`~/libmaple/arm/bin` stays in your ``PATH``.
+After that's done, update your shell startup script so
+:file:`~/libmaple/arm/bin` stays in your ``PATH``.
 
-**So far, so good?**
+So far, so good?
+~~~~~~~~~~~~~~~~
 
 Great! Test your setup by :ref:`compiling a sample program
 <toolchain-test>`.
@@ -278,33 +321,46 @@ Windows
 
 These instructions have been tested successfully on Windows XP SP3.
 
-1. First, you'll need Git, a distributed versioning system we use to
-track our source code. Follow the steps in `this great guide from
-GitHub <http://help.github.com/win-set-up-git/>`_.
+1. Collect and Install Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You'll need a few software tools for compiling and uploading programs.
+
+* `Git`_, a versioning system we use for :ref:`libmaple`.  Install Git
+  using the wonderful `Windows guide on GitHub
+  <https://help.github.com/articles/set-up-git#platform-windows>`_.
+
+  .. note:: These instructions use Git Bash, the command-line
+            interface to Git on Windows. You can use the GitHub for
+            Windows application instead, but we haven't tried.
+
+* `Install Python <http://python.org/download>`_.  Choose the latest
+  **2.7.x version**; Python 3 might work, but it's not tested.
 
-2. `Install Python <http://python.org/download>`_.  Choose the latest
-**2.7.x version**; Python 3 will not work.
+* `Install PySerial <http://pypi.python.org/pypi/pyserial>`_.  Choose
+  the latest **pyserial-x.y-win32.exe version** (or the "py3k" version
+  if you installed Python 3).
 
-3. `Install PySerial <http://pypi.python.org/pypi/pyserial>`_.  Choose
-the latest **pyserial-x.y-win32.exe version**; the "py3k" version will
-not work.
+2. Fetch ``libmaple`` and Compiler Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-4. Run Git Bash, and get :ref:`libmaple` by typing the following line
-and hitting return. (Do not type the "$".  We put these in to remind
-you that lines like this are for the Git Bash prompt). ::
+First, make a Git clone of :ref:`libmaple`. Do this by running Git
+Bash (which you installed in step 1), typing the following line, and
+hitting return. (Do not type the "$".  We put these in to remind you
+that lines like this are for the Git Bash prompt). ::
 
     $ git clone git://github.com/leaflabs/libmaple.git
 
 .. note:: Keep the Git Bash window open as you go.
 
-You now have the libmaple repository in the folder ``Documents and
+You now have the libmaple repository in the folder ``C:\Documents and
 Settings\<Your Name>``.
 
-5. Download this `archive of the CodeSourcery compiler toolchain
-<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.tar.gz>`_.
-When the download finishes, move the file into the libmaple directory.
-
-6. Type these two lines into the Git Bash prompt to go to the libmaple
+Next, download the `compilers and other tools
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.tar.gz>`_
+you'll use to build and upload your programs.  When the download
+finishes, move the file into the libmaple repository's folder. Then
+type these two lines into the Git Bash prompt to go to the libmaple
 folder and extract the archive::
 
     $ cd libmaple
@@ -312,14 +368,13 @@ folder and extract the archive::
 
 This will create a folder named "arm" inside the libmaple folder.
 
-7. Now you'll configure your system to use these tools. Type the
-following lines into the Git Bash prompt.
+You'll now configure your system to use these tools. Type the
+following lines into Git Bash.
 
 .. warning:: If you've installed Bash on your computer before starting
-   this guide, and have a ~/.bashrc already, these instructions will
-   overwrite it. If that is the case, we assume you know what you're
-   doing, and can modify the shell commands in this step appropriately
-   for your system.
+   this guide, and have a .bashrc already, typing these lines will
+   overwrite it. If that's the case, we assume you know what you're
+   doing, and can modify your .bashrc appropriately.
 
    If you're using Bash for the first time, don't worry about this
    warning.
@@ -333,13 +388,13 @@ following lines into the Git Bash prompt.
 .. note:: The "> " at the beginning of the second and third lines will
    appear automatically.
 
-In case that's hard to read, the part of the first line between
-``cat`` and ``bashrc`` is these five characters: space ( ), right
-angle bracket (>), tilde (~), forward slash (/), and period (.).
+   In case that's hard to read, the part of the first line between
+   ``cat`` and ``bashrc`` is these five characters: space ( ), right
+   angle bracket (>), tilde (~), forward slash (/), and period (.).
 
 For reference, here's a screenshot of what your Git Bash window should
-look like at this point (the output after the ``git clone`` line will
-be slightly different):
+look like at this point (the green prompts and output after the ``git
+clone`` line will be slightly different):
 
 .. _toolchain-git-bash-screenshot:
 
@@ -347,10 +402,13 @@ be slightly different):
    :align: center
    :alt: Git Bash screenshot
 
-8. Let's check that you completed the previous step correctly.  If you
-did, there should be a file called ".bashrc" (the period is supposed
-to be there) in the folder ``Documents and Settings\<Your Name>\``.
-Open this file in Notepad by right clicking on it and selecting "Open
+3. Check Your Setup
+~~~~~~~~~~~~~~~~~~~
+
+Let's check that you completed the previous step correctly.  If you
+did, there will be a file called ".bashrc" (the period is supposed to
+be there) in the folder ``Documents and Settings\<Your Name>\``.  Open
+this file in Notepad by right clicking on it and selecting "Open
 With...", like so:
 
 .. figure:: /_static/img/winxp-open-bashrc-with.png
@@ -365,12 +423,11 @@ The Notepad window should look like this:
    :alt: .bashrc in Notepad
 
 The little box at the end of the line is supposed to be there. Close
-the Notepad window (do not save any changes you may have made by
-accident).
-
-9. TODO download dfu-util.exe and put it in ``libmaple\arm\bin``.
+the Notepad window (don't save any changes you may have accidentally
+made).
 
-**So far, so good?**
+So far, so good?
+~~~~~~~~~~~~~~~~
 
 Great! Go on to the next section, where you'll compile a program.
 
@@ -380,10 +437,10 @@ Test compilation
 ----------------
 
 Get back into the libmaple directory (this tutorial assumes you put it
-in :file:`~/libmaple`) and test that you've installed all the
-compilation tools correctly (Windows users: use ``cs-make`` instead of
-``make``)::
+in :file:`libmaple` under your home directory) and test that you've
+installed all the compilation tools correctly::
 
+  # Note: Use "cs-make" instead of "make" on Windows
   $ cd ~/libmaple
   $ cp main.cpp.example main.cpp
   $ make clean
@@ -392,47 +449,35 @@ compilation tools correctly (Windows users: use ``cs-make`` instead of
 .. note:: These instructions are for the Maple.  If you're compiling
    for another board, you'll need to set a ``BOARD`` environment
    variable appropriately.  For example, to compile for Maple Mini (in
-   Bash), ::
+   Bash), run::
 
-       $ export BOARD=maple_mini
-       $ make
+     $ export BOARD=maple_mini
+     $ make
 
-   The ``BOARD`` for Maple RET6 edition is ``maple_RET6``.  You can
-   also use ::
+   You can also use the following, but you'll need to write the
+   ``BOARD=maple_mini`` part every time you call ``make`` (for ``make
+   install``, etc.)::
 
-       $ BOARD=maple_mini make
+     $ BOARD=maple_mini make
 
-   This will only set the environment variable for the duration of
-   that single compile.
+   To get a list of all boards, run ::
 
-If it all works out, you should end up seeing something like this::
+     $ make list-boards
 
-  find build -iname *.o | xargs arm-none-eabi-size -t
-     text    data     bss     dec     hex filename
-      482       4      24     510     1fe build/wirish/comm/HardwareSerial.o
-      260       0       0     260     104 build/wirish/comm/HardwareSPI.o
-       60       0       0      60      3c build/wirish/wirish.o
+   To make this setting permanent, put the ``export BOARD=maple_mini``
+   line in your .bashrc.
 
-  [...]
-
-     2196       0       1    2197     895 build/libmaple/usb/usb_lib/usb_core.o
-     1904       0       0    1904     770 build/libmaple/usb/usb_lib/usb_regs.o
-       56       0       0      56      38 build/libmaple/usb/usb_lib/usb_init.o
-      344       0       0     344     158 build/libmaple/usb/usb_hardware.o
-     6637       0      58    6695    1a27 build/main.o
-    21499     201     391   22091    564b (TOTALS)
+If all goes well, you should see a bunch of output, then something
+like this::
 
   Final Size:
-  arm-none-eabi-size build/maple.out
-     text    data     bss     dec     hex filename
-    21824     200     552   22576    5830 build/maple.out
-  Flash build
+     text          data     bss     dec     hex filename
+    13164          1704     552   15420    3c3c build/maple.elf
 
 The ``dec`` field at the end gives the total program size in
-bytes. The long listing of object files above the ``Final Size`` helps
-to identify bloated code.  As you write larger projects, you may find
-that they use too much space. If that happens, the file-by-file
-listing will help you track down the culprits.
+bytes. The long table of object files above the ``Final Size`` shows
+similar information on a per-file basis. You can use it to help slim
+down programs that use too much space.
 
 .. _toolchain-upload:
 
@@ -445,7 +490,7 @@ over a :ref:`USB serial port <usb>`. If you're on Linux, then before
 executing ``make install``, you'll want to have the udev rules setup
 :ref:`as described above <toolchain-udev>`.
 
-Plug in your Maple using the Mini-B USB cable; then run ::
+Plug in your Maple using the Mini-B USB cable, then run ::
 
   $ cd ~/libmaple
   $ cp examples/test-session.cpp main.cpp
@@ -465,10 +510,10 @@ Communicate over USB-Serial
 ---------------------------
 
 Now let's try out the interactive test session.  The serial port
-device file should look something like :file:`/dev/ttyACMXXX` on Linux
-or :file:`/dev/tty.usbmodemXXX` on OS X, but ``XXX`` will vary
-depending on your system.  Try using one of these to find out which it
-is::
+device file will look something like :file:`/dev/ttyACMXXX` on Linux,
+:file:`/dev/tty.usbmodemXXX` on OS X, or :file:`COMx` on Windows, but
+``XXX`` will vary depending on your system.  Try using one of these to
+find out which it is::
 
   # Linux
   $ ls /dev/ttyACM*
@@ -476,18 +521,25 @@ is::
   # OS X
   $ ls /dev/tty.usbmodem*
 
-To open up a session, run ::
+  # Windows, works from libmaple directory
+  $ python support/scripts/win-list-com-ports.py
+
+To open up a session on Linux or OS X, run ::
 
   $ screen /dev/ttyXXX
 
+(On Windows, you will need to use a separate program, such as Maple
+IDE's serial console or `PuTTY
+<http://www.chiark.greenend.org.uk/~sgtatham/putty/>`_.)
+
 If the interactive test program built and uploaded correctly,
 ``screen`` won't report any errors, and will present you an empty
 terminal.  Your board is now waiting for you to send it a command.
 Type ``h`` to print a list of commands which demonstrate various
 features; type any command's letter to run it.
 
-To exit the screen session, type :kbd:`C-a C-\\` (control-a, followed
-by control-backslash) on Mac, or :kbd:`C-a k` (control-a k) on Linux,
+To exit the screen session, type :kbd:`C-a k` (control-a k) on Linux,
+or :kbd:`C-a C-\\` (Control-a, followed by Control-backslash) on OS X,
 and type ``y`` when prompted if you're sure.
 
 .. note::
@@ -529,25 +581,27 @@ This will produce a build-time library in the file
 link against that library, and that the libmaple sources are in your
 include path.
 
-At a minimum, your include path should contain the directories
-:file:`~/libmaple/libmaple` and :file:`~/libmaple/wirish/`.  If you
-want to use one of the officially supported :ref:`libraries
-<libraries>`, those live under :file:`~/libmaple/libraries/`.  The
-main include file for the Wirish library is
-:file:`~/libmaple/wirish/wirish.h`.
+There is also a page on `starting a project with the Unix toolchain
+<http://wiki.leaflabs.com/index.php?title=Starting_A_Project_%28No_IDE%29>`_
+on the `LeafLabs wiki <http://wiki.leaflabs.com>`_ that you may find
+useful.
 
 Get updates
 -----------
 
 We update libmaple fairly frequently with bugfixes and other
-improvements.  In order get access to these in your local copy of
-the repository, you should periodically update it with::
+improvements.  In order get access to these in your local copy of the
+repository, you should periodically update it with::
 
   $ cd ~/libmaple
   $ git pull
 
-We keep releases of libmaple and the Maple IDE in lockstep, so any
-IDE updates will have corresponding library updates.  Our `blog
+We do our best to keep the master libmaple branch on GitHub free from
+broken or half-finished code, so don't be too scared running the
+latest and greatest. If you do, please report any bugs or regressions!
+
+We keep releases of libmaple and the Maple IDE in lockstep, so any IDE
+updates will have corresponding library updates.  Our `blog
 <http://leaflabs.com/blog/>`_ is the place to watch for major
 releases; an `RSS feed <http://leaflabs.com/blog/feed/>`_ is
 available.
@@ -559,14 +613,32 @@ notifications about bleeding-edge development.
 
 .. _toolchain-openocd:
 
-Debug with OpenOCD
-------------------
-
-TODO. For now see `this great guide
-<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se, and
-the ``jtag`` Makefile target.  There is also a `JTAG How-To
-<http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ page on
-our `wiki <http://wiki.leaflabs.com>`_ which you may find useful.
+(Optional) Upload/Debug with JTAG/SWD
+-------------------------------------
+
+Advanced users will wish to use a JTAG (or SWD) dongle for uploading
+and debugging their programs. A big advantage to this approach is that
+it lets you use `GDB
+<http://www.gnu.org/software/gdb/documentation/>`_ to single-step
+through your code, inspect variables, etc.
+
+You can build your projects for JTAG or SWD upload with the ``jtag``
+Makefile target. Instead of compiling with ``make``, compile with
+``make jtag``. Then use your method of choice to upload the resulting
+program, which will be in ``build/<your-board>.elf`` in the libmaple
+directory.
+
+.. warning:: Uploading code built with the ``jtag`` target will
+   overwrite the :ref:`bootloader <bootloader>`. This is a good thing
+   -- since you're using another upload method, this lets you use the
+   Flash and RAM the bootloader ordinarily reserves for itself. You
+   can always :ref:`reflash the bootloader <bootloader-reflashing>`
+   later.
+
+While LeafLabs doesn't officially support any particular way of using
+JTAG with Maple, there is a `JTAG How-To
+<http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ on the
+`LeafLabs wiki <http://wiki.leaflabs.com>`_ that you may find useful.
 
 .. _toolchain-exuberantly:
 
@@ -579,12 +651,20 @@ Let us know what you come up with! Mention `@leaflabs on Twitter
 <http://freenode.net/irc_servers.shtml>`_, whatever. We love projects!
 
 .. _PySerial: http://pyserial.sourceforge.net/
+.. _OpenMoko: http://openmoko.com/
+.. _Git: http://git-scm.com/
+.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util
 
 .. rubric:: Footnotes
 
+.. [#fudev] As a security precaution on Linux, unknown USB devices can
+   only be accessed by root. This udev script identifies the Maple
+   based on its vendor and product IDs, mounts it to
+   :file:`/dev/maple`, and (for Debian-based distros) grants
+   read/write permissions to the ``plugdev`` group.
+
 .. [#fpackman] Some of these software packages might be available on
    `MacPorts <http://www.macports.org/>`_ or `Homebrew
    <http://mxcl.github.com/homebrew/>`_. The author had some bad
    experiences with MacPorts a few years ago, though, and hasn't
-   touched a package manager on OS X since. Of course, your mileage
-   may vary.
+   touched a package manager on OS X since. Your mileage may vary.