1 files changed, 54 insertions, 71 deletions
diff --git a/docs/source/arduino/if.rst b/docs/source/arduino/if.rst
index d75f6d3..00f1a4d 100644
--- a/docs/source/arduino/if.rst
+++ b/docs/source/arduino/if.rst
@@ -1,95 +1,78 @@
-.. _arduino-if:
+.. highlight:: cpp
 
-if (conditional) and ==, !=, <, > (comparison operators)
-========================================================
+.. _arduino-if:
 
-**``if``**, which is used in conjunction with a comparison
-operator, tests whether a certain condition has been reached, such
-as an input being above a certain number. The format for an if test
-is:
+if Statements
+=============
 
+An ``if`` statement is used to execute code when certain conditions
+are met.  The general syntax for an ``if`` statement is::
 
+    if (condition) {
+        body
+    }
 
-::
+An ``if`` statement first tests whether its *condition* is true (such
+as an input being above a certain number).  If the condition is true,
+the ``if`` statement executes its *body*, which is made up of lines of
+code inside :ref:`curly braces <arduino-braces>`.  If the condition is
+false, the body is not executed.  Here's a more concrete example::
 
-    if (someVariable > 50)
-    {
+    if (someVariable > 50) {
       // do something here
     }
 
+The program tests to see if ``someVariable`` is greater than 50. If it
+is, the program executes every line in the curly braces (which in the
+above example does nothing, since the body is just the :ref:`comment
+<arduino-comments>` line "``// do something here``").
 
+Put another way, if the statement in parentheses is true, the
+statements inside the braces are run. If not, the program skips over
+the code.
 
-The program tests to see if someVariable is greater than 50. If it
-is, the program takes a particular action. Put another way, if the
-statement in parentheses is true, the statements inside the
-brackets are run. If not, the program skips over the code.
+An ``if`` statement's condition (which is inside the parentheses after
+``if``) often uses one or more :ref:`boolean <arduino-boolean>` or
+:ref:`comparison <arduino-comparison>` operators.
 
+Writing the if Body
+-------------------
 
+The brackets may be omitted after an ``if`` statement's
+conditional. If this is done, the next line (which ends in a
+semicolon) becomes the only line in the body.  The following three
+``if`` statements all do the same thing::
 
-The brackets may be omitted after an *if* statement. If this is
-done, the next line (defined by the semicolon) becomes the only
-conditional statement.
+    if (x > 120) digitalWrite(ledPin, HIGH);
 
-::
-
-    
-    if (x > 120) digitalWrite(LEDpin, HIGH); 
-    
     if (x > 120)
-    digitalWrite(LEDpin, HIGH); 
-    
-    if (x > 120){ digitalWrite(LEDpin, HIGH); } 
-    
-    if (x > 120){ 
-      digitalWrite(LEDpin1, HIGH);
-      digitalWrite(LEDpin2, HIGH); 
-    }                                 // all are correct
-
-
-
-The statements being evaluated inside the parentheses require the
-use of one or more operators:
-
-
+        digitalWrite(ledPin, HIGH);
 
-Comparison Operators:
-~~~~~~~~~~~~~~~~~~~~~
+    if (x > 120) {
+        digitalWrite(ledPin, HIGH);
+    }
 
-::
+However, the following two examples are different::
 
-     x == y (x is equal to y)
-     x != y (x is not equal to y)
-     x <  y (x is less than y)  
-     x >  y (x is greater than y) 
-     x <= y (x is less than or equal to y) 
-     x >= y (x is greater than or equal to y)
+    // example 1: two lines of code in the if body
+    if (x > 120) {
+      digitalWrite(ledPin1, HIGH);
+      digitalWrite(ledPin2, HIGH);
+    }
 
+    // example 2: one line of code in the if body, and
+    // another line of code after the if statement
+    if (x > 120)
+      digitalWrite(ledPin1, HIGH); // this is in the if body
+      digitalWrite(ledPin2, HIGH); // this is NOT in the if body
 
+In the first example, since the body is enclosed in curly braces, both
+lines are included.  In the second example, since the curly braces are
+missing, only the first line is in the ``if`` body.
 
-Warning:
+See Also
 --------
 
-Beware of accidentally using the single equal sign
-(e.g.``if (x = 10)`` ). The single equal sign is the assignment
-operator, and sets x to 10 (puts the value 10 into the variable x).
-Instead use the double equal sign (e.g.``if (x == 10)``), which is
-the comparison operator, and tests *whether* x is equal to 10 or
-not. The latter statement is only true if x equals 10, but the
-former statement will always be true.
-
-
-
-This is because C evaluates the statement ``if (x=10)`` as follows:
-10 is assigned to x (remember that the single equal sign is the
-`assignment operator <http://arduino.cc/en/Reference/Assignment>`_),
-so x now contains 10. Then the 'if' conditional evaluates 10, which
-always evaluates to TRUE, since any non-zero number evaluates to
-TRUE. Consequently, ``if (x = 10)`` will always evaluate to TRUE,
-which is not the desired result when using an 'if' statement.
-Additionally, the variable x will be set to 10, which is also not a
-desired action.
-
-
-
-**if** can also be part of a branching control structure using the
-`if...else <http://arduino.cc/en/Reference/Else>`_] construction.
+- :ref:`boolean operators <arduino-boolean>`
+- :ref:`comparison operators <arduino-comparison>`
+- :ref:`else <arduino-else>`