Update Template syntax in MANUAL.txt with latest doctemplates.

1 files changed, 146 insertions, 58 deletions

diff --git a/MANUAL.txt b/MANUAL.txt
index 1172929a8..87703bf31 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1633,21 +1633,24 @@ changes after each pandoc release.
 
 ## Template syntax
 
-To mark variables and control structures in the template, either
-`$`...`$` or `${`...`}` may be used as delimiters.  The styles
-may also be mixed in the same template, but the opening and
-closing delimiter must match in each case.  The opening
-delimiter may be followed by one or more spaces or tabs, which
-will be ignored. The closing delimiter may be followed by one or
-more spaces or tabs, which will be ignored.
-
-To include a literal `$` in the document, use `$$`.
-
 ### Comments
 
 Anything between the sequence `$--` and the end of the
 line will be treated as a comment and omitted from the output.
 
+### Delimiters
+
+To mark variables and control structures in the template,
+either `$`...`$` or `${`...`}` may be used as delimiters.
+The styles may also be mixed in the same template, but the
+opening and closing delimiter must match in each case.  The
+opening delimiter may be followed by one or more spaces
+or tabs, which will be ignored. The closing delimiter may
+be followed by one or more spaces or tabs, which will be
+ignored.
+
+To include a literal `$` in the document, use `$$`.
+
 ### Interpolated variables
 
 A slot for an interpolated variable is a variable name surrounded
@@ -1680,10 +1683,6 @@ the `employee` field.
 - If the value is a map, the string `true` will be rendered.
 - Every other value will be rendered as the empty string.
 
-The value of a variable that occurs by itself on a line
-will be indented to the same level as the opening delimiter of
-the variable.
-
 ### Conditionals
 
 A conditional begins with `if(variable)` (enclosed in
@@ -1691,8 +1690,7 @@ matched delimiters) and ends with `endif` (enclosed in matched
 delimiters).  It may optionally contain an `else` (enclosed in
 matched delimiters).  The `if` section is used if
 `variable` has a non-empty value, otherwise the `else`
-section is used (if present).  (Note that even the
-string `false` counts as a true value.) Examples:
+section is used (if present).  Examples:
 
 ```
 $if(foo)$bar$endif$
@@ -1721,7 +1719,7 @@ ${endif}
 ```
 
 The keyword `elseif` may be used to simplify complex nested
-conditionals.  Thus
+conditionals:
 
 ```
 $if(foo)$
@@ -1733,29 +1731,17 @@ ZZZ
 $endif$
 ```
 
