0.0.10 Documentation checkpoint.

The vast majority of the Maple-specific values have been pulled out of
the higher-level overview pages and replaced with refs into documents
under /docs/source/hardware/.

Much of the work that's left to be done in this regard is labeled with
versioned TODO and FIXME comments.

Suggestions from StephenFromNYC and gbulmer were incorporated from
this forum thread:

      http://forums.leaflabs.com/topic.php?id=703

1 files changed, 18 insertions, 39 deletions

diff --git a/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst
index 7c5a6c7..39902ac 100644
--- a/docs/source/lang/api/attachinterrupt.rst
+++ b/docs/source/lang/api/attachinterrupt.rst
@@ -5,9 +5,8 @@
 attachInterrupt()
 =================
 
-Used to specify a function to call when an external interrupt (like an
-GPIO changing from LOW to HIGH, a button getting pressed, etc.)
-occurs.
+Used to specify a function to call when an :ref:`external interrupt
+<external-interrupts>` occurs.
 
 .. contents:: Contents
    :local:
@@ -15,9 +14,9 @@ occurs.
 Library Documentation
 ---------------------
 
-.. FIXME once breathe knows how to get the correct attachInterupt
-.. (right now it's copying from HardwareTimer), replace with a
-.. doxygenfunction directive
+.. FIXME [doxygenfunction] once Breathe knows how to get the correct
+.. attachInterupt (right now it's copying from HardwareTimer), replace
+.. with a doxygenfunction directive
 
 .. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode)
 
@@ -47,49 +46,29 @@ Discussion
 
 Because the function will run in interrupt context, inside of it,
 :ref:`lang-delay` won't work, and the value returned by
-:ref:`lang-millis` will not increment. Serial data received while
-in the function may be lost. You should declare as ``volatile`` any
+:ref:`lang-millis` will not increment. Serial data received while in
+the function may be lost. You should declare as ``volatile`` any
 global variables that you modify within the attached function.
 
-There are a few constraints you should be aware of if you're using
-more than one interrupt at a time; the :ref:`external-interrupts` page
-has the details.
-
-Using Interrupts
-----------------
-
-Interrupts are useful for making things happen automatically in
-microcontroller programs, and can help solve timing problems. A
-good task for using an interrupt might be reading a rotary encoder,
-or monitoring user input.
-
-If you wanted to insure that a program always caught the pulses
-from a rotary encoder, never missing a pulse, it would make it very
-tricky to write a program to do anything else, because the program
-would need to constantly poll the sensor lines for the encoder, in
-order to catch pulses when they occurred. Other sensors have a
-similar interface dynamic too, such as trying to read a sound
-sensor that is trying to catch a click, or an infrared slot sensor
-(photo-interrupter) trying to catch a coin drop. In all of these
-situations, using an interrupt can free the microcontroller to get
-some other work done while not missing the doorbell.
+There are a few limits you should be aware of if you're using more
+than one interrupt at a time; the :ref:`External Interrupts
+<external-interrupts-exti-line>` page has more information.
 
 Example
 -------
 
-::
+ ::
 
-    int maple_led_pin = 13;
     volatile int state = LOW; // must declare volatile, since it's
-                              // modified within the blink handler
+                              // modified within the blink() handler
 
     void setup() {
-      pinMode(maple_led_pin, OUTPUT);
+      pinMode(BOARD_LED_PIN, OUTPUT);
       attachInterrupt(0, blink, CHANGE);
     }
 
     void loop() {
-      digitalWrite(maple_led_pin, state);
+      digitalWrite(BOARD_LED_PIN, state);
     }
 
     void blink() {
@@ -106,10 +85,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5
 number goes with which pin -- just tell ``attachInterrupt()`` the pin
 you want.
 
-See also
+See Also
 --------
 
--  :ref:`detachInterrupt <lang-detachinterrupt>`
--  :ref:`external-interrupts`
+- :ref:`lang-detachinterrupt`
+- :ref:`external-interrupts`
 
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt