Expand the inheritance overview

2 files changed, 39 insertions, 13 deletions

diff --git a/specs/~inheritance.json b/specs/~inheritance.json
index 809b693..2d4539d 100644
--- a/specs/~inheritance.json
+++ b/specs/~inheritance.json
@@ -1,6 +1,6 @@
 {
   "__ATTN__": "Do not edit this file; changes belong in the appropriate YAML file.",
-  "overview": "Parent tags are used to expand an external template into the current template,\nwith optional parameters delimited by block tags.\n\nThese tags' content MUST be a non-whitespace character sequence NOT containing\nthe current closing delimiter; each Parent tag MUST be followed by an End\nSection tag with the same content within the matching parent tag.\n\nBlock tags are used inside of parent tags to assign data onto the context\nstack prior to rendering the parent template. Outside of parent tags, block\ntags are used to indicate where value set in the parent tag should be placed.\nIf no value is set then the content in between the block tags, if any, is\nrendered.\n",
+  "overview": "Like partials, Parent tags are used to expand an external template into the\ncurrent template. Contrary to partials, Parent tags may contain optional\narguments delimited by block tags. For this reason, Parent tags may also be\nreferred to as Parametric Partials.\n\nThe Parent tags' content MUST be a non-whitespace character sequence NOT\ncontaining the current closing delimiter; each Parent tag MUST be followed by\nan End Section tag with the same content within the matching Parent tag.\n\nThis tag's content names the Parent template to inject. Set Delimiter tags\nMUST NOT affect the parsing of a Parent template. The Parent MUST be rendered\nagainst the context stack local to the tag. If the named Parent cannot be\nfound, the empty string SHOULD be used instead, as in interpolations.\n\nParent tags SHOULD be treated as standalone when appropriate. If this tag is\nused standalone, any whitespace preceding the tag should be treated as\nindentation, and prepended to each line of the Parent before rendering.\n\nThe Block tags' content MUST be a non-whitespace character sequence NOT\ncontaining the current closing delimiter. Each Block tag MUST be followed by\nan End Section tag with the same content within the matching Block tag. This\ntag's content determines the parameter or argument name.\n\nBlock tags may appear both inside and outside of Parent tags. In both cases,\nthey specify a position within the template that can be overridden; it is a\nparameter of the containing template. The template text between the Block tag\nand its matching End Section tag defines the default content to render when\nthe parameter is not overridden from outside.\n\nIn addition, when used inside of a Parent tag, the template text between a\nBlock tag and its matching End Section tag defines content that replaces the\ndefault defined in the Parent template. This content is the argument passed\nto the Parent template.\n\nThe practice of injecting an external template using a Parent tag is referred\nto as inheritance. If the Parent tag includes a Block tag that overrides a\nparameter of the Parent template, this may also be referred to as\nsubstitution.\n",
   "tests": [
     {
       "name": "Default",
diff --git a/specs/~inheritance.yml b/specs/~inheritance.yml
index 8881ee5..46eb625 100644
--- a/specs/~inheritance.yml
+++ b/specs/~inheritance.yml
@@ -1,16 +1,42 @@
 overview: |
-  Parent tags are used to expand an external template into the current template,
-  with optional parameters delimited by block tags.
-
-  These tags' content MUST be a non-whitespace character sequence NOT containing
-  the current closing delimiter; each Parent tag MUST be followed by an End
-  Section tag with the same content within the matching parent tag.
-
-  Block tags are used inside of parent tags to assign data onto the context
-  stack prior to rendering the parent template. Outside of parent tags, block
-  tags are used to indicate where value set in the parent tag should be placed.
-  If no value is set then the content in between the block tags, if any, is
-  rendered.
+  Like partials, Parent tags are used to expand an external template into the
+  current template. Contrary to partials, Parent tags may contain optional
+  arguments delimited by block tags. For this reason, Parent tags may also be
+  referred to as Parametric Partials.
+
+  The Parent tags' content MUST be a non-whitespace character sequence NOT
+  containing the current closing delimiter; each Parent tag MUST be followed by
+  an End Section tag with the same content within the matching Parent tag.
+
+  This tag's content names the Parent template to inject. Set Delimiter tags
+  MUST NOT affect the parsing of a Parent template. The Parent MUST be rendered
+  against the context stack local to the tag. If the named Parent cannot be
+  found, the empty string SHOULD be used instead, as in interpolations.
+
+  Parent tags SHOULD be treated as standalone when appropriate. If this tag is
+  used standalone, any whitespace preceding the tag should be treated as
+  indentation, and prepended to each line of the Parent before rendering.
+
+  The Block tags' content MUST be a non-whitespace character sequence NOT
+  containing the current closing delimiter. Each Block tag MUST be followed by
+  an End Section tag with the same content within the matching Block tag. This
+  tag's content determines the parameter or argument name.
+
+  Block tags may appear both inside and outside of Parent tags. In both cases,
+  they specify a position within the template that can be overridden; it is a
+  parameter of the containing template. The template text between the Block tag
+  and its matching End Section tag defines the default content to render when
+  the parameter is not overridden from outside.
+
+  In addition, when used inside of a Parent tag, the template text between a
+  Block tag and its matching End Section tag defines content that replaces the
+  default defined in the Parent template. This content is the argument passed
+  to the Parent template.
+
+  The practice of injecting an external template using a Parent tag is referred
+  to as inheritance. If the Parent tag includes a Block tag that overrides a
+  parameter of the Parent template, this may also be referred to as
+  substitution.
 tests:
   - name: Default
     desc: Default content should be rendered if the block isn't overridden