Update doc with v2.1.0 features

docs/boxes-man-1.html

@@ -226,14 +226,14 @@ design names. This option is normally used stand-alone; if
 used in combination with other options, behavior is
 undefined. The <i>query</i> argument is a comma-separated
 list of tags which can be present on a design in order to
-match. A tag may optionally be prefixed with <i>+</i> in
+match. A tag may optionally be prefixed with <code>+</code> in
-order to require that it be present, or with <i>-</i> in
+order to require that it be present, or with <code>-</code> in
 order to exclude designs which have that tag. Each tag can
 only occur once per query. <br>
 This option is intended for use by scripts. Alias names are
 printed below their primary design name, and postfixed with
-<i>(alias)</i>. <br>
+<code>(alias)</code>. <br>
-Example: <i>boxes -q programming,-comment</i></p>
+Example: <code>boxes -q programming,-comment</code></p>
 
 <p style="margin-left:11%;"><b>-r</b></p>
 

docs/config-syntax.html

@@ -15,6 +15,18 @@ string or something).
 <pre><b>BOX</b> <i>design_name</i>
     entries_and_blocks
 <b>END</b> <i>design_name</i></pre>
+
+A box design may optionally have **alias names** in addition to the primary design name (since *boxes* v2.1.0).
+Alias names are appended to the primary design name as a comma-separated list. For example:
+
+<pre><b>BOX</b> <i>design_name</i>, <i>alias1</i>, <i>alias2</i>
+    entries_and_blocks
+<b>END</b> <i>design_name</i></pre>
+
+After the `END` statement, only the primary design name is specified. There is no practical limit to the number of
+alias names. Every primary design name and alias name must be unique across the entire config file, including any
+parent config files.
+
 Every box design definition must have at least a `SHAPE` block, an `ELASTIC` list, and a `SAMPLE` block.
 
 ### Sample Block
@@ -27,6 +39,9 @@ this way, the box can be shown in an environment in which it might actually be u
 the [boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"} for many
 examples).
 
+The sample itself should be indented by *4 spaces*. This is because all other samples in the config file are also
+indented by this value, which simply looks better on the design list.
+
 The `ENDS` statement must stand on a line of its own, although it may be indented. Such a line cannot occur as part of
 the sample itself.\\
 The `SAMPLE` block is a required entry in every box design definition.
@@ -40,7 +55,10 @@ The `SAMPLE` block is a required entry in every box design definition.
 }</PRE>
 <i>`shape_name`</i> may be one of `nw`, `nnw`, `n`, `nne`, `ne`, `ene`, `e`, `ese`, `se`, `sse`, `s`, `ssw`, `sw`,
 `wsw`, `w`, or `wnw`, corresponding to the [figure shown earlier](config-general.html).
-The `string_list` represents the shape itself, line by line. Note that all lines must have equal length. Add extra spaces if necessary. Not also that double quotes (`"`) which appear as part of a string must be escaped by a preceding backslash, so as not to terminate the string early. Consequently, all occurrences of backslashes must also be escaped by adding additional backslashes. The recommended process for creating a string is thus:
+The `string_list` represents the shape itself, line by line. Note that all lines must have equal length. Add extra
+spaces if necessary. Not also that double quotes (`"`) which appear as part of a string must be escaped by a preceding
+backslash, so as not to terminate the string early. Consequently, all occurrences of backslashes must also be escaped
+by adding additional backslashes. The recommended process for creating a string is thus:
 
 1. Type in the string as you think it should look.
 1. Make your editor double all backslashes within the string.
@@ -58,13 +76,16 @@ Here are a few examples of valid entries in a `SHAPE` block:
     ene ()
     s ("\"")
 
