Redo source/libmaple.rst.

This page is not a good introduction. Make edits for clarity and
hopefully ease of use.

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

1 files changed, 26 insertions, 21 deletions

diff --git a/source/libmaple.rst b/source/libmaple.rst
index 0517f44..dce9ee6 100644
--- a/source/libmaple.rst
+++ b/source/libmaple.rst
@@ -5,33 +5,39 @@
 ``libmaple``
 ============
 
-LeafLabs' libmaple (`source code on GitHub
-<https://github.com/leaflabs/libmaple>`_) is the library we have
-developed for the `STM32 <http://www.st.com/stonline>`_ line of ARM
-Cortex M3 microcontrollers.  Its high-level interfaces are
-:ref:`largely compatible <arduino-compatibility>` with the AVR
-libraries written for the `Arduino <http://arduino.cc>`_ and `Wiring
-<http://wiring.org.co/>`_ development boards.
+LeafLabs' libmaple is the open source library we have developed for
+programming the `STM32 <http://www.st.com/stonline>`_ line of
+microcontrollers.  Libmaple's `source is on GitHub
+<https://github.com/leaflabs/libmaple>`_; :ref:`patches are welcome
+<libmaple-contributing>`.
 
 .. _libmaple-vs-wirish:
 
-libmaple is split into two pieces: a lower level layer written in C,
-which we call *libmaple proper* (in the `libmaple/
-<https://github.com/leaflabs/libmaple/tree/master/libmaple>`_
-directory of the source repository), and the Wiring-style C++ API
-written on top of it, called *Wirish* (in `wirish/
-<https://github.com/leaflabs/libmaple/tree/master/wirish>`_; the
-wirish APIs are :ref:`summarized here <language>`, with an :ref:`index
-here <language-index>`).
+Libmaple is split into two pieces: 
+
+- A low-level layer, written in C, called *libmaple proper*, located
+  in the `libmaple/
+  <https://github.com/leaflabs/libmaple/tree/master/libmaple>`_
+  subdirectory of the source repository.
+
+- A high-level layer, written in C++, called *wirish*, in the `wirish/
+  <https://github.com/leaflabs/libmaple/tree/master/wirish>`_
+  subdirectory.
+
+Wirish is :ref:`largely compatible <arduino-compatibility>` with the
+AVR libraries written for the `Arduino <http://arduino.cc>`_ and
+`Wiring <http://wiring.org.co/>`_ development boards. The Wirish
+:ref:`language` page is a good summary of what Wirish provides; a
+:ref:`complete Wirish API index <language-index>` is also
+available. :ref:`Wirish libraries <libraries>` are documented
+separately.
 
 libmaple is bundled with the :ref:`Maple IDE <ide>`.  However, we
 develop it separately, and :ref:`release it standalone
 <unix-toolchain>` for advanced users who might chafe at the "sketch"
-programming model of the IDE.
-
-As always, :ref:`patches are welcome <libmaple-contributing>`.
-
-**Contents:**
+programming model of the IDE. The following pages document libmaple
+proper. As such, they're intended for advanced users who know how to
+write C.
 
 .. toctree::
    :maxdepth: 1
@@ -40,4 +46,3 @@ As always, :ref:`patches are welcome <libmaple-contributing>`.
    libmaple/apis
    libmaple/contributing
    libmaple/coding-standard
-