arduino language reference nearing completion, properly CC-BY-SA 3.0 attributed

1 files changed, 58 insertions, 77 deletions

diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst
index c7bd148..1ae34e8 100644
--- a/source/arduino/braces.rst
+++ b/source/arduino/braces.rst
@@ -1,113 +1,94 @@
+.. highlight:: cpp
+
 .. _arduino-braces:
 
-{} Curly Braces
-===============
+Curly Braces ({})
+=================
 
-Curly braces (also referred to as just "braces" or as "curly
-brackets") are a major part of the C programming language. They are
-used in several different constructs, outlined below, and this can
-sometimes be confusing for beginners.
+.. contents:: Contents
+   :local:
 
+Introduction
+------------
 
+Curly braces (also referred to as just "braces" or as "curly
+brackets") are a major part of the C and C++ programming
+languages. They are used in several different constructs, outlined
+below, and this can sometimes be confusing for beginners.
 
-An opening curly brace "{" must always be followed by a closing
-curly brace "}". This is a condition that is often referred to as
-the braces being balanced. The Arduino IDE (integrated development
+An opening curly brace, ``{`` must always be followed by a closing
+curly brace ``}``. This is a condition that is often referred to as
+the braces being *balanced*. The Maple IDE (integrated development
 environment) includes a convenient feature to check the balance of
-curly braces. Just select a brace, or even click the insertion
-point immediately following a brace, and its logical companion will
-be highlighted.
-
-
-
-At present this feature is slightly buggy as the IDE will often
-find (incorrectly) a brace in text that has been "commented out."
-
-
-
-Beginning programmers, and programmers coming to C from the BASIC
-language often find using braces confusing or daunting. After all,
-the same curly braces replace the RETURN statement in a subroutine
-(function), the ENDIF statement in a conditional and the NEXT
-statement in a FOR loop.
-
+curly braces. Just select a brace, or even click the insertion point
+immediately following a brace, and its companion will be highlighted\
+[#fbug]_\ .
 
+Beginning programmers, and programmers coming to C++ from languages
+without braces, often find using them confusing or daunting.
 
 Because the use of the curly brace is so varied, it is good
 programming practice to type the closing brace immediately after
 typing the opening brace when inserting a construct which requires
-curly braces. Then insert some carriage returns between your braces
-and begin inserting statements. Your braces, and your attitude,
-will never become unbalanced.
-
-
+curly braces. Then insert some blank lines between your braces and
+begin inserting statements. Your braces, and your attitude, will never
+become unbalanced.
 
 Unbalanced braces can often lead to cryptic, impenetrable compiler
 errors that can sometimes be hard to track down in a large program.
-Because of their varied usages, braces are also incredibly
-important to the syntax of a program and moving a brace one or two
-lines will often dramatically affect the meaning of a program.
+Because of their varied usages, braces are also incredibly important
+to the syntax of a program and moving a brace one or two lines will
+usually dramatically affect the meaning of a program.
 
+The main uses of curly braces
+-----------------------------
 
+**Functions**::
 
-**The main uses of curly braces**
----------------------------------
-
-Functions
----------
-
-::
-
-      void myfunction(datatype argument){
-        statements(s)
+      // a function body needs braces around it
+      void myfunction(datatype argument) {
+        // ... function body goes in here ...
       }
 
+**Loops** (see the :ref:`while <arduino-while>`\ , :ref:`for
+<arduino-for>`\ , and :ref:`do/while <arduino-dowhile>` loop reference
+pages for more information)::
 
+      // you should put braces around the body of a loop:
 
-Loops
------
-
-::
-
-      while (boolean expression)
-      {
-         statement(s)
+      while (boolean expression) {
+         // code inside the loop goes here
       }
     
-      do
-      {
-         statement(s)
-      } while (boolean expression);
-    
-      for (initialisation; termination condition; incrementing expr)
-      {
-         statement(s)
+      for (initialisation; termination condition; incrementing expr) {
+         // code inside the loop goes here
       } 
 
+      do {
+         // code inside the loop goes here
+      } while (boolean expression);
 
 
-Conditional statements
-----------------------
-
-
+**Conditional statements** (see the :ref:`if statement <arduino-if>`
+reference page for more information)::
 
-::
+      // you should put braces around the body of an "if", "else if",
+      // or "else":
 
-      if (boolean expression)
-      {
-         statement(s)
+      if (boolean expression) {
+          // code inside the "if"
       }
-    
-      else if (boolean expression)
-      {
-         statement(s)
+      else if (boolean expression) {
+          // code inside the "else if"
       } 
-      else
-      {
-         statement(s)
+      else {
+          // code inside the "else"
       }
 
+.. rubric:: Footnotes
 
+.. TODO remove this once IDE 0.1.0 released
 
-`Reference Home <http://arduino.cc/en/Reference/HomePage>`_
-
+.. [#fbug] At present this feature is slightly buggy as the IDE will
+   often find (incorrectly) a brace in text that has been commented
+   out.