Split up README into separate files.

The README is pretty long (over 1500 words). Nobody's going to read
that. Make it short, and put the long-winded bullshit into other files
that are clearly labeled as being for docs maintainers.

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

3 files changed, 327 insertions, 335 deletions

diff --git a/README b/README
index c11fc72..60fb888 100644
--- a/README
+++ b/README
@@ -1,344 +1,24 @@
-Introduction
-------------
-
-This repository contains reStructuredText (reST) source files used to
-generate the documentation for LeafLabs' libmaple and Maple IDE
-projects.  For more information on these projects, see their GitHub
-pages:
-
-    https://github.com/leaflabs/libmaple
-    https://github.com/leaflabs/maple-ide
-
-While the two projects are developed separately, they are released in
-lockstep, and Maple IDE depends upon libmaple.  (libmaple doesn't
-depend on Maple IDE).
-
-The generated documentation for the latest libmaple and Maple IDE
-release is available online in HTML form:
+This repository contains source files used to generate the
+documentation for LeafLabs' libmaple and Maple IDE projects [*]. The
+HTML documentation generated from these sources is available online:
 
     http://leaflabs.com/docs/
 
-The web interface is the recommended way for users to read the
-documentation.  Older versions are available as well:
-
-    http://static.leaflabs.com/pub/leaflabs/maple-docs/
-
-This file contains instructions for generating the HTML files.  It
-also contains guidelines for the documentation's maintainers.
-
-About the Documentation
------------------------
-
-The docs are written in Sphinx's extensions to reStructuredText
-(reST).  You can read more about Sphinx here:
-
-    http://sphinx.pocoo.org/tutorial.html
-
-Much of the documentation is pulled out of the libmaple source code.
-libmaple documents itself using Doxygen:
-
-    http://doxygen.org
-
-We use a Sphinx plugin called Breathe to parse Doxygen's XML output
-into a form usable by Sphinx.  You can read more about Breathe here:
-
-    http://michaeljones.github.com/breathe/
-
-Documentation Build Steps
--------------------------
-
-First, you will need to install some dependencies (Doxygen, Sphinx,
-and Breathe).
-
-1. You need a recent-ish version of Doxygen in your PATH:
-
-    http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
-
-2. Install Breathe, which does Doxygen-to-Sphinx conversion:
-
-   Read/write version (for LeafLabs developers):
-
-    $ git clone git@github.com:leaflabs/breathe.git
-
-   Read-only version (for non-LeafLabs developers):
-
-    $ git clone git://github.com/leaflabs/breathe.git
-
-   After that's done, set an environment variable BREATHE_HOME to
-   point to where you downloaded it.  Something like this on bash:
-
-    $ export BREATHE_HOME=/path/to/breathe/repo/
-
-   (You'll want to put this in your shell startup script).
-
-3. Install Sphinx.
-
-   From source or .egg:
-
-    http://pypi.python.org/pypi/Sphinx#downloads
-
-   Via easy_install:
-
-    $ sudo easy_install -U Sphinx
-
-   You need Sphinx version >= 1.0.6.
-
-You are now ready to build the documentation.  First, you'll produce
-Doxygen XML output, then you can generate the HTML documentation.
-
-1. Before the first time you run Sphinx (and any time the Doxygen
-   comments in the libmaple source code are changed), you'll need to
-   rebuild libmaple's Doxygen XML output.  That is, from within the
-   libmaple repository (i.e., NOT THIS REPOSITORY), run:
-
-    $ make doxygen
-
-2. Finally, you can build the documentation (in this folder):
-
-    $ make html
-
-   On Windows, use the batch file make.bat instead.
-
-  As of 8 September 2011, building the docs generates a bunch of
-  errors/warnings.  Most of these are spurious and appear to be
-  Breathe's fault.  C'est la vie.
-
-Reading and Modifying the Documentation
----------------------------------------
-
-Just point your web browser at the file
-
-  build/html/index.html
-
-For the most part, the file build/html/foo.html is built from
-source/foo.rst.  (The index is an exception, because we needed to
-hand-hack the HTML to get the "Contents at a Glance" section to look
-nice).
-
-Read more about Sphinx and use the existing docs source as an example
-when writing yours.  The directory tmpl/ contains template ReST files
-you should sometimes use when creating a new page, in order to keep
-the style consistent.
-
-The file source/conf.py is the Sphinx configuration file; you can go
-read it for more information about our setup.
-
-All of the documentation which isn't pulled out of source code
-comments lives in source/.  The directory source/_static/ is for
-static content (like style sheets); source/_templates/ is meant to
-contain Sphinx templates.
-
-The remaining sections describe what to do under various circumstances
-when modifying or building the docs.
-
-Adding a New Board
-------------------
-
-Adding documentation for a new board is not just a matter of shoving a
-file for it into source/hardware/!
-
-- Various places in the docs link to particular kinds of pin maps for
-  each board.  When you add a new board, you must update these as
-  well.  Here's the list; please keep it current (files are relative
-  to the source/ directory):
-
-  * external-interrupts.rst: EXTI line pin maps
-  * timers.rst: timer pin maps
-  * adc.rst: low-noise ADC banks
-  * usart.rst: USART pin maps
-  * gpio.rst: master pin maps
-  * bootloader.rst: flashing a custom bootloader
-
-- The quickstart document may not explain how to use the new board.
-  If the board is different enough, a new, special-purpose quickstart
-  may need to be written for it.  Therefore, read the quickstart in
-  its entirety and update it appropriately.
-
-  Take this step seriously.  The quickstart is the first thing users
-  read when starting out, and first impressions matter.
-
-Building Documentation for a Release
-------------------------------------
-
-This is the procedure to follow when building the documentation for a
-versioned release (as such, it's mostly intended for LeafLabs people).
+The above URL is the recommended way for users to read the
+documentation.  The docs for the latest release are always available
+there.
 
-Read the following "Background" section if you've never done this
-before (or haven't done it in a while; things change).  Then do the
-steps in the "Preparation" and "Cutting the Release" sections that
-follow it.
+Older versions are here:
 
-If you're bugfixing the docs for a release that's already been
-shipped, skip to "Maintaining a Release", below.
-
-   ~~~~~~~~~~
-   Background
-   ~~~~~~~~~~
-
-As a lightweight form of issue tracking, the documentation sources are
-sprinkled (not to say "littered") with comments that begin with FIXME
-or TODO, optionally followed by [milestone].
-
-Here's a hypothetical example:
-
-    .. TODO [1.4.0] Replace this section; new API is incompatible with 1.3.7
-
-This means you should replace the docs section following the comment
-before you build the HTML for version 1.4.0.
-
-Here's a command line you can use on OS X and Linux to list the TODOs
-in the documentation sources (run it from the same directory as this
-README):
-
-    $ find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)'
-
-You can use the following to temporarily alias the above mouthful to
-'todos':
-
-    $ alias todos="find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)'"
-
-Then you can just run
-
-    $ todos
-
-to measure the joy that awaits you.
-
-Windows users: I'm not sure what the equivalent of grep is on your
-system.  If you're using Git, I presume you've got a Bash shell
-available to you due to msysgit; try running the above commands there.
-
-BE ADVISED: that only finds the comments embedded within .rst files.
-You also need to check for these in source/conf.py; there may be
-others.  If you have ack (which might be called "ack-grep" on your
-system) installed, you can instead use
-
-    $ ack --type-set rst=.rst --type-set txt=.txt --ignore-dir=build '(FIXME|TODO)'
-
-to get the same output, but for all the file types we care about.
-
-    ~~~~~~~~~~~
-    Preparation
-    ~~~~~~~~~~~
-
-- FINISH THE FIXMEs/TODOs FOR THE CURRENT RELEASE!
-
-  You may violate assumptions made elsewhere in the documentation if
-  you don't.  This can lead to incoherent or incorrect documentation,
-  which is usually worse than none at all.
-
-  If the release you're building is vA.B.C, you can see the relevant
-  TODOs with:
-
-      $ todos | grep A\.B\.C
-
-  If you find that you really can't finish the TODO, you should bump
-  the version number in the comment.  Don't do this out of laziness.
-  Seriously, don't.  We may have made promises to the users about what
-  would happen when, and you might be breaking them.
-
-- Pick the low-hanging fruit on any other FIXMEs/TODOs.
-
-- Ask Git to tell you what's happened since the most recent libmaple
-  release, and make sure that any major, potentially
-  backwards-incompatible, etc. changes are appropriately documented.
-
-  You can use three dots ("...") between the git tags for those
-  releases in concert with "git log --oneline" to do this.
-
-  For instance, from the libmaple repository, you can use the
-  following to tell you what happened in between 0.0.9 and 0.0.10:
-
-      $ git log --oneline 0.0.9...0.0.10
-
-  As an example of what the output might cause you to do, consider the
-  following line (which appears in the output for 0.0.9...0.0.10):
-
-      4941335 Adding rcc_dev_clk(), an accessor for a peripheral's clock line.
-
-  Did the author of that commit (or some other interested party)
-  remember to pull in the documentation for rcc_dev_clk() into the
-  libmaple API page for rcc.h?  Go check!
-
-- Do something similar for Maple IDE.  The IDE changes a lot more
-  slowly, so there should be less to do.
-
-    ~~~~~~~~~~~~~~~~~~~
-    Cutting the Release
-    ~~~~~~~~~~~~~~~~~~~
-
-- Make a release branch in Git.  For release A.B.C, call it
-  vA.B.C-maintenance.  You spell that
-
-      $ git checkout -b vA.B.C-maintenance
-
-  DON'T MAKE A TAG.  There are inevitably mistakes in the docs, some
-  of which will be noticed and corrected, making a fixed tag useless.
-  When you correct the errors, you'll need to update this branch,
-  possibly also cherry-picking or otherwise adding into master.  See
-  "Maintaining the Release", below.
-
-- Do all the TODOs which must happen for _every_ release. (These are
-  distinct from the ones that must happen for some _particular_
-  release).  You can find most of these with
-
-      $ todos | grep RELEASE
-
-  However, you'll also need to check source/conf.py, as e.g. a
-  release's configuration file needs to have a version entered into
-  it.
-
-  Don't forget to commit your changes.
-
-- Run "$ make mrproper" from the libmaple directory, and "$ make
-  clean" from this directory, in order to wipe out old docs.
-
-- Finally, you can actually build the docs.  "$ make doxygen" from
-  libmaple followed by "$ make html" from here.  The sources you want
-  will be in build/html.  Wooo!  You're done!  Distribute the results
-  appropriately (e.g. by bundling them with the IDE release).
-
-  Don't forget to push the release branch to the leaflabs-docs repo on
-  GitHub.
-
-Maintaining a Release
----------------------
-
-So a released version's documentation contains unforgivable lies, huh?
-It needs to be updated RIGHT AWAY, you say?  Here's what you do:
-
-- Check out the release branch for the version of the docs you care
-  about (see "Cutting the Release", above).
-
-- Make your changes.
-
-- Rebuild the docs (see the last two steps in "Cutting the Release")
-  and look at the changed pages.
-
-- If your changes also need to happen on the master branch, make them
-  appropriately.
-
-  Advice: git cherry-pick is your friend.  Let's say you're on branch
-  "vX.Y.Z-maintenance", and you want to get commit C onto master:
-
-             o---C  vX.Y.Z-maintenance
-            /
-      -o---o---o---o  master
-
-  The recipe is:
-
-      $ git checkout master
-      $ git cherry-pick C
-
-  Which (if there are no conflicts) will result in:
-
-             o---C  vX.Y.Z-maintenance
-            /
-      -o---o---o---o---C'  master
+    http://static.leaflabs.com/pub/leaflabs/maple-docs/
 
-  Where C' performs the same changes as C.
+The file README-building.txt explains how to build the HTML docs.
 
-- Push your fixes to GitHub.
+The file README-maintainers.txt contains important information for
+maintainers of the documentation (e.g. how to add docs for a new
+board, how to cut a release version of the docs, etc.).
 
-- Distribute the updated docs.  These are world-visible here:
+[*] libmaple and Maple IDE themselves are in separate repositories:
 
-      http://static.leaflabs.com/pub/leaflabs/maple-docs/
+    https://github.com/leaflabs/libmaple
+    https://github.com/leaflabs/maple-ide
diff --git a/README-building.txt b/README-building.txt
new file mode 100644
index 0000000..9a1a1ac
--- /dev/null
+++ b/README-building.txt
@@ -0,0 +1,103 @@
+This file explains how to build the HTML documentation. As such, it's
+probably only useful to LeafLabs developers. Users can read the HTML
+for the latest release here:
+
+    http://leaflabs.com/docs/
+
+Install Dependencies
+--------------------
+
+First, you will need to install some dependencies (Doxygen, Sphinx,
+and Breathe).
+
+1. Much of the documentation is pulled out of the libmaple source
+   code's Doxygen comments, so you need a recent-ish version of
+   Doxygen in your PATH:
+
+    http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+
+2. Documentation not taken from the libmaple sources is written in
+   Sphinx's extensions to the reStructuredText (reST) markup language.
+   (More about Sphinx: http://sphinx.pocoo.org/tutorial.html).
+
+   These are your choices for how to install Sphinx:
+
+   - From source or .egg:
+     http://pypi.python.org/pypi/Sphinx#downloads
+
+   - Via easy_install:
+     $ sudo easy_install -U Sphinx
+
+   You need Sphinx version >= 1.0.6.
+
+3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output
+   into a form usable by Sphinx. (More about Breathe:
+   http://michaeljones.github.com/breathe/).
+
+   LeafLabs sometimes patches Breathe for the purposes of building our
+   docs, so clone the LeafLabs Breathe tree from GitHub (somewhere
+   else on your system, NOT in the leaflabs-docs repo):
+
+   - LeafLabs developers, clone with push permissions:
+     $ git clone git@github.com:leaflabs/breathe.git
+
+   - Everyone else, clone without them:
+     $ git clone git://github.com/leaflabs/breathe.git
+
+   After that's done, set an environment variable BREATHE_HOME to
+   point to your clone.  Something like this in Bash:
+
+    $ export BREATHE_HOME=/path/to/breathe/repo/
+
+   (You'll want to put this in your shell startup script.)
+
+Build the Docs
+--------------
+
+You are finally ready to build the documentation.  First, you'll
+produce Doxygen XML output, then you can generate the final HTML docs.
+
+1. Before the first time you run Sphinx (and any time the Doxygen
+   comments in the libmaple source code are changed), you'll need to
+   re-run doxygen on libmaple.
+
+    $ cd /path/to/libmaple
+    $ make doxygen
+
+   Doxygen will yell at you a lot; it's generally safe to ignore it.
+
+2. Finally, you can build the HTML (in the leaflabs-docs repository):
+
+    $ cd /path/to/leaflabs-docs
+    $ make html
+
+   On Windows, you can supposedly use the batch file make.bat instead.
+
+   Breathe will yell at you a lot; it's often safe to ignore this,
+   too. C'est la vie.
+
+Read and Modify the Docs
+------------------------
+
+Point your web browser at the file
+
+  build/html/index.html
+
+For the most part, the file build/html/foo.html is built from
+source/foo.rst.  (The index is an exception, because we needed to
+hand-hack the HTML to get the "Contents at a Glance" section to look
+nice).
+
+All of the documentation which isn't pulled out of libmaple's Doxygen
+comments lives in source/.  The directory source/_static/ is for
+static content (like style sheets); source/_templates/ is meant to
+contain Sphinx templates.
+
+Read more about Sphinx and use the existing leaflabs-docs source for
+examples when writing new docs.  The directory tmpl/ contains template
+ReST files you should sometimes use when creating a page that follows
+a pattern (like a libmaple API page), in order to keep the style
+consistent.
+
+The file source/conf.py is the Sphinx configuration file; you can go
+read it for more information about our setup.
diff --git a/README-maintainers.txt b/README-maintainers.txt
new file mode 100644
index 0000000..90ebfb5
--- /dev/null
+++ b/README-maintainers.txt
@@ -0,0 +1,209 @@
+This file contains information useful for the documentation's
+maintainers. As such, it's probably only useful to LeafLabs
+developers. Users can read the HTML for the latest release here:
+
+    http://leaflabs.com/docs/
+
+Things you can learn how to do from this file:
+
+- Cut a release version
+- Fix errors in/otherwise maintain the current docs release
+- Add docs for a new board
+
+Building Documentation for a Release
+------------------------------------
+
+This is the procedure to follow when building the documentation for a
+versioned release.
+
+Read the following "Background" section if you've never done this
+before (or haven't done it in a while; things change).  Then do the
+steps in the "Preparation" and "Cutting the Release" sections that
+follow it.
+
+If you're bugfixing the docs for a release that's already been
+shipped, skip to "Maintaining a Release", below.
+
+   ~~~~~~~~~~
+   Background
+   ~~~~~~~~~~
+
+As a lightweight form of issue tracking, the documentation sources are
+sprinkled (not to say "littered") with comments that begin with FIXME
+or TODO, optionally followed by [milestone].
+
+Here's a hypothetical example:
+
+    .. TODO [1.4.0] Replace this section; new API is incompatible with 1.3.7
+
+This means you should replace the docs section following the comment
+before you build the HTML for version 1.4.0.
+
+Here's a command line you can use to list the TODOs in the
+documentation sources (run it from the top-level directory in the
+repository):
+
+    $ git grep -n 'FIXME\|TODO'
+
+You can use the following to temporarily alias the above mouthful to
+'todos':
+
+    $ alias todos="git grep -n 'FIXME\|TODO'"
+
+Then you can just run
+
+    $ todos
+
+to measure the joy that awaits you.
+
+    ~~~~~~~~~~~
+    Preparation
+    ~~~~~~~~~~~
+
+- FINISH THE FIXMEs/TODOs FOR THE CURRENT RELEASE!
+
+  You may violate assumptions made elsewhere in the documentation if
+  you don't.  This can lead to incoherent or incorrect documentation,
+  which is usually worse than none at all.
+
+  If the release you're building is vA.B.C, you can see the relevant
+  TODOs with:
+
+      $ todos | grep A\.B\.C
+
+  If you find that you really can't finish the TODO, you should bump
+  the version number in the comment.  Don't do this out of laziness.
+  Seriously, don't.  We may have made promises to the users about what
+  would happen when, and you might be breaking them.
+
+- Pick the low-hanging fruit on any other FIXMEs/TODOs.
+
+- Ask Git to tell you what's happened since the most recent libmaple
+  release, and make sure that any major, potentially
+  backwards-incompatible, etc. changes are appropriately documented.
+
+  You can use three dots ("...") between the git tags for those
+  releases in concert with "git log --oneline" to do this.
+
+  For instance, from the libmaple repository, you can use the
+  following to tell you what happened in between 0.0.9 and 0.0.10:
+
+      $ git log --oneline 0.0.9...0.0.10
+
+  As an example of what the output might cause you to do, consider the
+  following line (which appears in the output for 0.0.9...0.0.10):
+
+      4941335 Adding rcc_dev_clk(), an accessor for a peripheral's clock line.
+
+  Did the author of that commit (or some other interested party)
+  remember to pull in the documentation for rcc_dev_clk() into the
+  libmaple API page for rcc.h?  Go check!
+
+- Do something similar for Maple IDE.  The IDE changes a lot more
+  slowly, so there should be less to do.
+
+    ~~~~~~~~~~~~~~~~~~~
+    Cutting the Release
+    ~~~~~~~~~~~~~~~~~~~
+
+- Make a release branch in Git.  For release A.B.C, call it
+  vA.B.C-maintenance.  You spell that
+
+      $ git checkout -b vA.B.C-maintenance
+
+  DON'T MAKE A TAG.  There are inevitably mistakes in the docs, some
+  of which will be noticed and corrected, making a fixed tag useless.
+  When you correct the errors, you'll need to update this branch,
+  possibly also cherry-picking or otherwise adding into master.  See
+  "Maintaining the Release", below.
+
+- Do all the TODOs which must happen for _every_ release. (These are
+  distinct from the ones that must happen for some _particular_
+  release).  You can find most of these with
+
+      $ todos | grep RELEASE
+
+  However, you'll also need to check source/conf.py, as e.g. a
+  release's configuration file needs to have a version entered into
+  it.
+
+  DON'T FORGET TO COMMIT YOUR CHANGES.
+
+- Run "$ make mrproper" from the libmaple directory, and "$ make
+  clean" from this directory, in order to wipe out existing old docs.
+
+- Finally, you can actually build the docs. (See README-building.txt
+  for instructions if you've never done this before.)
+
+  DON'T FORGET TO PUSH THE RELEASE BRANCH TO GITHUB.
+
+Maintaining a Release
+---------------------
+
+So a released version's documentation contains unforgivable lies, huh?
+It needs to be updated RIGHT AWAY, you say?  Here's what you do:
+
+- Check out the release branch for the version of the docs you care
+  about (see "Cutting the Release", above).
+
+- Make your changes.
+
+- Rebuild the docs (see the last two steps in "Cutting the Release")
+  and look at the changed pages.
+
+- If your changes also need to happen on the master branch, make them
+  appropriately.
+
+  Advice: git cherry-pick is your friend.  Let's say you're on branch
+  "vX.Y.Z-maintenance", and you want to get commit C onto master:
+
+             o---C  vX.Y.Z-maintenance
+            /
+      -o---o---o---o  master
+
+  The recipe is:
+
+      $ git checkout master
+      $ git cherry-pick C
+
+  Which (if there are no conflicts) will result in:
+
+             o---C  vX.Y.Z-maintenance
+            /
+      -o---o---o---o---C'  master
+
+  Where C' performs the same changes as C.
+
+- Push your fixes to GitHub.
+
+- Distribute the updated docs.  These are world-visible here:
+
+      http://static.leaflabs.com/pub/leaflabs/maple-docs/
+
+Adding a New Board
+------------------
+
+Adding documentation for a new board is not just a matter of shoving a
+file for it into source/hardware/!
+
+Other things you must consider:
+
+- Various places in the docs link to particular kinds of pin maps for
+  each board.  When you add a new board, you must update these as
+  well.  Here's the list; please keep it current (files are relative
+  to the source/ directory):
+
+  * external-interrupts.rst: EXTI line pin maps
+  * timers.rst: timer pin maps
+  * adc.rst: low-noise ADC banks
+  * usart.rst: USART pin maps
+  * gpio.rst: master pin maps
+  * bootloader.rst: flashing a custom bootloader
+
+- The quickstart document may not explain how to use the new board.
+  If the board is different enough, a new, special-purpose quickstart
+  may need to be written for it.  Therefore, read the quickstart in
+  its entirety and update it appropriately.
+
+  Take this step seriously.  The quickstart is the first thing users
+  read when starting out, and first impressions matter.