unix-toolchain: Break individual OS setup docs into separate files.

A monolithic quickstart is too unwieldy at this point. Move the
initial setup instructions into their own files to make it less
daunting and easier to read.

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

6 files changed, 524 insertions, 479 deletions

diff --git a/source/contents.rst b/source/contents.rst
index 7bb60b8..7be7aec 100644
--- a/source/contents.rst
+++ b/source/contents.rst
@@ -14,6 +14,9 @@ Contents in Full
    maple-ide-install
    ide
    unix-toolchain
+   unix-toolchain-linux-setup
+   unix-toolchain-osx-setup
+   unix-toolchain-win-setup
    whats-new
 
 .. _index-maple-programming:
diff --git a/source/epilog.rst b/source/epilog.rst
index e64103c..b548001 100644
--- a/source/epilog.rst
+++ b/source/epilog.rst
@@ -6,3 +6,9 @@
 .. _forum: http://forums.leaflabs.com
 .. _contact: http://leaflabs.com/contact/
 .. _contact us directly: http://leaflabs.com/contact/
+.. _Python: http://python.org/download/
+.. _PySerial: http://pyserial.sourceforge.net/
+.. _OpenMoko: http://openmoko.com/
+.. _Git: http://git-scm.com/
+.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util
+.. _easy_install: http://packages.python.org/distribute/easy_install.html
diff --git a/source/unix-toolchain-linux-setup.rst b/source/unix-toolchain-linux-setup.rst
new file mode 100644
index 0000000..2ba7689
--- /dev/null
+++ b/source/unix-toolchain-linux-setup.rst
@@ -0,0 +1,186 @@
+.. highlight:: sh
+
+.. _unix-toolchain-linux-setup:
+
+Unix Toolchain Linux Setup
+==========================
+
+This page contains instructions for setting up a Linux computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on:
+
+- Ubuntu 10.04 and 12.04 (32- and 64-bit)
+- Fedora 17 (64-bit)
+
+Generic instructions for other distributions are also provided. Please
+`contact`_ us with any updates for distros not already covered!
+
+.. contents:: Contents
+   :local:
+
+Collect and Install Tools
+-------------------------
+
+First, you'll need some tools.
+
+.. 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.
+
+**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**:
+
+  Install mandatory and optional tools with ::
+
+    $ sudo apt-get install build-essential git-core screen dfu-util python python-serial
+
+  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 ::
+
+    # 64-bit systems only!
+    $ sudo apt-get install ia32-libs
+
+  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+  with ::
+
+    # Optional
+    $ sudo apt-get remove brltty
+
+  Brltty provides braille access to the console.  It has been reported
+  to cause conflicts with Maple.
+
+**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**:
+
+  Install mandatory and optional tools with ::
+
+    $ sudo yum install screen git python pyserial dfu-util make
+
+  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 ::
+
+    # 64-bit systems only!
+    $ sudo yum install glibc.i686
+
+  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+  with one of these::
+
+    # Optional, 64-bit systems:
+    $ sudo yum erase brltty.x86_64
+
+    # Optional, 32-bit systems:
+    $ sudo yum erase brltty.i686
+
+  Brltty provides braille access to the console.  It has been
+  reported to cause conflicts with Maple.
+
+**Other Linux distributions**:
+
+  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`_ 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`_.
+
+  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/>`_).
+
+Fetch ``libmaple`` and Compiler Toolchain
+-----------------------------------------
+
+First, make a Git clone of :ref:`libmaple`::
+
+  $ cd ~
+  $ git clone git://github.com/leaflabs/libmaple.git libmaple
+
+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 the 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::
+
+  $ 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
+
+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:
+
+Install udev Rules
+------------------
+
+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
+
+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 plugdev with ::
+
+    $ sudo usermod -a -G plugdev $USER
+
+  then log back out and log back in.
+
+  After that's done, restart udev::
+
+    $ sudo restart udev
+
+**Red Hat-based distros**:
+
+  ::
+
+    $ udevadm control --reload-rules
+
+After restarting ``udev``, you'll need to unplug and re-plug your
+Maple.
+
+So far, so good?
+----------------
+
+Great! Move on by :ref:`compiling a sample program <toolchain-test>`.
+
+.. 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.
+
diff --git a/source/unix-toolchain-osx-setup.rst b/source/unix-toolchain-osx-setup.rst
new file mode 100644
index 0000000..3ed78af
--- /dev/null
+++ b/source/unix-toolchain-osx-setup.rst
@@ -0,0 +1,131 @@
+.. highlight:: sh
+
+.. _unix-toolchain-osx-setup:
+
+Unix Toolchain OS X Setup
+=========================
+
+This page contains instructions for setting up an OS X computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on OS X 10.6.4 and
+10.8.1.
+
+.. contents:: Contents
+   :local:
+
+Collect and Install Tools
+-------------------------
+
+First, you'll need some tools. [#fpackman]_
+
+* `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`_: 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`_: 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
+     uploads will not work.  ``dfu-util`` versions 0.6 and greater
+     should work.
+
+  If you prefer to compile from source, OpenMoko provides instructions
+  for `building dfu-util on OS X
+  <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_.
+
+  If you're in a hurry, you can use the dfu-util binary bundled with
+  `OpenMoko Flasher
+  <http://www.handheld-linux.com/wiki.php?page=OpenMoko%20Flasher>`_. To
+  do this, first `download OpenMoko Flasher
+  <http://projects.goldelico.com/p/omflasher/downloads/>`_, then move
+  it to your :file:`/Applications` folder (or wherever you
+  like). Let's say you save it as :file:`/Applications/OpenMoko
+  Flasher.app`.  Then the ``dfu-util`` binary resides in
+
+      :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
+
+  To run it from the command line, make a symbolic link to the binary
+  from some place on your ``PATH``::
+
+      $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \
+              /somewhere/on/your/PATH/dfu-util
+
+  .. note::
+
+    Copying the binary won't work, as it relies on dynamically linked
+    libraries found elsewhere in the .app bundle.
+
+  To make sure this worked, plug in your Maple, put it into
+  :ref:`perpetual bootloader mode
+  <troubleshooting-perpetual-bootloader>` (press RESET, then quickly
+  press and hold BUT for several seconds), and run ::
+
+      $ dfu-util -l
+
+  The output should look like this::
+
+      Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00"
+      Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000"
+
+* `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
+  extract the `latest version
+  <http://pypi.python.org/pypi/pyserial>`_, then install with ::
+
+      $ cd /path/to/pyserial-x.y
+      $ python setup.py build
+      $ sudo python setup.py install
+
+  PySerial is also available via `easy_install`_, so if you're
+  comfortable using that, you could alternatively install it with ::
+
+      $ easy_install pyserial
+
+Fetch ``libmaple`` and Compiler Toolchain
+-----------------------------------------
+
+First, make a `Git`_ clone of :ref:`libmaple`::
+
+  $ cd ~
+  $ git clone git://github.com/leaflabs/libmaple.git
+
+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 :ref:`GCC <arm-gcc>`).
+
+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 -xvf gcc-arm-none-eabi-latest-osx32.tar.gz
+  $ mv arm ~/libmaple/arm
+  $ export PATH=$PATH:~/libmaple/arm/bin
+
+After that's done, update your shell startup script so
+:file:`~/libmaple/arm/bin` stays in your ``PATH``.
+
+So far, so good?
+----------------
+
+Great! Move on by :ref:`compiling a sample program <toolchain-test>`.
+
+.. rubric:: Footnotes
+
+.. [#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. Your mileage may vary.
diff --git a/source/unix-toolchain-win-setup.rst b/source/unix-toolchain-win-setup.rst
new file mode 100644
index 0000000..5885741
--- /dev/null
+++ b/source/unix-toolchain-win-setup.rst
@@ -0,0 +1,160 @@
+.. highlight:: sh
+
+.. _unix-toolchain-win-setup:
+
+Unix Toolchain Windows Setup
+============================
+
+This page contains instructions for setting up a Windows computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on Windows 7 Home
+Premium.
+
+.. contents:: Contents
+   :local:
+
+Collect and Install Tools
+-------------------------
+
+First, you'll need some tools.
+
+* `GitHub for Windows <http://windows.github.com/>`_: this is a GUI
+  for `Git`_, the version control system we use for :ref:`libmaple`.
+
+  If you don't have one, you need to sign up for a (free) `GitHub
+  account <https://github.com/signup/free>`_.
+
+  .. note:: If you use Git from the command line, you can clone
+            libmaple with::
+
+              $ git clone git://github.com/leaflabs/libmaple.git
+
+            If you go this route, you don't need a GitHub account.
+
+* `Python`_: choose the **latest 2.7.x version**. (Python 3 works, but
+  you're on your own.)
+
+* `PySerial`_:  Choose the latest **pyserial-x.y-win32.exe version**.
+
+Fetch ``libmaple`` and Compiler Toolchain
+-----------------------------------------
+
+First, make a Git clone of the :ref:`libmaple` repository with the
+following steps:
+
+1. **Run GitHub for Windows**, and **sign in** using your GitHub
+   account.
+2. **Visit** `libmaple's GitHub page
+   <https://github.com/leaflabs/libmaple/>`_, and **sign in** to
+   GitHub in your web browser as well.
+3. **Click on the "Clone in Windows" button** on libmaple's GitHub
+   page, which looks like this:
+
+     .. figure:: /_static/img/github-clone-in-windows.png
+
+   Your browser may prompt you about what to do when you click the
+   "Clone in Windows" button. Choose the option that launches the
+   GitHub for Windows application.
+
+Next, you'll need to get some cross-compilers and other tools for
+building and uploading your programs:
+
+- `Download a .zip of the latest tools
+  <http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.zip>`_.
+
+- Extract the .zip, and **move the extracted "arm" folder into the
+  libmaple repository's folder**.
+
+  You can open the libmaple repository folder by right-clicking
+  libmaple in the main GitHub for Windows screen and choosing "open in
+  explorer":
+
+  .. figure:: /_static/img/win7-github-open-in-explorer.png
+     :align: center
+
+Update your PATH
+----------------
+
+You'll next need to configure your system to use the various tools
+you've downloaded and installed. Do that by adding the Python and
+``arm\bin`` directories to your PATH environment variable.
+
+If you've never set environment variables before, this section
+explains what to do.
+
+**Add Python to your PATH**:
+
+  Start by navigating to the folder where Python is installed on your
+  system (this is probably ``C:\Python27``). Right click on the folder
+  address, then choose "Copy address as text":
+
+  .. figure:: /_static/img/win7-copy-python-address.png
+     :align: center
+
+  Next, open your environment variables window: from the Start/Windows
+  menu, right click on Computer, then choose Properties > Advanced
+  System Settings > Environment Variables. Under the "User variables
+  for YOUR_USERNAME", look for PATH.
+
+  - If PATH is missing from the list, click "New...".
+
+    Under "Variable Name", write PATH. Under "Variable value", paste
+    the Python address you just copied, and click OK. The result looks
+    like this:
+
+    .. figure:: /_static/img/win7-python-path.png
+       :align: center
+
+  - If PATH is present in the list, click on it and choose "Edit...".
+
+    Go to the end of the "Variable value:" text box, type a semicolon
+    (the ``;`` character), and then paste the path you just
+    copied. Click OK.
+
+  Test that this worked by running the Git Shell program that came with
+  GitHub for Windows, then running ``python`` at the command prompt. You
+  should get a Python interpreter that looks like this:
+
+  .. figure:: /_static/img/win7-python-prompt.png
+     :align: center
+
+  If that worked, then close the window.
+
+**Add compiler toolchain to your PATH**:
+
+  Do this by adding the ``arm\bin`` directory (earlier instructions
+  had you move ``arm`` to the libmaple repository folder) to your PATH
+  environment variable in the same way you added Python.
+
+  Copy the address of the ``arm\bin`` folder by right-clicking on it
+  after navigating to it:
+
+  .. figure:: /_static/img/win7-copy-arm-bin-address.png
+     :align: center
+
+  The PATH environment variable should exist from when you added
+  Python to it, so make sure you choose "Edit..."  from the
+  environment variables window. Then paste the ``arm\bin`` address you
+  copied after typing a semicolon. The final result will look
+  something like this:
+
+  .. figure:: /_static/img/win7-python-arm-bin-path.png
+     :align: center
+
+  Click OK.
+
+Once that's done, **open a new Git Shell**, then type this at the
+prompt, and hit return::
+
+  cd libmaple
+
+.. warning:: You must open a new Git Shell window. If you use a shell
+             that's already open, then the changes to PATH you just
+             made won't be available, and the instructions in the next
+             section won't work.
+
+So far, so good?
+----------------
+
+Great! Go on to the next section, where you'll compile a program.
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index f767d7a..64fd9d1 100644
--- a/source/unix-toolchain.rst
+++ b/source/unix-toolchain.rst
@@ -11,469 +11,44 @@ This is a tutorial for using a standard Unix toolchain (``make``,
 who want to use :ref:`libmaple` directly. If you're just beginning, we
 recommend installing :ref:`Maple IDE <maple-ide-install>` instead.
 
-If you have success on an operating system not covered here, please
-post in the `forum`_ (or email us at info@leaflabs.com), so we can
-update this document.
-
 .. contents:: Contents
    :local:
-   :depth: 2
 
 Requirements
 ------------
 
-You need:
+We assume you've had success with the :ref:`Maple IDE <ide>` (this is
+important on Windows, as this document doesn't cover :ref:`driver
+installation <maple-ide-install-windows-drivers>`).
+
+At a minimum, you need:
 
 * Maple board
 * Mini-B USB cable
 * root (or Administrator) access to your computer.
 
+On Linux and OS X, you need to know how to use `bash
+<http://www.gnu.org/software/bash/>`_, and how to edit your .bashrc.
 Some experience using `GCC <http://gcc.gnu.org/>`_ and `make
 <http://www.gnu.org/software/make/>`_ is recommended, but is not
 required.
 
-On Linux and OS X, you need to know how to use `bash
-<http://www.gnu.org/software/bash/>`_, and how to edit your .bashrc.
-
-We assume you've had success with the :ref:`Maple IDE <ide>` (this is
-important on Windows, as this document doesn't cover :ref:`driver
-installation <maple-ide-install-windows-drivers>`).
-
-Setup
------
-
 .. _toolchain-linux-setup:
-
-Linux
-^^^^^
-
-1. Collect and Install Tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, you'll need some tools.
-
-.. 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.
-
-**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**:
-
-  Install mandatory and optional tools with ::
-
-    $ sudo apt-get install build-essential git-core screen dfu-util python python-serial
-
-  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 ::
-
-    # 64-bit systems only!
-    $ sudo apt-get install ia32-libs
-
-  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
-  with ::
-
-    # Optional
-    $ sudo apt-get remove brltty
-
-  Brltty provides braille access to the console.  It has been reported
-  to cause conflicts with Maple.
-
-**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**:
-
-  Install mandatory and optional tools with ::
-
-    $ sudo yum install screen git python pyserial dfu-util make
-
-  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 ::
-
-    # 64-bit systems only!
-    $ sudo yum install glibc.i686
-
-  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
-  with one of these::
-
-    # Optional, 64-bit systems:
-    $ sudo yum erase brltty.x86_64
-
-    # Optional, 32-bit systems:
-    $ sudo yum erase brltty.i686
-
-  Brltty provides braille access to the console.  It has been
-  reported to cause conflicts with Maple.
-
-**Other Linux distributions**:
-
-  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`_ 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`_.
-
-  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
-
-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::
-
-  $ 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
-
-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
-~~~~~~~~~~~~~~~~~~~~~
-
-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
-
-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 plugdev with ::
-
-    $ sudo usermod -a -G plugdev $USER
-
-  then log back out and log back in.
-
-  After that's done, restart udev::
-
-    $ sudo restart udev
-
-**Red Hat-based distros**:
-
-  ::
-
-    $ udevadm control --reload-rules
-
-After restarting ``udev``, you'll need to unplug and re-plug your
-Maple.
-
-So far, so good?
-~~~~~~~~~~~~~~~~
-
-Great! Test your setup by :ref:`compiling a sample program
-<toolchain-test>`.
-
 .. _toolchain-osx-setup:
-
-OS X
-^^^^
-
-These instructions have been tested successfully on OS X 10.6.4 and
-10.8.1.
-
-1. Collect and Install Tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, you'll need some tools. [#fpackman]_
-
-* `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`_: 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`_: 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
-     uploads will not work.  ``dfu-util`` versions 0.6 and greater
-     should work.
-
-  If you prefer to compile from source, OpenMoko provides instructions
-  for `building dfu-util on OS X
-  <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_.
-
-  If you're in a hurry, you can use the dfu-util binary bundled with
-  `OpenMoko Flasher
-  <http://www.handheld-linux.com/wiki.php?page=OpenMoko%20Flasher>`_. To
-  do this, first `download OpenMoko Flasher
-  <http://projects.goldelico.com/p/omflasher/downloads/>`_, then move
-  it to your :file:`/Applications` folder (or wherever you
-  like). Let's say you save it as :file:`/Applications/OpenMoko
-  Flasher.app`.  Then the ``dfu-util`` binary resides in
-
-      :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
-
-  To run it from the command line, make a symbolic link to the binary
-  from some place on your ``PATH``::
-
-      $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \
-              /somewhere/on/your/PATH/dfu-util
-
-  .. note::
-
-    Copying the binary won't work, as it relies on dynamically linked
-    libraries found elsewhere in the .app bundle.
-
-  To make sure this worked, plug in your Maple, put it into
-  :ref:`perpetual bootloader mode
-  <troubleshooting-perpetual-bootloader>` (press RESET, then quickly
-  press and hold BUT for several seconds), and run ::
-
-      $ dfu-util -l
-
-  The output should look like this::
-
-      Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00"
-      Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000"
-
-* `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
-  extract the `latest version
-  <http://pypi.python.org/pypi/pyserial>`_, then install with ::
-
-      $ cd /path/to/pyserial-x.y
-      $ python setup.py build
-      $ sudo python setup.py install
-
-  PySerial is also available via `easy_install`_, so if you're
-  comfortable using that, you could alternatively install it with ::
-
-      $ easy_install pyserial
-
-2. Fetch ``libmaple`` and Compiler Toolchain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, make a `Git`_ clone of :ref:`libmaple`::
-
-  $ cd ~
-  $ git clone git://github.com/leaflabs/libmaple.git
-
-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 :ref:`GCC <arm-gcc>`).
-
-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 -xvf gcc-arm-none-eabi-latest-osx32.tar.gz
-  $ mv arm ~/libmaple/arm
-  $ export PATH=$PATH:~/libmaple/arm/bin
-
-After that's done, update your shell startup script so
-:file:`~/libmaple/arm/bin` stays in your ``PATH``.
-
-So far, so good?
-~~~~~~~~~~~~~~~~
-
-Great! Test your setup by :ref:`compiling a sample program
-<toolchain-test>`.
-
 .. _toolchain-win-setup:
 
-Windows
-^^^^^^^
-
-These instructions have been tested successfully on Windows 7 Home
-Premium.
-
-1. Collect and Install Tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, you'll need some tools.
-
-* `GitHub for Windows <http://windows.github.com/>`_: this is a GUI
-  for `Git`_, the version control system we use for :ref:`libmaple`.
-
-  If you don't have one, you need to sign up for a (free) `GitHub
-  account <https://github.com/signup/free>`_.
-
-  .. note:: If you use Git from the command line, you can clone
-            libmaple with::
-
-              $ git clone git://github.com/leaflabs/libmaple.git
-
-            If you go this route, you don't need a GitHub account.
-
-* `Python`_: choose the **latest 2.7.x version**. (Python 3 works, but
-  you're on your own.)
-
-* `PySerial`_:  Choose the latest **pyserial-x.y-win32.exe version**.
-
-2. Fetch ``libmaple`` and Compiler Toolchain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, make a Git clone of the :ref:`libmaple` repository with the
-following steps:
-
-1. **Run GitHub for Windows**, and **sign in** using your GitHub
-   account.
-2. **Visit** `libmaple's GitHub page
-   <https://github.com/leaflabs/libmaple/>`_, and **sign in** to
-   GitHub in your web browser as well.
-3. **Click on the "Clone in Windows" button** on libmaple's GitHub
-   page, which looks like this:
-
-     .. figure:: /_static/img/github-clone-in-windows.png
-
-   Your browser may prompt you about what to do when you click the
-   "Clone in Windows" button. Choose the option that launches the
-   GitHub for Windows application.
-
-Next, you'll need to get some cross-compilers and other tools for
-building and uploading your programs:
-
-- `Download a .zip of the latest tools
-  <http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.zip>`_.
-
-- Extract the .zip, and **move the extracted "arm" folder into the
-  libmaple repository's folder**.
-
-  You can open the libmaple repository folder by right-clicking
-  libmaple in the main GitHub for Windows screen and choosing "open in
-  explorer":
-
-  .. figure:: /_static/img/win7-github-open-in-explorer.png
-     :align: center
-
-3. Update your PATH
-~~~~~~~~~~~~~~~~~~~
-
-You'll next need to configure your system to use the various tools
-you've downloaded and installed. Do that by adding the Python and
-``arm\bin`` directories to your PATH environment variable.
-
-If you've never set environment variables before, this section
-explains what to do.
-
-**Add Python to your PATH**:
-
-  Start by navigating to the folder where Python is installed on your
-  system (this is probably ``C:\Python27``). Right click on the folder
-  address, then choose "Copy address as text":
-
-  .. figure:: /_static/img/win7-copy-python-address.png
-     :align: center
-
-  Next, open your environment variables window: from the Start/Windows
-  menu, right click on Computer, then choose Properties > Advanced
-  System Settings > Environment Variables. Under the "User variables
-  for YOUR_USERNAME", look for PATH.
-
-  - If PATH is missing from the list, click "New...".
-
-    Under "Variable Name", write PATH. Under "Variable value", paste
-    the Python address you just copied, and click OK. The result looks
-    like this:
-
-    .. figure:: /_static/img/win7-python-path.png
-       :align: center
-
-  - If PATH is present in the list, click on it and choose "Edit...".
-
-    Go to the end of the "Variable value:" text box, type a semicolon
-    (the ``;`` character), and then paste the path you just
-    copied. Click OK.
-
-  Test that this worked by running the Git Shell program that came with
-  GitHub for Windows, then running ``python`` at the command prompt. You
-  should get a Python interpreter that looks like this:
-
-  .. figure:: /_static/img/win7-python-prompt.png
-     :align: center
-
-  If that worked, then close the window.
-
-**Add compiler toolchain to your PATH**:
-
-  Do this by adding the ``arm\bin`` directory (earlier instructions
-  had you move ``arm`` to the libmaple repository folder) to your PATH
-  environment variable in the same way you added Python.
-
-  Copy the address of the ``arm\bin`` folder by right-clicking on it
-  after navigating to it:
-
-  .. figure:: /_static/img/win7-copy-arm-bin-address.png
-     :align: center
-
-  The PATH environment variable should exist from when you added
-  Python to it, so make sure you choose "Edit..."  from the
-  environment variables window. Then paste the ``arm\bin`` address you
-  copied after typing a semicolon. The final result will look
-  something like this:
-
-  .. figure:: /_static/img/win7-python-arm-bin-path.png
-     :align: center
-
-  Click OK.
-
-Once that's done, **open a new Git Shell**, then type this at the
-prompt, and hit return::
-
-  cd libmaple
+Setup
+-----
 
-.. warning:: You must open a new Git Shell window. If you use a shell
-             that's already open, then the changes to PATH you just
-             made won't be available, and the instructions in the next
-             section won't work.
+You first need to set up your computer by installing and configuring
+various things. Don't fret! We've got detailed instructions, just for
+you.
 
-So far, so good?
-~~~~~~~~~~~~~~~~
+* :ref:`Linux <unix-toolchain-linux-setup>`
+* :ref:`OS X <unix-toolchain-osx-setup>`
+* :ref:`Windows <unix-toolchain-win-setup>`
 
-Great! Go on to the next section, where you'll compile a program.
+Come back when you're ready. We'll wait.
 
 .. _toolchain-test:
 
@@ -481,14 +56,19 @@ Test compilation
 ----------------
 
 Test that you've installed all the compilation tools correctly by
-running these commands in your shell::
+running the following commands in your shell.
+
+Windows users:
 
-  # Windows users:
-  #   - Type "cs-make" instead of "make"
-  #   - Don't type the "$", just the parts that come after
-  #
-  # Linux and OS X users:
-  #   - First get to libmaple with $ cd libmaple
+  - Don't type the ``$``'s, just the parts that come after.
+  - First get to libmaple by opening a Git Shell, then running ``cd libmaple``.
+  - **Always type** ``cs-make`` **instead of** ``make``.
+
+Linux and OS X users:
+
+  - Run these from the top-level libmaple directory.
+
+::
 
   $ cp main.cpp.example main.cpp
   $ make clean
@@ -567,12 +147,12 @@ Notes about the ``libmaple`` build
 These are just some miscellaneous notes that are good to know. Feel
 free to skip reading this section.
 
-- The ``dec`` field at the end under ``Final Size:`` gives the total
-  program size in bytes.  The ``text``, ``data``, and ``bss`` fields
-  respectively break down the size of the program into `code
-  <http://en.wikipedia.org/wiki/Code_segment>`_, `initialized data
-  <http://en.wikipedia.org/wiki/Data_segment>`_, and `zero-valued data
-  <http://en.wikipedia.org/wiki/.bss>`_.
+- The ``dec`` field at the end of the build output under ``Final
+  Size:`` gives the total program size in bytes.  The ``text``,
+  ``data``, and ``bss`` fields respectively break down the size of the
+  program into `code <http://en.wikipedia.org/wiki/Code_segment>`_,
+  `initialized data <http://en.wikipedia.org/wiki/Data_segment>`_, and
+  `zero-valued data <http://en.wikipedia.org/wiki/.bss>`_.
 
 - The long list of object files above the ``Final Size`` shows similar
   information on a per-file basis. You can use it to help slim down
@@ -598,8 +178,8 @@ Let's blow away the little example program and upload the interactive
 test session to your Maple.  This will let you interact with the Maple
 over a :ref:`USB serial port <usb>`.
 
-* Linux: you need udev rules set up :ref:`as described above
-  <toolchain-udev>`.
+* Linux: you need udev rules set up :ref:`as described in the setup
+  doc <toolchain-udev>`.
 
 * Windows: you need to :ref:`install the Maple's device drivers
   <maple-ide-install-windows-drivers>`.
@@ -629,8 +209,8 @@ Communicate over USB-Serial
 Now let's try out the interactive test session.  You need to connect
 to the board's serial port device file.
 
-* Linux: this looks like :file:`/dev/ttyACM*`
-* OS X: it looks like :file:`/dev/tty.usbmodem*`
+* Linux: this looks like :file:`/dev/ttyACM*`.
+* OS X: it looks like :file:`/dev/tty.usbmodem*`.
 * Windows: it will be :file:`COMx`, where ``x`` is some number.
 
 Try using one of these to find out which it is::
@@ -786,24 +366,3 @@ Let us know what you come up with! Mention `@leaflabs on Twitter
 <http://twitter.com/#!/leaflabs>`_, post in the `forum`_, join the the
 #leafblowers IRC channel on `freenode
 <http://freenode.net/irc_servers.shtml>`_, whatever. We love projects!
-
-.. _Python: http://python.org/download/
-.. _PySerial: http://pyserial.sourceforge.net/
-.. _OpenMoko: http://openmoko.com/
-.. _Git: http://git-scm.com/
-.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util
-.. _easy_install: http://packages.python.org/distribute/easy_install.html
-
-.. 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. Your mileage may vary.