Docs: move ASSERT() to its own page.

ASSERT() was previously documented in language.rst.  Move it to a new
lang/api/assert.rst.

5 files changed, 51 insertions, 55 deletions

diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index 4151a53..0558a29 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -2,9 +2,8 @@
 
 .. _jtag:
 
-======
- JTAG
-======
+JTAG
+====
 
 .. FIXME [0.1.0] Updated adapter schematic, better information
 
@@ -17,10 +16,9 @@ and hardware peripherals (we use it when working on :ref:`libmaple
 <libmaple>`) or to flash a new bootloader.
 
 Note that the STM32 on the Maple has a built-in low level serial
-debugger which could also be used to flash bootloaders, and that the
-:ref:`ASSERT <language-assert>` framework allows basic debugging over
-a USART serial channel.  We expect only fairly advanced users to use
-this feature.
+debugger which could also be used to flash bootloaders, and
+:ref:`lang-assert` allows basic debugging over a USART serial channel.
+We expect only fairly advanced users to use this feature.
 
 .. contents:: Contents
    :local:
diff --git a/docs/source/lang/api/assert.rst b/docs/source/lang/api/assert.rst
new file mode 100644
index 0000000..76330b6
--- /dev/null
+++ b/docs/source/lang/api/assert.rst
@@ -0,0 +1,30 @@
+.. highlight:: cpp
+
+.. _lang-assert:
+
+``ASSERT(...)``
+===============
+
+ASSERT() can be very useful for basic program debugging. It accepts a
+boolean; for example::
+
+  ASSERT(state == WAIT);
+
+Zero is false and any other number is true.  If the boolean is true,
+the assertion passes and the program continues as usual.  If it is
+false, the assertion fails: the program is halted, debug information
+is printed to USART2, and the status LED begins to throb (it's
+noticeably different from blinking). The debug information is printed
+at 9600 baud and consists of the filename and line number where the
+ASSERT() failed.
+
+Including assertions in a program increases the program size. When
+using libmaple **from the command line only**, they can be disabled by
+making the definition ::
+
+  #define DEBUG_LEVEL DEBUG_NONE
+
+before including either wirish.h or libmaple.h. In this case, all
+assertions will pass without any lost clock cycles.  Note that this
+will **not work in the IDE**; even with this definition, assertions
+will still be enabled.
diff --git a/docs/source/language.rst b/docs/source/language.rst
index 3ecbe43..be085f2 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -12,8 +12,7 @@ language used to program the `Arduino <http://arduino.cc/>`_ boards.
 
 .. TODO [0.2.0?] Wiring tutorial
 
-C or C++ programmers curious about the differences between the Wiring
-language and C++ may wish to skip to the
+C or C++ programmers may wish to skip to the
 :ref:`arduino_c_for_c_hackers`.
 
 .. contents:: Contents
@@ -21,8 +20,7 @@ language and C++ may wish to skip to the
 
 .. admonition:: **Looking for Something Else?**
 
-   - See the :ref:`libraries` for extra built-in libraries for dealing
-     with different kinds of hardware.
+   - See the :ref:`libraries` for extra built-in libraries.
 
    - If you're looking for something from the C standard library (like
      ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
@@ -31,17 +29,17 @@ language and C++ may wish to skip to the
      use of any of its header files.  However, dynamic memory allocation
      (``malloc()``, etc.) is not available.
 
