README in citrus-1.8.0 vs README in citrus-2.0.0

@@ -54,13 +54,13 @@
 
 A [Rule](api/classes/Citrus/Rule.html) is an object that specifies some matching
 behavior on a string. There are two types of rules: terminals and non-terminals.
 Terminals can be either Ruby strings or regular expressions that specify some
 input to match. For example, a terminal created from the string "end" would
-match any sequence of the characters "e", "n", and "d", in that order. A
-terminal created from a regular expression uses Ruby's regular expression engine
-to attempt to create a match.
+match any sequence of the characters "e", "n", and "d", in that order. Terminals
+created from regular expressions may match any sequence of characters that can
+be generated from that expression.
 
 Non-terminals are rules that may contain other rules but do not themselves match
 directly on the input. For example, a Repeat is a non-terminal that may contain
 one other rule that will try and match a certain number of times. Several other
 types of non-terminals are available that will be discussed later.
@@ -83,25 +83,24 @@
 similar to Ruby's super keyword.
 
 ## Matches
 
 Matches are created by rule objects when they match on the input. A 
-[Match](api/classes/Citrus/Match.html) in Citrus is actually a 
-[String](http://ruby-doc.org/core/classes/String.html) with some extra 
-information attached such as the name(s) of the rule(s) which generated the 
-match as well as its offset in the original input string.
+[Match](api/classes/Citrus/Match.html) is actually a 
+[String](http://ruby-doc.org/core/classes/String.html) object with some extra 
+information attached such as the name(s) of the rule(s) from which it was
+generated and any submatches it may contain.
 
 During a parse, matches are arranged in a tree structure where any match may
 contain any number of other matches. This structure is determined by the way in
 which the rule that generated each match is used in the grammar. For example, a 
 match that is created from a non-terminal rule that contains several other 
 terminals will likewise contain several matches, one for each terminal.
 
 Match objects may be extended with semantic information in the form of methods.
-These methods can interpret the text of a match using the wealth of information
-available to them including the text of the match, its position in the input,
-and any submatches.
+These methods should provide various interpretations for the semantic value of a
+match.
 
 
 # Syntax
 
 
@@ -123,12 +122,11 @@
 
     [a-z0-9]      # match any lowercase letter or digit
     [\x00-\xFF]   # match any octet
     .             # match anything, even new lines
 
-See [FixedWidth](api/classes/Citrus/FixedWidth.html) and
-[Expression](api/classes/Citrus/Expression.html) for more information.
+See [Terminal](api/classes/Citrus/Terminal.html) for more information.
 
 ## Repetition
 
 Quantifiers may be used after any expression to specify a number of times it
 must match. The universal form of a quantifier is N*M where N is the minimum and
@@ -210,29 +208,29 @@
 ## Precedence
 
 The following table contains a list of all Citrus operators and their 
 precedence. A higher precedence indicates tighter binding.
 
-| Operator    | Name                      | Precedence |
-| ----------- | ------------------------- | ---------- |
-| ''          | String (single quoted)    | 6          |
-| ""          | String (double quoted)    | 6          |
-| []          | Character class           | 6          |
-| .           | Dot (any character)       | 6          |
-| //          | Regular expression        | 6          |
-| ()          | Grouping                  | 6          |
-| *           | Repetition (arbitrary)    | 5          |
-| +           | Repetition (one or more)  | 5          |
-| ?           | Repetition (zero or one)  | 5          |
-| &           | And predicate             | 4          |
-| !           | Not predicate             | 4          |
-| ~           | But predicate             | 4          |
-| :           | Label                     | 4          |
-| <>          | Extension (module name)   | 3          |
-| {}          | Extension (literal)       | 3          |
-| e1 e2       | Sequence                  | 2          |
-| e1 | e2     | Ordered choice            | 1          |
+Operator    | Name                      | Precedence
+----------- | ------------------------- | ----------
+''          | String (single quoted)    | 6
+""          | String (double quoted)    | 6
+[]          | Character class           | 6
+.           | Dot (any character)       | 6
+//          | Regular expression        | 6
+()          | Grouping                  | 6
+*           | Repetition (arbitrary)    | 5
++           | Repetition (one or more)  | 5
+?           | Repetition (zero or one)  | 5
+&           | And predicate             | 4
+!           | Not predicate             | 4
+~           | But predicate             | 4
+:           | Label                     | 4
+<>          | Extension (module name)   | 3
+{}          | Extension (literal)       | 3
+e1 e2       | Sequence                  | 2
+e1 | e2     | Ordered choice            | 1
 
 
 # Example
 
 
@@ -280,13 +278,13 @@
 
 Submatches are created whenever a rule contains another rule. For example, in
 the grammar above the number rule matches a string of digits followed by white
 space. Thus, a match generated by the number rule will contain two submatches.
 
-We can use Ruby's block syntax to create a module that will be attached to these
-matches when they are created and is used to lazily extend them when we want to
-interpret them. The following example shows one way to do this.
+We can define methods inside a set of curly braces that will be used to extend
+matches when they are created. This works in similar fashion to using Ruby's
+blocks. Let's extend the `Addition` grammar using this technique.
 
     grammar Addition
       rule additive
         (number plus term:(additive | number)) {
           def value
@@ -316,29 +314,31 @@
 the additive and number rules. These blocks contain methods that will be present
 on all match objects that result from matches of those particular rules. It's
 easiest to explain what is going on here by starting with the lowest level
 block, which is defined within the number rule.
 
-The semantic block associated with the number rule defines one method, value.
+The semantic block associated with the number rule defines one method, `value`.
 Inside this method, we can see that the value of a number match is determined to
-be its text value, stripped of white space and converted to an integer. Remember
-that matches are simply strings, so the `strip` method in this case is actually
-`String#strip`.
+be its text value, stripped of white space and converted to an integer.
+[Remember](background.html) that matches are simply strings, so the `strip`
+method in this case is actually
+[String#strip](http://ruby-doc.org/core/classes/String.html#M000820).
 
-The `additive` rule also extends its matches with a value method. Notice the use
-of the `term` label within the rule definition. This label allows the match that
-is created by either the additive or the number rule to be retrieved using the
-`term` label. The value of an additive is determined to be the values of its
+The `additive` rule also extends its matches with a `value` method. Notice the
+use of the `term` label within the rule definition. This label allows the match
+that is created by either the additive or the number rule to be retrieved using
+the `term` label. The value of an additive is determined to be the values of its
 `number` and `term` matches added together using Ruby's addition operator.
 
 Since additive is the first rule defined in the grammar, any match that results
 from parsing a string with this grammar will have a `value` method that can be
 used to recursively calculate the collective value of the entire match tree.
 
-To give it a try, save the code for the Addition grammar in a file called
-addition.citrus. Next, assuming you have the Citrus gem installed, try the
-following sequence of commands in a terminal.
+To give it a try, save the code for the `Addition` grammar in a file called
+addition.citrus. Next, assuming you have the Citrus
+[gem](https://rubygems.org/gems/citrus) installed, try the following sequence of
+commands in a terminal.
 
     $ irb
     > require 'citrus'
      => true
     > Citrus.load 'addition'
@@ -347,9 +347,16 @@
      => #<Citrus::Match ...
     > m.value
      => 6
 
 Congratulations! You just ran your first piece of Citrus code.
+
+One interesting thing to notice about the above sequence of commands is the
+return value of [Citrus#load](api/classes/Citrus.html#M000003). When you use
+`Citrus.load` to
+load a grammar file (and likewise [Citrus#eval](api/classes/Citrus.html#M000004) to evaluate
+a raw string of grammar code), the return value is an array of all the grammars
+present in that file.
 
 Take a look at 
 [examples/calc.citrus](http://github.com/mjijackson/citrus/blob/master/examples/calc.citrus)
 for an example of a calculator that is able to parse and evaluate more complex 
 mathematical expressions.