-The [`delimiter` statement](#delim) can be used to redefine the string delimiting character and the escape character, thus eliminating the above backslash problem.
+The [`delimiter` statement](#delim) can be used to redefine the string delimiting character and the escape character,
+thus eliminating the above backslash problem.
 The `SHAPE` block is a required entry in every box design definition.
 
 ### Elastic List
 
 <PRE><b>ELASTIC</b> (<i>shape_name</i>, <i>shape_name</i>, ...)</PRE>
-Simply lists the shapes which are *elastic*. Elastic shapes are repeated so that the box can grow and shrink to meet its requested size. Corner shapes may not be elastic. Naturally, there must always be at least one elastic shape per box side. No two neighboring shapes may be elastic. A typical `ELASTIC` entry would look like this:
+Simply lists the shapes which are *elastic*. Elastic shapes are repeated so that the box can grow and shrink to meet
+its requested size. Corner shapes may not be elastic. Naturally, there must always be at least one elastic shape per
+box side. No two neighboring shapes may be elastic. A typical `ELASTIC` entry would look like this:
 
     elastic (n, e, s, w)
 
@@ -77,7 +98,10 @@ The elastic list is a required entry in every box design definition.
     side_or_group_of_sides <i>value</i>
     ...
 }</PRE>
-Defines the default [padding area](config-general.html#padding-area). Possible values for `side_or_group_of_sides` are `all`, `horizontal`, `vertical`, `top`, `left`, `right`, or `bottom`. A padding block may contain an arbitrary number of entries. Entries are read from top to bottom, so that later entries overwrite earlier entries. In the following example:
+Defines the default [padding area](config-general.html#padding-area). Possible values for `side_or_group_of_sides` are
+`all`, `horizontal`, `vertical`, `top`, `left`, `right`, or `bottom`. A padding block may contain an arbitrary number
+of entries. Entries are read from top to bottom, so that later entries overwrite earlier entries. In the following
+example:
 
     padding {
         vertical 3
@@ -85,7 +109,9 @@ Defines the default [padding area](config-general.html#padding-area). Possible v
         left 4
     }
 
-the padding is set to 3 blank lines above the text, 2 spaces to the right of the text, 3 blank lines below the text, and 4 spaces to the left of the text. These values can be overridden by a different specification on the command line using the **-p** option.
+the padding is set to 3 blank lines above the text, 2 spaces to the right of the text, 3 blank lines below the text,
+and 4 spaces to the left of the text. These values can be overridden by a different specification on the command line
+using the **-p** option.
 
 ### Replace and Reverse Statements
 
@@ -93,15 +119,20 @@ the padding is set to 3 blank lines above the text, 2 spaces to the right of the
 ...
 <b>REVERSE</b> "<i>search_pattern</i>" <b>TO</b> "<i>replacement_string</i>"
 ...</PRE>
-These statements are used to perform substitutions on the text surrounded by a box. The `REPLACE` statements are executed on the input text when a box is being created. `REVERSE` statements have the same effect as `REPLACE` statements, but they are executed after a box has been removed.
+These statements are used to perform substitutions on the text surrounded by a box. The `REPLACE` statements are
+executed on the input text when a box is being created. `REVERSE` statements have the same effect as `REPLACE`
+statements, but they are executed after a box has been removed.
 In the simplest case, one string is replaced with another:
 
     replace "\\*/" with "*-/"
     reverse "\\*-/" to "*/"
 
-The `REPLACE` statement in the above example may be used to quote closing comment tags in the C programming language by inserting a dash between the asterisk and the slash. The `REVERSE` statement undoes this effect when the box is removed.
+The `REPLACE` statement in the above example may be used to quote closing comment tags in the C programming language by
+inserting a dash between the asterisk and the slash. The `REVERSE` statement undoes this effect when the box is removed.
 
-The search pattern may be a regular expression, and the replacement string may include backreferences. This gives you quite a powerful means for text modification. The following example is used to insert a space between all characters of the input text:
+The search pattern may be a regular expression, and the replacement string may include backreferences. This gives you
+quite a powerful means for text modification. The following example is used to insert a space between all characters of
+the input text:
 
     replace "(.)" with "$1 "
     reverse "(.) " to "$1"
@@ -130,9 +161,11 @@ come in handy.
 ### Indentation Mode
 
 <PRE><b>INDENT</b> "<i>indentmode</i>"</PRE>
-This sets the default indentation mode for a design. Possible values for <i>`indentmode`</i> are `"box"`, `"text"`, and `"none"`. The indent mode specifies how existing text indentation is treated.
+This sets the default indentation mode for a design. Possible values for <i>`indentmode`</i> are `"box"`, `"text"`,
+and `"none"`. The indent mode specifies how existing text indentation is treated.
 
-  - `"box"`, which is the default setting, will cause the box to be indented by the same number of spaces as the text was. The text itself will not be indented within the box, though.
+  - `"box"`, which is the default setting, will cause the box to be indented by the same number of spaces as the text
+    was. The text itself will not be indented within the box, though.
   - `"text"` will not indent the box, but instead retain the text indentation inside the box.
   - `"none"` will simply throw away all indentation.
 
@@ -143,41 +176,76 @@ For examples on all three indentation modes please refer to the [example page]({
 ### String Delimiters
 
 <PRE><b>DELIM[ITER]</b> <i>chars</i></PRE>
-*`chars`* must consist of exactly two characters, the first of which being the escape character, and the second the string delimiter. No quotes must be placed around those two characters.
-The effect is that until the end of the current design or until the next `DELIMITER` statement, all strings must be enclosed not by the usual double quotes (`"`), but instead by the character you specify.
-Also, the delimiter may be escaped not by the usual backslash (`\`), but instead by the escape character you specify.
-For example, consider the literal string `foo":"\"\\bar`:
 
-    "foo\":\"\\\"\\\\bar"
+*`chars`* must consist of exactly two characters:
+
+1. the escape character (first character, one of `@~?!\`)
+2. the string delimiter (second character, one of `"~'!|`)
+
+No quotes must be placed around those two characters. The effect is that until the end of the current design or until
+the next `DELIMITER` statement, all strings must be enclosed not by the usual double quotes (`"`), but instead by the
+character you specify. Also, the delimiter may be escaped not by the usual backslash (`\`), but instead by the escape
+character you specify. The escape character and the string delimiter must be different characters, of course.  
+For example, consider the literal string `"""""`, which would normally be written like this:
+
+    "\"\"\"\"\""
 
 Using a `DELIMITER` statement, this looks much simpler:
 
-    delimiter ?:
+    delimiter \'
-    :foo"?:"\"\\bar:
+    '"""""'
 
-The escape character may be any character you choose. The string delimiter, however, may only be one out of the following:
+This mechanism is intended for box designs which have a lot of backslash or double quote characters in them.
-
-    "~'`!@%&*=:;<>?/|.\
-
-This set may change, but *boxes* will tell you your choices if you make a mistake.
 
 
 ### Name of Author
 
 <PRE><b>AUTHOR</b> &quot;<i>name_of_author</i>&quot;</PRE>
-Simply states who the person was who coded the box design definition. This entry is used when displaying the list of designs (`boxes -l`). The value is free text, but it is good if some contact information is included, for example `John Doe <john@acme.com>`. These days, such openness with one's email address may not suit everyone, so feel free to give less or differently formatted author information.
+Simply states who the person was who coded the box design definition. This entry is used when displaying the list of
+designs (`boxes -l`). The value is free text, but it is good if some contact information is included, for example
+`John Doe <john@acme.com>`. These days, such openness with one's email address may not suit everyone, so feel free to
+give less or differently formatted author information.
 
 <PRE><b>DESIGNER</b> &quot;<i>name_of_designer</i>&quot;</PRE>
-In contrast to `author`, which tells us who created the config file entry, the `designer` keyword tells us who created the box design itself. In other words, this is the artist who originally created the ASCII artwork.
+In contrast to `author`, which tells us who created the config file entry, the `designer` keyword tells us who created
+the box design itself. In other words, this is the artist who originally created the ASCII artwork.
 
-Please try to give both fields always. Especially in those cases where existing ASCII art from the internet is adapted for use with boxes, it is important (and good manners) to give credit to the original artist.
+Please try to give both fields always. Especially in those cases where existing ASCII art from the internet is adapted
+for use with *boxes*, it is important (and good manners) to give credit to the original artist.
 
 
 ### General Entries
 
 <PRE><b>keyword</b> &quot;<i>string_value</i>&quot;</PRE>
 
-In addition to the author entry, there may be any number of other entries of the above form, giving any kind of information. The [boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"} includes the entries `CREATED`, `REVISION`, and `REVDATE`, to indicate the creation timestamp, revision number, and timestamp of the latest revision, respectively. These other entries are not yet used by *boxes*, though, and will simply be ignored.
+In addition to the author entry, there may be any number of other entries of the above form, giving any kind of
+information. The [boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"}
+includes the entries `CREATED`, `REVISION`, and `REVDATE`, to indicate the creation timestamp, revision number, and
+timestamp of the latest revision, respectively. These other entries are not yet used by *boxes*, though, and will
+simply be ignored.
+
+-----
+
+## Config File Inheritance
+
+A config file may specify one or more other config files as a "parents" (since *boxes* v2.1.0). This means that after
+the config file is read, *boxes* will also read all the parent configs (in order). If a design is found which we don't
+know yet, it is added to the list. In other words, all box designs are "inherited" from the parents, and can be
+overwritten.
+
+This mechanism works on the box design level. You can only override an entire box design, but not parts of one.
+
+The syntax is
+
+<PRE><b>PARENT</b> <i>path_to_parent_config</i></PRE>
+
+The path to the parent config should be an absolute pathname specifying a config file (not a directory). Spaces are
+permitted in this path, and no quotes are used. A parent reference can only occur outside of any box design definitions.
+The special keyword `:global:` is used to refer to the *boxes* global config file.
+
+For example, a user wants to add or change a design from the global config. So she creates a config file in ~/.boxes
+and places a `parent :global:` statement at the top to inherit the global config. The local / personal config file
+contains only the changes / additions.
 
 
 [ [up](index.html) \| [next](config-step.html) ]