1 files changed, 49 insertions, 57 deletions
diff --git a/docs/source/arduino/boolean.rst b/docs/source/arduino/boolean.rst
index f109bdb..a724c20 100644
--- a/docs/source/arduino/boolean.rst
+++ b/docs/source/arduino/boolean.rst
@@ -1,94 +1,86 @@
+.. highlight:: cpp
+
 .. _arduino-boolean:
 
 Boolean Operators
 =================
 
-These can be used inside the condition of an
-`if <http://arduino.cc/en/Reference/If>`_ statement.
+These can be used inside the condition of an :ref:`if <arduino-if>`
+statement.
 
+.. contents:: Contents
+   :local:
 
+.. _arduino-boolean-and:
 
 && (logical and)
-~~~~~~~~~~~~~~~~
-
-True only if both operands are true, e.g.
+----------------
 
-::
+True only if both operands are true.  For example::
 
-    if (digitalRead(2) == HIGH  && digitalRead(3) == HIGH) { // read two switches 
+    if (digitalRead(2) == HIGH  && digitalRead(3) == HIGH) { // read two switches
       // ...
-    } 
+    }
+
+is true only if both inputs are high.  Another example::
 
-is true only if both inputs are high.
+    if (a >= 10 && a <= 20){}   // true if a is between 10 and 20
 
+**Be careful** not to say ``10 <= a <= 20``!  This won't work the way
+you want.  You have to separately test whether ``a`` is at least 10
+using ``a >= 10``, then test whether ``a`` is at most 20 using ``a <=
+20``, then combine the results using ``&&``.
 
 
-\|\| (logical or)
-~~~~~~~~~~~~~~~~~
+.. _arduino-boolean-or:
 
-True if either operand is true, e.g.
+\|\| (logical or)
+-----------------
 
-::
+True if either operand is true.  For example::
 
     if (x > 0 || y > 0) {
       // ...
-    } 
+    }
 
-is true if either x or y is greater than 0.
+is true if either ``x`` or ``y`` is greater than 0.
 
 
+! (logical not)
+---------------
 
-! (not)
-~~~~~~~
+True if the operand is false.  For example::
 
-True if the operand is false, e.g.
-
-::
-
-    if (!x) { 
+    if (!x) {
       // ...
-    } 
-
-is true if x is false (i.e. if x equals 0).
-
-
-
-Warning
--------
+    }
 
-Make sure you don't mistake the boolean AND operator, && (double
-ampersand) for the bitwise AND operator & (single ampersand). They
-are entirely different beasts.
+is true if ``x`` is false (i.e. if ``x`` equals zero).
 
+Some Advice
+-----------
 
+.. warning::
 
-Similarly, do not confuse the boolean \|\| (double pipe) operator
-with the bitwise OR operator \| (single pipe).
+   Make sure you don't mistake the boolean AND operator ``&&``
+   (double ampersand) for the :ref:`bitwise AND operator
+   <arduino-bitwisemath-and>` ``&`` (single ampersand). They are
+   entirely different beasts.
 
+   Similarly, do not confuse the boolean OR operator ``||`` (double
+   pipe) with the :ref:`bitwise OR operator <arduino-bitwisemath-or>`
+   ``|`` (single pipe).
 
+   The :ref:`bitwise NOT operator <arduino-bitwisemath-not>` ``~``
+   (tilde) looks much different than the boolean not operator ``!``
+   (exclamation point, or "bang", as some programmers say), but you
+   still have to be sure which one you want.
 
-The bitwise not ~ (tilde) looks much different than the boolean not
-! (exclamation point or "bang" as the programmers say) but you
-still have to be sure which one you want where.
 
-
-
-Examples
---------
-
-::
-
-    if (a >= 10 && a <= 20){}   // true if a is between 10 and 20
-
-
-
-See also
+See Also
 --------
 
-
--  `& <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise AND)
--  `\| <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise OR)
--  `~ <http://arduino.cc/en/Reference/BitwiseXorNot>`_ (bitwise NOT
--  `if <http://arduino.cc/en/Reference/If>`_
-
-
+- :ref:`Bitwise operators <arduino-bitwisemath>` (``&``, ``|``, ``^``, ``~``)
+- :ref:`Compound bitwise operators <arduino-bitwisecompound>` (``&=``,
+  ``|=``, ``^=``).
+- :ref:`if statement <arduino-if>`