man/mustache.5.ron in mustache-0.9.2 vs man/mustache.5.ron in mustache-0.10.0

@@ -39,28 +39,29 @@
 values. This document explains the different types of Mustache tags.
 
 
 ## TAG TYPES
 
-Tags are indicated by the double mustaches. `{{name}}` is a tag. Let's
-talk about the different types of tags.
+Tags are indicated by the double mustaches. `{{name}}` is a tag, as is
+`{{#name}}`. Let's talk about the different types of tags.
 
 
 ### Variables
 
 The most basic tag is the variable. A `{{name}}` tag in a basic
-template will try to call the `name` method on your view. If there is
-no `name` method, an exception will be raised.
+template will try to find the `name` key or method on your view. If
+there is no `name` method, nothing will be rendered.
 
 All variables are HTML escaped by default. If you want to return
 unescaped HTML, use the triple mustache: `{{{name}}}`.
 
 You can also use `&` to unescape a variable: `{{& name}}`. This may be
 useful when changing delimiters (see "Set Delimter" below).
 
 By default a variable "miss" returns an empty string. This can usually
-be configured in your Mustache library.
+be configured in your Mustache library. The Ruby version of Mustache
+supports raising an exception in this situation, for instance.
 
 Template:
 
     * {{name}}
     * {{age}}
@@ -79,72 +80,92 @@
     * Chris
     *
     * <b>GitHub</b>
     * <b>GitHub</b>
 
-### Boolean Sections
 
+### Sections
+
+Sections render blocks of text one or more times, depending on the
+value of the referenced tag.
+
 A section begins with a pound and ends with a slash. That is,
 `{{#person}}` begins a "person" section while `{{/person}}` ends it.
 
-If the `person` key exists and calling it returns false, the HTML
-between the pound and slash will not be displayed.
+If the `person` key exists and calling it returns false or an empty
+list, the HTML between the pound and slash will not be displayed.
 
-If the `person` method exists and calling it returns true, the HTML
-between the pound and slash will be rendered and displayed.
+If the `person` method exists and calling it returns true or an
+object, the HTML between the pound and slash will be rendered and
+displayed exactly one time. The object that was returned by the
+`person` method will become the context of the block, as well.
 
+If the `person` method exists and calling it returns a non-empty list,
+the text in the block will be displayed once for each item in the
+list. The context of the block will be set to the current item for
+each iteration. In this way we can loop over collections.
+
 Template:
 
     {{#person}}
       Shown!
     {{/person}}
     {{#anything_else}}
       Never shown!
     {{/anything_else}}
+    {{#repo}}
+      <b>{{name}}</b>
+    {{/repo}}
 
 Hash:
 
     {
-      "person": true
+      "person": true,
+      "repo": [
+        { "name": "resque" },
+        { "name": "hub" },
+        { "name": "rip" },
+      ]
     }
 
 Output:
 
     Shown!
+    <b>resque</b>
+    <b>hub</b>
+    <b>rip</b>
 
-### Enumerable Sections
 
-Enumerable sections are syntactically identical to boolean sections in
-that they begin with a pound and end with a slash. The difference,
-however, is in the view: if the method called returns an enumerable,
-the section is repeated as the enumerable is iterated over.
+### Inverted Sections
 
-Each item in the enumerable is expected to be a hash which will then
-become the context of the corresponding iteration. In this way we can
-construct loops.
+An inverted section begins with a caret (hat) and ends with a
+slash. That is `{{^person}}` begins a "person" inverted section while
+`{{/person}}` ends it.
 
+While sections can be used to render text one or more times based on the
+value of the key given, inverted sections may render text once based
+on the inverse value of the key given. That is, they will be rendered
+if the key doesn't exist, is false, or is an empty list.
+
 Template:
 
     {{#repo}}
       <b>{{name}}</b>
     {{/repo}}
+    {{^repo}}
+      No repos :(
+    {{/repo}}
 
 Hash:
 
     {
-      "repo": [
-        { "name": "resque" },
-        { "name": "hub" },
-        { "name": "rip" },
-      ]
+      "repo": []
     }
 
 Output:
 
-    <b>resque</b>
-    <b>hub</b>
-    <b>rip</b>
+    No repos :(
 
 
 ### Comments
 
 Comments begin with a bang and are ignored. The following template:
@@ -158,14 +179,28 @@
 
 ### Partials
 
 Partials begin with a greater than sign, like `{{> box}}`.
 
-It is useful to think of partials as a "template expansion" - that is,
-the actual partial tag will be replaced with the content of the
-partial. Therefor partials share the current context.
+Partials are rendered at runtime (as opposed to compile time), so
+recursive partials are possible. Just avoid infinite loops.
 
+They also inherit the calling context. Whereas in ERB you may have
+this:
+
+    <%= partial :next_more, :start => start, :size => size %>
+
+Mustache requires only this:
+
+    {{> next_more}}
+
+Why? Because the `next_more.mustache` file will inherit the `size` and
+`start` methods from the calling context.
+
+In this way you may want to think of partials as includes, or template
+expansion, even though it's not literally true.
+
 For example, this template and partial:
 
     base.mustache:
     <h2>Names</h2>
     {{# names }}
@@ -218,6 +253,6 @@
 
 
 ## SEE ALSO
 
 mustache(1), mustache(7), gem(1),
-<http://defunkt.github.com/mustache/>
+<http://mustache.github.com/>