Merge pull request #62 from allenluce/doc1

Documentation cleanup, part one.

doc/source/reference/introduction.rst

@@ -7,10 +7,10 @@ Introduction
 .. index::
     single: introduction
 
-Squirrel is a high level imperative-OO programming language, designed to be a powerful
-scripting tool that fits in the size, memory bandwidth, and real-time requirements of
+Squirrel is a high-level, imperative-OO programming language, designed to be a powerful
+scripting tool that fits within the size, memory bandwidth, and real-time requirements of
 applications like games.
-Although Squirrel offers a wide range of features like dynamic typing, delegation, higher
+Squirrel offers a wide range of features like dynamic typing, delegation, higher
 order functions, generators, tail recursion, exception handling, automatic memory
-management, both compiler and virtual machine fit together in about 6k lines of C++
-code.
+management while fitting both compiler and virtual machine into about 6k lines of C++
+code.

doc/source/reference/language/datatypes.rst

@@ -4,10 +4,11 @@
 Values and Data types
 =====================
 
-Squirrel is a dynamically typed language so variables do not have a type, although they
-refer to a value that does have a type.
-Squirrel basic types are integer, float, string, null, table, array, function, generator,
-class, instance, bool, thread and userdata.
+While Squirrel is a dynamically typed language and variables do not
+have a type, different operations may interpret the variable as
+containing a type.  Squirrel's basic types are integer, float, string,
+null, table, array, function, generator, class, instance, bool, thread
+and userdata.
 
 .. _userdata-index:
 
@@ -15,7 +16,7 @@ class, instance, bool, thread and userdata.
 Integer
 --------
 
-An Integer represents a 32 bits (or better) signed number.::
+An Integer represents a 32 bit (or better) signed number.::
 
     local a = 123 //decimal
     local b = 0x0012 //hexadecimal
@@ -26,7 +27,7 @@ An Integer represents a 32 bits (or better) signed number.::
 Float
 --------
 
-A float represents a 32 bits (or better) floating point number.::
+A float represents a 32 bit (or better) floating point number.::
 
     local a=1.0
     local b=0.234
@@ -35,24 +36,27 @@ A float represents a 32 bits (or better) floating point number.::
 String
 --------
 
-Strings are an immutable sequence of characters to modify a string is necessary create a new one.
+Strings are an immutable sequence of characters. In order to modify a
+string is it necessary create a new one.
 
