Adding blanklines and indenting rationale codes.

2 files changed, 88 insertions, 79 deletions

diff --git a/specs/~dynamic-names.json b/specs/~dynamic-names.json
index 8b4c8af..8264d21 100644
--- a/specs/~dynamic-names.json
+++ b/specs/~dynamic-names.json
@@ -1,5 +1,5 @@
 {
-  "overview": "Rationale: this special notation was introduced primarily to allow the dynamic\nloading of partials. The main advantage that this notation offers is to allow\ndynamic loading of partials, which is particularly useful in cases where\npolymorphic data needs to be rendered in different ways. Such cases would\notherwise be possible to render only with solutions that are convoluted,\ninefficient, or both.\nExample.\nLet's consider the following data:\n    items: [\n      { content: 'Hello, World!' },\n      { url: 'http://example.com/foo.jpg' },\n      { content: 'Some text' },\n      { content: 'Some other text' },\n      { url: 'http://example.com/bar.jpg' },\n      { url: 'http://example.com/baz.jpg' },\n      { content: 'Last text here' }\n    ]\nThe goal is to render the different types of items in different ways. The\nitems having a key named `content` should be rendered with the template\n`text.mustache`:\n    {{!image.mustache}}\n    <img src=\"{{url}}\"/>\nAnd the items having a key named `url` should be rendered with the template\n`image.mustache`:\n    {{!text.mustache}}\n    {{content}}\nThere are already several ways to achieve this goal, here below are\nillustrated and discussed the most significant solutions to this problem.\nUsing Pre-Processing\nThe idea is to use a secondary templating mechanism to dynamically generate\nthe template that will be rendered.\nThe template that our secondary templating mechanism generates might look\nlike this:\n  {{!template.mustache}}\n  {{items.1.content}}\n  <img src=\"{{items.2.url}}\"/>\n  {{items.3.content}}\n  {{items.4.content}}\n  <img src=\"{{items.5.url}}\"/>\n  <img src=\"{{items.6.url}}\"/>\n  {{items.7.content}}\nThis solutions offers the advantages of having more control over the template\nand minimizing the template blocks to the essential ones.\nThe drawbacks are the rendering speed and the complexity that the secondary\ntemplating mechanism requires.\nUsing Lambdas\nThe idea is to inject functions into the data that will be later called from\nthe template.\nThis way the data will look like this:\n  items: [\n    {\n      content: 'Hello, World!',\n      html: function() { return '{{>text}}'; }\n    },\n    {\n      url: 'http://example.com/foo.jpg',\n      html: function() { return '{{>image}}'; }\n    },\n    {\n      content: 'Some text',\n      html: function() { return '{{>text}}'; }\n    },\n    {\n      content: 'Some other text',\n      html: function() { return '{{>text}}'; }\n    },\n    {\n      url: 'http://example.com/bar.jpg',\n      html: function() { return '{{>image}}'; }\n    },\n    {\n      url: 'http://example.com/baz.jpg',\n      html: function() { return '{{>image}}'; }\n    },\n    {\n      content: 'Last text here',\n      html: function() { return '{{>text}}'; }\n    }\n  ]\nAnd the template will look like this:\n  {{!template.mustache}}\n  {{#items}}\n  {{{html}}}\n  {{/items}}\nThe advantage this solution offers is to have a light main template.\nThe drawback is that the data needs to embed logic and template tags in\nit.\nUsing If-Else Blocks\nThe idea is to put some logic into the main template so it can select the\ntemplates at rendering time:\n  {{!template.mustache}}\n  {{#items}}\n  {{#url}}\n  {{>image}}\n  {{/url}}\n  {{#content}}\n  {{>text}}\n  {{/content}}\n  {{/items}}\nThe main advantage of this solution is that it works without adding any\noverhead fields to the data. It also documents which external templates are\nappropriate for expansion in this position.\nThe drawback is that this solution isn't optimal for heterogeneous data sets\nas the main template grows linearly with the number of polymorphic variants.\nUsing Dynamic Names\nThis is the solution proposed by this spec.\nThe idea is to load partials dynamically.\nThis way the data items have to be tagged with the corresponding partial name:\n  items: [\n    { content: 'Hello, World!',          dynamic: 'text' },\n    { url: 'http://example.com/foo.jpg', dynamic: 'image' },\n    { content: 'Some text',              dynamic: 'text' },\n    { content: 'Some other text',        dynamic: 'text' },\n    { url: 'http://example.com/bar.jpg', dynamic: 'image' },\n    { url: 'http://example.com/baz.jpg', dynamic: 'image' },\n    { content: 'Last text here',         dynamic: 'text' }\n  ]\nAnd the template would simple look like this:\n  {{!template.mustache}}\n  {{#items}}\n  {{>*dynamic}}\n  {{/items}}\nSummary:\n+----------------+---------------------+-------------------------------------+\n|    Approach    |        Pros         |                Cons                 |\n+----------------+---------------------+-------------------------------------+\n| Pre-Processing | Essential template, | Secondary templating system needed, |\n|                | more control        | slower rendering                    |\n| Lambdas        | Slim template       | Data tagging, logic in data         |\n| If Blocks      | No data overhead,   | Template linear growth              |\n|                | self-documenting    |                                     |\n| Dynamic Names  | Slim template       | Data tagging                        |\n+----------------+---------------------+-------------------------------------+\n\nDynamic Names are a special notation to dynamically determine a tag's content.\n\nDynamic Names MUST be a non-whitespace character sequence NOT containing\nthe current closing delimiter. A Dynamic Name consists of an asterisk,\nfollowed by a dotted name. The dotted name follows the same notation as in an\nInterpolation tag.\n\nThis tag's dotted name, which is the Dynamic Name excluding the\nleading asterisk, references a key in the context whose value will be used in\nplace of the Dynamic Name itself as content of the tag. The dotted name\nresolution produces the same value as an Interpolation tag and does not affect\nthe context for further processing.\n\nSet Delimiter tags MUST NOT affect the resolution of a Dynamic Name. The\nDynamic Names MUST be resolved against the context stack local to the tag.\nFailed resolution of the dynamic name SHOULD result in nothing being rendered.\n\nEngines that implement Dynamic Names MUST support their use in Partial tags.\nIn engines that also implement the optional inheritance spec, Dynamic Names\ninside Parent tags SHOULD be supported as well. Dynamic Names cannot be\nresolved more than once (Dynamic Names cannot be nested).\n",
+  "overview": "Rationale: this special notation was introduced primarily to allow the dynamic\nloading of partials. The main advantage that this notation offers is to allow\ndynamic loading of partials, which is particularly useful in cases where\npolymorphic data needs to be rendered in different ways. Such cases would\notherwise be possible to render only with solutions that are convoluted,\ninefficient, or both.\nExample.\nLet's consider the following data:\n\n    items: [\n      { content: 'Hello, World!' },\n      { url: 'http://example.com/foo.jpg' },\n      { content: 'Some text' },\n      { content: 'Some other text' },\n      { url: 'http://example.com/bar.jpg' },\n      { url: 'http://example.com/baz.jpg' },\n      { content: 'Last text here' }\n    ]\nThe goal is to render the different types of items in different ways. The\nitems having a key named `content` should be rendered with the template\n`text.mustache`:\n\n    {{!text.mustache}}\n    {{content}}\nAnd the items having a key named `url` should be rendered with the template\n`image.mustache`:\n\n    {{!image.mustache}}\n    <img src=\"{{url}}\"/>\nThere are already several ways to achieve this goal, here below are\nillustrated and discussed the most significant solutions to this problem.\nUsing Pre-Processing\nThe idea is to use a secondary templating mechanism to dynamically generate\nthe template that will be rendered.\nThe template that our secondary templating mechanism generates might look\nlike this:\n\n    {{!template.mustache}}\n    {{items.1.content}}\n    <img src=\"{{items.2.url}}\"/>\n    {{items.3.content}}\n    {{items.4.content}}\n    <img src=\"{{items.5.url}}\"/>\n    <img src=\"{{items.6.url}}\"/>\n    {{items.7.content}}\nThis solutions offers the advantages of having more control over the template\nand minimizing the template blocks to the essential ones.\nThe drawbacks are the rendering speed and the complexity that the secondary\ntemplating mechanism requires.\nUsing Lambdas\nThe idea is to inject functions into the data that will be later called from\nthe template.\nThis way the data will look like this:\n\n    items: [\n      {\n        content: 'Hello, World!',\n        html: function() { return '{{>text}}'; }\n      },\n      {\n        url: 'http://example.com/foo.jpg',\n        html: function() { return '{{>image}}'; }\n      },\n      {\n        content: 'Some text',\n        html: function() { return '{{>text}}'; }\n      },\n      {\n        content: 'Some other text',\n        html: function() { return '{{>text}}'; }\n      },\n      {\n        url: 'http://example.com/bar.jpg',\n        html: function() { return '{{>image}}'; }\n      },\n      {\n        url: 'http://example.com/baz.jpg',\n        html: function() { return '{{>image}}'; }\n      },\n      {\n        content: 'Last text here',\n        html: function() { return '{{>text}}'; }\n      }\n    ]\nAnd the template will look like this:\n\n    {{!template.mustache}}\n    {{#items}}\n    {{{html}}}\n    {{/items}}\nThe advantage this solution offers is to have a light main template.\nThe drawback is that the data needs to embed logic and template tags in\nit.\nUsing If-Else Blocks\nThe idea is to put some logic into the main template so it can select the\ntemplates at rendering time:\n\n    {{!template.mustache}}\n    {{#items}}\n    {{#url}}\n    {{>image}}\n    {{/url}}\n    {{#content}}\n    {{>text}}\n    {{/content}}\n    {{/items}}\nThe main advantage of this solution is that it works without adding any\noverhead fields to the data. It also documents which external templates are\nappropriate for expansion in this position.\nThe drawback is that this solution isn't optimal for heterogeneous data sets\nas the main template grows linearly with the number of polymorphic variants.\nUsing Dynamic Names\nThis is the solution proposed by this spec.\nThe idea is to load partials dynamically.\nThis way the data items have to be tagged with the corresponding partial name:\n\n    items: [\n      { content: 'Hello, World!',          dynamic: 'text' },\n      { url: 'http://example.com/foo.jpg', dynamic: 'image' },\n      { content: 'Some text',              dynamic: 'text' },\n      { content: 'Some other text',        dynamic: 'text' },\n      { url: 'http://example.com/bar.jpg', dynamic: 'image' },\n      { url: 'http://example.com/baz.jpg', dynamic: 'image' },\n      { content: 'Last text here',         dynamic: 'text' }\n    ]\nAnd the template would simple look like this:\n\n    {{!template.mustache}}\n    {{#items}}\n    {{>*dynamic}}\n    {{/items}}\nSummary:\n\n  +----------------+---------------------+-----------------------------------+\n  |    Approach    |        Pros         |               Cons                |\n  +----------------+---------------------+-----------------------------------+\n  | Pre-Processing | Essential template, | Secondary templating system       |\n  |                | more control        | needed, slower rendering          |\n  | Lambdas        | Slim template       | Data tagging, logic in data       |\n  | If Blocks      | No data overhead,   | Template linear growth            |\n  |                | self-documenting    |                                   |\n  | Dynamic Names  | Slim template       | Data tagging                      |\n  +----------------+---------------------+-----------------------------------+\nDynamic Names are a special notation to dynamically determine a tag's content.\n\nDynamic Names MUST be a non-whitespace character sequence NOT containing\nthe current closing delimiter. A Dynamic Name consists of an asterisk,\nfollowed by a dotted name. The dotted name follows the same notation as in an\nInterpolation tag.\n\nThis tag's dotted name, which is the Dynamic Name excluding the\nleading asterisk, references a key in the context whose value will be used in\nplace of the Dynamic Name itself as content of the tag. The dotted name\nresolution produces the same value as an Interpolation tag and does not affect\nthe context for further processing.\n\nSet Delimiter tags MUST NOT affect the resolution of a Dynamic Name. The\nDynamic Names MUST be resolved against the context stack local to the tag.\nFailed resolution of the dynamic name SHOULD result in nothing being rendered.\n\nEngines that implement Dynamic Names MUST support their use in Partial tags.\nIn engines that also implement the optional inheritance spec, Dynamic Names\ninside Parent tags SHOULD be supported as well. Dynamic Names cannot be\nresolved more than once (Dynamic Names cannot be nested).\n",
   "tests": [
     {
       "name": "Basic Behavior - Partial",
diff --git a/specs/~dynamic-names.yml b/specs/~dynamic-names.yml
index 0823764..0c6561d 100644
--- a/specs/~dynamic-names.yml
+++ b/specs/~dynamic-names.yml
@@ -7,6 +7,7 @@ overview: |
   inefficient, or both.
   Example.
   Let's consider the following data:
+
       items: [
         { content: 'Hello, World!' },
         { url: 'http://example.com/foo.jpg' },
@@ -19,12 +20,14 @@ overview: |
   The goal is to render the different types of items in different ways. The
   items having a key named `content` should be rendered with the template
   `text.mustache`:
-      {{!image.mustache}}
-      <img src="{{url}}"/>
-  And the items having a key named `url` should be rendered with the template
-  `image.mustache`:
+
       {{!text.mustache}}
       {{content}}
+  And the items having a key named `url` should be rendered with the template
+  `image.mustache`:
+
+      {{!image.mustache}}
+      <img src="{{url}}"/>
   There are already several ways to achieve this goal, here below are
   illustrated and discussed the most significant solutions to this problem.
   Using Pre-Processing
@@ -32,14 +35,15 @@ overview: |
   the template that will be rendered.
   The template that our secondary templating mechanism generates might look
   like this:
-    {{!template.mustache}}
-    {{items.1.content}}
-    <img src="{{items.2.url}}"/>
-    {{items.3.content}}
-    {{items.4.content}}
-    <img src="{{items.5.url}}"/>
-    <img src="{{items.6.url}}"/>
-    {{items.7.content}}
+
+      {{!template.mustache}}
+      {{items.1.content}}
+      <img src="{{items.2.url}}"/>
+      {{items.3.content}}
+      {{items.4.content}}
+      <img src="{{items.5.url}}"/>
+      <img src="{{items.6.url}}"/>
+      {{items.7.content}}
   This solutions offers the advantages of having more control over the template
   and minimizing the template blocks to the essential ones.
   The drawbacks are the rendering speed and the complexity that the secondary
@@ -48,56 +52,59 @@ overview: |
   The idea is to inject functions into the data that will be later called from
   the template.
   This way the data will look like this:
-    items: [
-      {
-        content: 'Hello, World!',
-        html: function() { return '{{>text}}'; }
-      },
-      {
-        url: 'http://example.com/foo.jpg',
-        html: function() { return '{{>image}}'; }
-      },
-      {
-        content: 'Some text',
-        html: function() { return '{{>text}}'; }
-      },
-      {
-        content: 'Some other text',
-        html: function() { return '{{>text}}'; }
-      },
-      {
-        url: 'http://example.com/bar.jpg',
-        html: function() { return '{{>image}}'; }
-      },
-      {
-        url: 'http://example.com/baz.jpg',
-        html: function() { return '{{>image}}'; }
-      },
-      {
-        content: 'Last text here',
-        html: function() { return '{{>text}}'; }
-      }
-    ]
+
+      items: [
+        {
+          content: 'Hello, World!',
+          html: function() { return '{{>text}}'; }
+        },
+        {
+          url: 'http://example.com/foo.jpg',
+          html: function() { return '{{>image}}'; }
+        },
+        {
+          content: 'Some text',
+          html: function() { return '{{>text}}'; }
+        },
+        {
+          content: 'Some other text',
+          html: function() { return '{{>text}}'; }
+        },
+        {
+          url: 'http://example.com/bar.jpg',
+          html: function() { return '{{>image}}'; }
+        },
+        {
+          url: 'http://example.com/baz.jpg',
+          html: function() { return '{{>image}}'; }
+        },
+        {
+          content: 'Last text here',
+          html: function() { return '{{>text}}'; }
+        }
+      ]
   And the template will look like this:
-    {{!template.mustache}}
-    {{#items}}
-    {{{html}}}
-    {{/items}}
+
+      {{!template.mustache}}
+      {{#items}}
+      {{{html}}}
+      {{/items}}
   The advantage this solution offers is to have a light main template.
   The drawback is that the data needs to embed logic and template tags in
   it.
   Using If-Else Blocks
   The idea is to put some logic into the main template so it can select the
   templates at rendering time:
-    {{!template.mustache}}
-    {{#items}}
-    {{#url}}
-    {{>image}}
-    {{/url}}
-    {{#content}}
-    {{>text}}
-    {{/content}}
-    {{/items}}
+
+      {{!template.mustache}}
+      {{#items}}
+      {{#url}}
+      {{>image}}
+      {{/url}}
+      {{#content}}
+      {{>text}}
+      {{/content}}
+      {{/items}}
   The main advantage of this solution is that it works without adding any
   overhead fields to the data. It also documents which external templates are
   appropriate for expansion in this position.
@@ -107,32 +114,34 @@ overview: |
   This is the solution proposed by this spec.
   The idea is to load partials dynamically.
   This way the data items have to be tagged with the corresponding partial name:
-    items: [
-      { content: 'Hello, World!',          dynamic: 'text' },
-      { url: 'http://example.com/foo.jpg', dynamic: 'image' },
-      { content: 'Some text',              dynamic: 'text' },
-      { content: 'Some other text',        dynamic: 'text' },
-      { url: 'http://example.com/bar.jpg', dynamic: 'image' },
-      { url: 'http://example.com/baz.jpg', dynamic: 'image' },
-      { content: 'Last text here',         dynamic: 'text' }
-    ]
+
+      items: [
+        { content: 'Hello, World!',          dynamic: 'text' },
+        { url: 'http://example.com/foo.jpg', dynamic: 'image' },
+        { content: 'Some text',              dynamic: 'text' },
+        { content: 'Some other text',        dynamic: 'text' },
+        { url: 'http://example.com/bar.jpg', dynamic: 'image' },
+        { url: 'http://example.com/baz.jpg', dynamic: 'image' },
+        { content: 'Last text here',         dynamic: 'text' }
+      ]
   And the template would simple look like this:
-    {{!template.mustache}}
-    {{#items}}
-    {{>*dynamic}}
-    {{/items}}
+
+      {{!template.mustache}}
+      {{#items}}
+      {{>*dynamic}}
+      {{/items}}
   Summary:
-  +----------------+---------------------+-------------------------------------+
-  |    Approach    |        Pros         |                Cons                 |
-  +----------------+---------------------+-------------------------------------+
-  | Pre-Processing | Essential template, | Secondary templating system needed, |
-  |                | more control        | slower rendering                    |
-  | Lambdas        | Slim template       | Data tagging, logic in data         |
-  | If Blocks      | No data overhead,   | Template linear growth              |
-  |                | self-documenting    |                                     |
-  | Dynamic Names  | Slim template       | Data tagging                        |
-  +----------------+---------------------+-------------------------------------+
 
+    +----------------+---------------------+-----------------------------------+
+    |    Approach    |        Pros         |               Cons                |
+    +----------------+---------------------+-----------------------------------+
+    | Pre-Processing | Essential template, | Secondary templating system       |
+    |                | more control        | needed, slower rendering          |
+    | Lambdas        | Slim template       | Data tagging, logic in data       |
+    | If Blocks      | No data overhead,   | Template linear growth            |
+    |                | self-documenting    |                                   |
+    | Dynamic Names  | Slim template       | Data tagging                      |
+    +----------------+---------------------+-----------------------------------+
   Dynamic Names are a special notation to dynamically determine a tag's content.
 
   Dynamic Names MUST be a non-whitespace character sequence NOT containing