@@ -1633,21 +1633,24 @@ changes after each pandoc release.
1634## Template syntax
1634## Template syntax
1636−To mark variables and control structures in the template, either
1637−`$`...`$` or `${`...`}` may be used as delimiters. The styles
1638−may also be mixed in the same template, but the opening and
1639−closing delimiter must match in each case. The opening
1640−delimiter may be followed by one or more spaces or tabs, which
1641−will be ignored. The closing delimiter may be followed by one or
1642−more spaces or tabs, which will be ignored.
1644−To include a literal `$` in the document, use `$$`.
1646### Comments
1636### Comments
1648Anything between the sequence `$--` and the end of the
1638Anything between the sequence `$--` and the end of the
1649line will be treated as a comment and omitted from the output.
1639line will be treated as a comment and omitted from the output.
1643+To mark variables and control structures in the template,
1644+either `$`...`$` or `${`...`}` may be used as delimiters.
1645+The styles may also be mixed in the same template, but the
1646+opening and closing delimiter must match in each case. The
1647+opening delimiter may be followed by one or more spaces
1648+or tabs, which will be ignored. The closing delimiter may
1649+be followed by one or more spaces or tabs, which will be
1652+To include a literal `$` in the document, use `$$`.
1651### Interpolated variables
1654### Interpolated variables
1653A slot for an interpolated variable is a variable name surrounded
1656A slot for an interpolated variable is a variable name surrounded
@@ -1680,10 +1683,6 @@ the `employee` field.
1680- If the value is a map, the string `true` will be rendered.
1683- If the value is a map, the string `true` will be rendered.
1681- Every other value will be rendered as the empty string.
1684- Every other value will be rendered as the empty string.
1683−The value of a variable that occurs by itself on a line
1684−will be indented to the same level as the opening delimiter of
1687### Conditionals
1686### Conditionals
1689A conditional begins with `if(variable)` (enclosed in
1688A conditional begins with `if(variable)` (enclosed in
@@ -1691,8 +1690,7 @@ matched delimiters) and ends with `endif` (enclosed in matched
1691delimiters). It may optionally contain an `else` (enclosed in
1690delimiters). It may optionally contain an `else` (enclosed in
1692matched delimiters). The `if` section is used if
1691matched delimiters). The `if` section is used if
1693`variable` has a non-empty value, otherwise the `else`
1692`variable` has a non-empty value, otherwise the `else`
1694−section is used (if present). (Note that even the
1693+section is used (if present). Examples:
1695−string `false` counts as a true value.) Examples:
1698$if(foo)$bar$endif$
1696$if(foo)$bar$endif$
@@ -1721,7 +1719,7 @@ ${endif}
1723The keyword `elseif` may be used to simplify complex nested
1721The keyword `elseif` may be used to simplify complex nested
1724−conditionals. Thus
1722+conditionals:
1727$if(foo)$
1725$if(foo)$
@@ -1733,29 +1731,17 @@ ZZZ
1750### For loops
1734### For loops
1752A for loop begins with `for(variable)` (enclosed in
1736A for loop begins with `for(variable)` (enclosed in
1753matched delimiters) and ends with `endfor` (enclosed in matched
1737matched delimiters) and ends with `endfor` (enclosed in matched
1754−delimiters. If `variable` is an array, the material inside
1740+- If `variable` is an array, the material inside the loop will
1755−the loop will be evaluated repeatedly, with `variable` being set
1741+ be evaluated repeatedly, with `variable` being set to each
1756−to each value of the array in turn. If the value of the
1742+ value of the array in turn, and concatenated.
1757−associated variable is not an array, a single iteration will be
1743+- If the value of the associated variable is not an array or
1758−performed on its value.
1744+ a map, a single iteration will be performed on its value.
1760Examples:
1746Examples:
@@ -1779,8 +1765,8 @@ material between `sep` and the `endfor` is the separator.
1779${ for(foo) }${ foo }${ sep }, ${ endfor }
1765${ for(foo) }${ foo }${ sep }, ${ endfor }
1782−Instead of the variable name, the special anaphoric keyword `it`
1768+Instead of using `variable` inside the loop, the special
1783−may be used inside the loop.
1769+anaphoric keyword `it` may be used.
1786${ for(foo.bar) }
1772${ for(foo.bar) }
@@ -1814,8 +1800,8 @@ ${ articles:bibentry() }
1816If `articles` is an array, this will iterate over its
1802If `articles` is an array, this will iterate over its
1817−values, applying the partial `bibentry()` to each one.
1803+values, applying the partial `bibentry()` to each one. So the
1818−So the second example above is equivalent to
1804+second example above is equivalent to
1821${ for(articles) }
1807${ for(articles) }
@@ -1830,9 +1816,7 @@ the `bibentry` partial should contain `it.title`
1831Final newlines are omitted from included partials.
1817Final newlines are omitted from included partials.
1833−Partials may include other partials. If you exceed
1819+Partials may include other partials.
1834−a nesting level of 50, though, in resolving partials,
1835−the literal `(loop)` will be returned, to avoid infinite loops.
1837A separator between values of an array may be specified
1821A separator between values of an array may be specified
1838in square brackets, immediately after the variable name
1822in square brackets, immediately after the variable name
@@ -1848,37 +1832,141 @@ The separator in this case is literal and (unlike with `sep`
1848in an explicit `for` loop) cannot contain interpolated
1832in an explicit `for` loop) cannot contain interpolated
1849variables or other template directives.
1833variables or other template directives.
1837+To ensure that content is "nested," that is, subsequent lines
1838+indented, use the `^` directive:
1841+$item.number$ $^$$item.description$ ($item.price$)
1844+In this example, if `item.description` has multiple lines,
1845+they will all be indented to line up with the first line:
1848+00123 A fine bottle of 18-year old
1849+ Oban whiskey. ($148)
1852+To nest multiple lines to the same level, align them
1853+with the `^` directive in the template. For example:
1856+$item.number$ $^$$item.description$ ($item.price$)
1857+ (Available til $item.sellby$.)
1863+00123 A fine bottle of 18-year old
1864+ Oban whiskey. ($148)
1865+ (Available til March 30, 2020.)
1868+If a variable occurs by itself on a line, preceded by whitespace
1869+and not followed by further text or directives on the same line,
1870+and the variable's value contains multiple lines, it will be
1871+nested automatically.
1851### Breakable spaces
1873### Breakable spaces
1853Normally, spaces in the template itself (as opposed to values of
1875Normally, spaces in the template itself (as opposed to values of
1854the interpolated variables) are not breakable, but they can be
1876the interpolated variables) are not breakable, but they can be
1855−made breakable in part of the template by using the `+reflow`
1877+made breakable in part of the template by using the `~` keyword
1856−keyword (ended with `-reflow`).
1878+(ended with another `~`).
1859−${ +reflow }This long line may break if the document is rendered
1881+$~$This long line may break if the document is rendered
1860−with a short line length.${ -reflow }
1882+with a short line length.$~$
1863−### Nesting
1885+### Filters
1865−As noted above, the value of a variable that occurs by itself on
1887+A filter transforms the value of a variable. Filters are
1866−a line will be indented to the same level as the opening
1888+specified using a slash (`/`) between the variable name and
1867−delimiter of the variable.
1889+the filter name. They may go anywhere a variable can go.
1869−In addition, any part of a template can be marked explicitly for
1892+```
1870−indented rendering, using the `+nest` keyword (o start nesting at
1893+$for(name)$
1871−the column where it appears) and `-nest` to stop nesting.
1894+$name/uppercase$
1873−Example:
1897+$for(metadata/pairs)$
1898+- $it.key$: $it.value$
1902+Filters may be chained:
1905+$for(employees/pairs)$
1906+$it.key/alpha/uppercase$. $it.name$
1910+Some filters take parameters:
1876−$for(article)$
1913+|----------------------|------------|
1877−- $+nest$$article.author$, "$article.title$," in $article.book$
1914+$for(employee)$
1878− ($article.year$).$-nest$
1915+$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
1917+|----------------------|------------|
1920+Currently the following filters are predefined:
1922+- `pairs`: Converts a map or array to an array of maps,
1923+ each with `key` and `value` fields. If the original
1924+ value was an array, the `key` will be the array index,
1927+- `uppercase`: Converts a textual value to uppercase,
1928+ and has no effect on other values.
1930+- `lowercase`: Converts a textual value to lowercase,
1931+ and has no effect on other values.
1933+- `length`: Returns the length of the value: number
1934+ of characters for a textual value, number of elements
1935+ for a map or array.
1937+- `reverse`: Reverses a textual value or array,
1938+ and has no effect on other values.
1940+- `alpha`: Converts a textual value that can be
1941+ read as an integer into a lowercase alphabetic
1942+ character `a..z` (mod 26), and has no effect on
1943+ other values. This can be used to get lettered
1944+ enumeration from array indices. To get uppercase
1945+ letters, chain with `uppercase`.
1947+- `roman`: Converts a textual value that can be
1948+ read as an integer into a lowercase roman numerial,
1949+ and has no effect on other values. This can be used
1950+ to get lettered enumeration from array indices. To
1951+ get uppercase roman, chain with `uppercase`.
1953+- `left n "leftborder" "rightborder"`: Renders a textual value
1954+ in a block of width `n`, aligned to the left, with an optional
1955+ left and right border. Has no effect on other values. This
1956+ can be used to align material in tables. Widths are positive
1957+ integers indicating the number of characters. Borders
1958+ are strings inside double quotes; literal `"` and `\` characters
1959+ must be backslash-escaped.
1961+- `right n "leftborder" "rightborder"`: Renders a textual value
1962+ in a block of width `n`, aligned to the right, and has no
1963+ effect on other values.
1965+- `center n "leftborder" "rightborder"`: Renders a textual
1966+ value in a block of width `n`, aligned to the center, and has
1967+ no effect on other values.
1882## Variables
1970## Variables
1884### Metadata variables
1972### Metadata variables