-Squirrel's strings, behave like C or C++, are delimited by quotation marks(``"``) and can contain
-escape sequences(``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``, ``\\``, ``\"``, ``\'``, ``\0``,
-``\x<hh>``, ``\u<hhhh>`` and ``\U<hhhhhhhh>``).
+Squirrel's strings are similar to strings in C or C++.  They are
+delimited by quotation marks(``"``) and can contain escape
+sequences (``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``,
+``\\``, ``\"``, ``\'``, ``\0``, ``\x<hh>``, ``\u<hhhh>`` and
+``\U<hhhhhhhh>``).
 
-Verbatim string literals begin with ``@"`` and end with the matching quote.
-Verbatim string literals also can extend over a line break. If they do, they
-include any white space characters between the quotes: ::
+Verbatim string literals do not interpret escape sequences. They begin
+with ``@"`` and end with the matching quote.  Verbatim string literals
+also can extend over a line break. If they do, they include any white
+space characters between the quotes: ::
 
     local a = "I'm a wonderful string\n"
     // has a newline at the end of the string
     local x = @"I'm a verbatim string\n"
-    // the \n is copied in the string same as \\n in a regular string "I'm a verbatim string\n"
+    // the \n is literal, similar to "\\n" in a regular string.
 
-The only exception to the "no escape sequence" rule for verbatim
-string literals is that you can put a double quotation mark inside a
-verbatim string by doubling it: ::
+However, a doubled quotation mark within a verbatim string is replaced
+by a single quotation mark: ::
 
     local multiline = @"
         this is a multiline string
@@ -73,7 +77,7 @@ reference. The type Null has exactly one value, called null.::
 Bool
 --------
 
-the bool data type can have only two. They are the literals ``true``
+Bool is a double-valued (Boolean) data type. Its literals are ``true``
 and ``false``. A bool value expresses the validity of a condition
 (tells whether the condition is true or false).::
 
@@ -83,7 +87,8 @@ and ``false``. A bool value expresses the validity of a condition
 Table
 --------
 
-Tables are associative containers implemented as pairs of key/value (called a slot).::
+Tables are associative containers implemented as a set of key/value pairs
+called slots.::
 
     local t={}
     local test=
@@ -96,7 +101,7 @@ Tables are associative containers implemented as pairs of key/value (called a sl
 Array
 --------
 
-Arrays are simple sequence of objects, their size is dynamic and their index starts always from 0.::
+Arrays are simple sequence of objects. Their size is dynamic and their index always starts from 0.::
 
     local a  = ["I'm","an","array"]
     local b = [null]
@@ -106,46 +111,48 @@ Arrays are simple sequence of objects, their size is dynamic and their index sta
 Function
 --------
 
-Functions are similar to those in other C-like languages and to most programming
-languages in general, however there are a few key differences (see below).
+Functions are similar to those in other C-like languages with a few key differences (see below).
 
 --------
 Class
 --------
 
-Classes are associative containers implemented as pairs of key/value. Classes are created through
-a 'class expression' or a 'class statement'. class members can be inherited from another class object
-at creation time. After creation members can be added until a instance of the class is created.
+Classes are associative containers implemented as sets of key/value
+pairs. Classes are created through a 'class expression' or a 'class
+statement'. class members can be inherited from another class object
+at creation time. After creation, members can be added until an
+instance of the class is created.
 
 --------------
 Class Instance
 --------------
 
-Class instances are created by calling a *class object*. Instances, as tables, are
-implemented as pair of key/value. Instances members cannot be dynamically added or removed; however the value of the members can be changed.
-
-
+Class instances are created by calling a *class object*. Instances, as
+tables, are implemented as sets of key/value pairs. Instance members
+cannot be dynamically added or removed; however the value of the
+members can be changed.
 
 ---------
 Generator
 ---------
 
-Generators are functions that can be suspended with the statement 'yield' and resumed
-later (see :ref:`Generators <generators>`).
+Generators are functions that can be suspended with the statement
+'yield' and resumed later (see :ref:`Generators <generators>`).
 
 ---------
 Userdata
 ---------
 
-Userdata objects are blobs of memory(or pointers) defined by the host application but
-stored into Squirrel variables (See :ref:`Userdata and UserPointers <embedding_userdata_and_userpointers>`).
-
+Userdata objects are blobs of memory or pointers defined by the host
+application but stored within Squirrel variables (See :ref:`Userdata
+and UserPointers <embedding_userdata_and_userpointers>`).
 
 ---------
 Thread
 ---------
 
-Threads are objects that represents a cooperative thread of execution, also known as coroutines.
+Threads are objects representing a cooperative thread of execution,
+also known as coroutines.
 
 --------------
 Weak Reference
@@ -153,5 +160,3 @@ Weak Reference
 
 Weak References are objects that point to another (non-scalar) object but do not own a strong reference to it.
 (See :ref:`Weak References <weak_references>`).
-
-

doc/source/reference/language/lexical_structure.rst

@@ -13,11 +13,11 @@ Identifiers
 
 .. index:: single: identifiers
 
-Identifiers start with a alphabetic character or '_' followed by any number of alphabetic
-characters, '_' or digits ([0-9]). Squirrel is a case sensitive language, this means that the
-lowercase and uppercase representation of the same alphabetic character are considered
-different characters. For instance "foo", "Foo" and "fOo" will be treated as 3 distinct
-identifiers.
+Identifiers start with an alphabetic character or the symbol '_' followed by any number
+of alphabetic characters, '_' or digits ([0-9]). Squirrel is a case sensitive language
+meaning that the lowercase and uppercase representation of the same alphabetic
+character are considered different characters. For instance, "foo", "Foo" and "fOo" are
+treated as 3 distinct identifiers.
 
 -----------
 Keywords
@@ -25,7 +25,7 @@ Keywords
 
 .. index:: single: keywords
 
-The following words are reserved words by the language and cannot be used as identifiers:
+The following words are reserved and cannot be used as identifiers:
 
 +------------+------------+-----------+------------+------------+-------------+
 | base       | break      | case      | catch      | class      | clone       |
@@ -69,7 +69,7 @@ Other tokens
     single: delimiters
     single: other tokens
 
-Other used tokens are:
+Other significant tokens are:
 
 +----------+----------+----------+----------+----------+----------+
 | ``{``    | ``}``    | ``[``    | ``]``    | ``.``    | ``:``    |
@@ -86,7 +86,7 @@ Literals
     single: string literals
     single: numeric literals
 
-Squirrel accepts integer numbers, floating point numbers and strings literals.
+Squirrel accepts integer numbers, floating point numbers and string literals.
 
 +-------------------------------+------------------------------------------+
 | ``34``                        | Integer number(base 10)                  |
@@ -131,7 +131,7 @@ A comment is text that the compiler ignores but that is useful for programmers.
 Comments are normally used to embed annotations in the code. The compiler
 treats them as white space.
 
-The ``/*`` (slash, asterisk) characters, followed by any
+A comment can be ``/*`` (slash, asterisk) characters, followed by any
 sequence of characters (including new lines),
 followed by the ``*/`` characters. This syntax is the same as ANSI C.::
 
@@ -141,9 +141,9 @@ followed by the ``*/`` characters. This syntax is the same as ANSI C.::
     this lines will be ignored by the compiler
     */
 
-The ``//`` (two slashes) characters, followed by any sequence of characters.
-A new line not immediately preceded by a backslash terminates this form of comment.
-It is commonly called a *"single-line comment."*::
+A comment can also be ``//`` (two slashes) characters, followed by any sequence of
+characters.  A new line not immediately preceded by a backslash terminates this form of
+comment.  It is commonly called a *"single-line comment."*::
 
     //this is a single line comment. this line will be ignored by the compiler
 
@@ -152,5 +152,3 @@ The character ``#`` is an alternative syntax for single line comment.::
     # this is also a single line comment.
 
 This to facilitate the use of squirrel in UNIX-style shell scripts.
-
-