-is equivalent to
-
-```
-$if(foo)$
-XXX
-$else$
-$if(bar)$
-YYY
-$else$
-ZZZ
-$endif$
-$endif$
-```
-
 ### For loops
 
 A for loop begins with `for(variable)` (enclosed in
 matched delimiters) and ends with `endfor` (enclosed in matched
-delimiters.  If `variable` is an array, the material inside
-the loop will be evaluated repeatedly, with `variable` being set
-to each value of the array in turn.  If the value of the
-associated variable is not an array, a single iteration will be
-performed on its value.
+delimiters.
+
+- If `variable` is an array, the material inside the loop will
+  be evaluated repeatedly, with `variable` being set to each
+  value of the array in turn, and concatenated.
+- If the value of the associated variable is not an array or
+  a map, a single iteration will be performed on its value.
 
 Examples:
 
@@ -1779,8 +1765,8 @@ material between `sep` and the `endfor` is the separator.
 ${ for(foo) }${ foo }${ sep }, ${ endfor }
 ```
 
-Instead of the variable name, the special anaphoric keyword `it`
-may be used inside the loop.
+Instead of using `variable` inside the loop, the special
+anaphoric keyword `it` may be used.
 
 ```
 ${ for(foo.bar) }
@@ -1814,8 +1800,8 @@ ${ articles:bibentry() }
 ```
 
 If `articles` is an array, this will iterate over its
-values, applying the partial `bibentry()` to each one.
-So the second example above is equivalent to
+values, applying the partial `bibentry()` to each one.  So the
+second example above is equivalent to
 
 ```
 ${ for(articles) }
@@ -1830,9 +1816,7 @@ the `bibentry` partial should contain `it.title`
 
 Final newlines are omitted from included partials.
 
-Partials may include other partials.  If you exceed
-a nesting level of 50, though, in resolving partials,
-the literal `(loop)` will be returned, to avoid infinite loops.
+Partials may include other partials.
 
 A separator between values of an array may be specified
 in square brackets, immediately after the variable name
@@ -1848,37 +1832,141 @@ The separator in this case is literal and (unlike with `sep`
 in an explicit `for` loop) cannot contain interpolated
 variables or other template directives.
 
+### Nesting
+
+To ensure that content is "nested," that is, subsequent lines
+indented, use the `^` directive:
+
+```
+$item.number$  $^$$item.description$ ($item.price$)
+```
+
+In this example, if `item.description` has multiple lines,
+they will all be indented to line up with the first line:
+
+```
+00123  A fine bottle of 18-year old
+       Oban whiskey. ($148)
+```
+
+To nest multiple lines to the same level, align them
+with the `^` directive in the template. For example:
+
+```
+$item.number$  $^$$item.description$ ($item.price$)
+               (Available til $item.sellby$.)
+```
+
+will produce
+
+```
+00123  A fine bottle of 18-year old
+       Oban whiskey. ($148)
+       (Available til March 30, 2020.)
+```
+
+If a variable occurs by itself on a line, preceded by whitespace
+and not followed by further text or directives on the same line,
+and the variable's value contains multiple lines, it will be
+nested automatically.
+
 ### Breakable spaces
 
 Normally, spaces in the template itself (as opposed to values of
 the interpolated variables) are not breakable, but they can be
-made breakable in part of the template by using the `+reflow`
-keyword (ended with `-reflow`).
+made breakable in part of the template by using the `~` keyword
+(ended with another `~`).
 
 ```
-${ +reflow }This long line may break if the document is rendered
-with a short line length.${ -reflow }
+$~$This long line may break if the document is rendered
+with a short line length.$~$
 ```
 
-### Nesting
+### Filters
 
-As noted above, the value of a variable that occurs by itself on
-a line will be indented to the same level as the opening
-delimiter of the variable.
+A filter transforms the value of a variable.  Filters are
+specified using a slash (`/`) between the variable name and
+the filter name.  They may go anywhere a variable can go.
+Example:
 
-In addition, any part of a template can be marked explicitly for
-indented rendering, using the `+nest` keyword (o start nesting at
-the column where it appears) and `-nest` to stop nesting.
+```
+$for(name)$
+$name/uppercase$
+$endfor$
 
-Example:
+$for(metadata/pairs)$
+- $it.key$: $it.value$
+$endfor$
+```
+
+Filters may be chained:
+
+```
+$for(employees/pairs)$
+$it.key/alpha/uppercase$. $it.name$
+$endfor$
+```
+
+Some filters take parameters:
 
 ```
-$for(article)$
-- $+nest$$article.author$, "$article.title$," in $article.book$
-  ($article.year$).$-nest$
+|----------------------|------------|
+$for(employee)$
+$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
 $endfor$
+|----------------------|------------|
 ```
 
+Currently the following filters are predefined:
+
+- `pairs`:  Converts a map or array to an array of maps,
+  each with `key` and `value` fields.  If the original
+  value was an array, the `key` will be the array index,
+  starting with 1.
+
+- `uppercase`:  Converts a textual value to uppercase,
+  and has no effect on other values.
+
+- `lowercase`:  Converts a textual value to lowercase,
+  and has no effect on other values.
+
+- `length`:  Returns the length of the value:  number
+  of characters for a textual value, number of elements
+  for a map or array.
+
+- `reverse`:  Reverses a textual value or array,
+  and has no effect on other values.
+
+- `alpha`:  Converts a textual value that can be
+  read as an integer into a lowercase alphabetic
+  character `a..z` (mod 26), and has no effect on
+  other values.  This can be used to get lettered
+  enumeration from array indices.  To get uppercase
+  letters, chain with `uppercase`.
+
+- `roman`:  Converts a textual value that can be
+  read as an integer into a lowercase roman numerial,
+  and has no effect on other values.  This can be used
+  to get lettered enumeration from array indices.  To
+  get uppercase roman, chain with `uppercase`.
+
+- `left n "leftborder" "rightborder"`:  Renders a textual value
+  in a block of width `n`, aligned to the left, with an optional
+  left and right border.  Has no effect on other values. This
+  can be used to align material in tables.  Widths are positive
+  integers indicating the number of characters.  Borders
+  are strings inside double quotes; literal `"` and `\` characters
+  must be backslash-escaped.
+
+- `right n "leftborder" "rightborder"`:  Renders a textual value
+  in a block of width `n`, aligned to the right, and has no
+  effect on other values.
+
+- `center n "leftborder" "rightborder"`:  Renders a textual
+  value in a block of width `n`, aligned to the center, and has
+  no effect on other values.
+
+
 ## Variables
 
 ### Metadata variables