-   - If you're looking for pointers to low-level details, see this page's
-     :ref:`Recommended Reading <language-recommended-reading>`.
+   - If you're looking for pointers to low-level details, see
+     :ref:`libmaple` and this page's :ref:`Recommended Reading
+     <language-recommended-reading>`.
 
 .. _language-lang-docs:
 
 Maple Language Reference
 ------------------------
 
-The following table summarizes the most important core language
-features.  An exhaustive index is available at the
-:ref:`language-index`.
+This table is a summary of the most important language features.  See
+the :ref:`language-index` for a complete listing.
 
 +--------------------------------------------+----------------------------------------------+---------------------------------------------------+
 | Structure                                  | Variables                                    | Functions                                         |
@@ -68,7 +66,7 @@ features.  An exhaustive index is available at the
 |                                            |                                              |                                                   |
 |* :ref:`continue <lang-continue>`           |**Data Types**                                |* :ref:`analogRead() <lang-analogread>`            |
 |                                            |                                              |                                                   |
-|* :ref:`return <lang-return>`               | The size of each datatype, in bytes, is      |* :ref:`pwmWrite() <lang-pwmwrite>`                |
+|* :ref:`return <lang-return>`               | The size of each data type, in bytes, is     |* :ref:`pwmWrite() <lang-pwmwrite>`                |
 |                                            | given in parentheses where appropriate.      |  (:ref:`analogWrite() <lang-analogwrite>` is      |
 |* :ref:`goto <lang-goto>`                   |                                              |  also available, though its use is discouraged)   |
 |                                            | *Note*: The ``word`` type is (deliberately)  |                                                   |
@@ -144,7 +142,7 @@ features.  An exhaustive index is available at the
 |                                            |                                              |                                                   |
 |* :ref:`& reference operator                |* :ref:`sizeof() <lang-sizeof>`               |* :ref:`bitClear() <lang-bitclear>`                |
 |  <lang-pointer>`                           |                                              |                                                   |
-|                                            |                                              |* :ref:`bit() <lang-bit>`                          |
+|                                            |* :ref:`ASSERT() <lang-assert>`               |* :ref:`bit() <lang-bit>`                          |
 |                                            |                                              |                                                   |
 |**Bitwise Operators**                       |                                              |                                                   |
 |                                            |                                              |**External Interrupts**                            |
@@ -205,35 +203,6 @@ features.  An exhaustive index is available at the
 |                                            |                                              |                                                   |
 +--------------------------------------------+----------------------------------------------+---------------------------------------------------+
 
-.. _language-assert:
-
-``ASSERT(...)``
----------------
-
-The ``ASSERT()`` function can be very useful for basic program
-debugging. It accepts a boolean; for example::
-
-  ASSERT(state == WAIT);
-
-Zero is false and any other number is true. If the boolean is true, the
-assertion passes and the program continues as usual. If it is false,
-the assertion fails: the program is halted, debug information is
-printed to USART2, and the status LED begins to throb in intensity
-(it's noticeably different from blinking). The debug information is
-printed at 9600 baud and consists of the filename and line number
-where the particular assertion failed.
-
-Including assertions in a program increases the program size. When
-using libmaple **from the command line only**, they can be disabled by
-making the definition ::
-
-  #define DEBUG_LEVEL DEBUG_NONE
-
-before including either wirish.h or libmaple.h. In this case, all
-assertions will pass without any lost clock cycles.  Note that this
-will **not work in the IDE**; even with this definition, assertions
-will still be enabled.
-
 .. _language-missing-features:
 
 Missing Arduino Features
@@ -301,7 +270,7 @@ Note for C/C++ Hackers
 
 This is a note for programmers comfortable with C or C++ who want a
 better understanding of the differences between C++ and the Wiring
-language.  
+language.
 
 The good news is that the differences are relatively few; Wiring is
 just a thin wrapper around C++.  Some potentially better news is that
@@ -378,7 +347,7 @@ behaves roughly like::
 
     // Call user loop() forever.
     while (true) {
-        loop(); 
+        loop();
     }
   }
 
diff --git a/docs/source/timers.rst b/docs/source/timers.rst
index e23579d..b6c0886 100644
--- a/docs/source/timers.rst
+++ b/docs/source/timers.rst
@@ -66,11 +66,10 @@ Working with timers and interrupts can be tricky; they are a somewhat
 "advanced" topic.  The following subsections explain some common
 problems associated with using timers and timer interrupts.
 
-In general: start simple, test with :ref:`ASSERT() <language-assert>`,
-and don't try to do too much in your interrupt handlers!  Make sure
-that what you're trying to do in a handler isn't going to block other
-interrupts from firing, if those other interrupts are important for
-your program.
+In general: start simple, test with :ref:`lang-assert`, and don't try
+to do too much in your interrupt handlers!  Make sure that what you're
+trying to do in a handler isn't going to block other interrupts from
+firing, if those other interrupts are important for your program.
 
 .. _timers-pwm-conflicts:
 
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
index 3174f14..b679b9c 100644
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@@ -18,7 +18,7 @@ The LED is throbbing and my program is stopped!
 -----------------------------------------------
 
 The LED throbs when there has been a failed software :ref:`assertion
-<language-assert>` or some other error.
+<lang-assert>` or some other error.
 
 There are a few issues with the bootloader which mean you might not be
 able to upload your program when this happens.  You can still