@@ -1633,21 +1633,24 @@ changes after each pandoc release.
16331633
16341634## Template syntax
16351635
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.
1643−
1644−To include a literal `$` in the document, use `$$`.
1645−
16461636### Comments
16471637
16481638Anything between the sequence `$--` and the end of the
16491639line will be treated as a comment and omitted from the output.
16501640
1641+### Delimiters
1642+
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
1650+ignored.
1651+
1652+To include a literal `$` in the document, use `$$`.
1653+
16511654### Interpolated variables
16521655
16531656A slot for an interpolated variable is a variable name surrounded
@@ -1680,10 +1683,6 @@ the `employee` field.
16801683- If the value is a map, the string `true` will be rendered.
16811684- Every other value will be rendered as the empty string.
16821685
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
1685−the variable.
1686−
16871686### Conditionals
16881687
16891688A conditional begins with `if(variable)` (enclosed in
@@ -1691,8 +1690,7 @@ matched delimiters) and ends with `endif` (enclosed in matched
16911690delimiters). It may optionally contain an `else` (enclosed in
16921691matched delimiters). The `if` section is used if
16931692`variable` has a non-empty value, otherwise the `else`
1694−section is used (if present). (Note that even the
1695−string `false` counts as a true value.) Examples:
1693+section is used (if present). Examples:
16961694
16971695```
16981696$if(foo)$bar$endif$
@@ -1721,7 +1719,7 @@ ${endif}
17211719```
17221720
17231721The keyword `elseif` may be used to simplify complex nested
1724−conditionals. Thus
1722+conditionals:
17251723
17261724```
17271725$if(foo)$
@@ -1733,29 +1731,17 @@ ZZZ
17331731$endif$
17341732```
17351733
1736−is equivalent to
1737−
1738−```
1739−$if(foo)$
1740−XXX
1741−$else$
1742−$if(bar)$
1743−YYY
1744−$else$
1745−ZZZ
1746−$endif$
1747−$endif$
1748−```
1749−
17501734### For loops
17511735
17521736A for loop begins with `for(variable)` (enclosed in
17531737matched delimiters) and ends with `endfor` (enclosed in matched
1754−delimiters. If `variable` is an array, the material inside
1755−the loop will be evaluated repeatedly, with `variable` being set
1756−to each value of the array in turn. If the value of the
1757−associated variable is not an array, a single iteration will be
1758−performed on its value.
1738+delimiters.
1739+
1740+- If `variable` is an array, the material inside the loop will
1741+ be evaluated repeatedly, with `variable` being set to each
1742+ value of the array in turn, and concatenated.
1743+- If the value of the associated variable is not an array or
1744+ a map, a single iteration will be performed on its value.
17591745
17601746Examples:
17611747
@@ -1779,8 +1765,8 @@ material between `sep` and the `endfor` is the separator.
17791765${ for(foo) }${ foo }${ sep }, ${ endfor }
17801766```
17811767
1782−Instead of the variable name, the special anaphoric keyword `it`
1783−may be used inside the loop.
1768+Instead of using `variable` inside the loop, the special
1769+anaphoric keyword `it` may be used.
17841770
17851771```
17861772${ for(foo.bar) }
@@ -1814,8 +1800,8 @@ ${ articles:bibentry() }
18141800```
18151801
18161802If `articles` is an array, this will iterate over its
1817−values, applying the partial `bibentry()` to each one.
1818−So the second example above is equivalent to
1803+values, applying the partial `bibentry()` to each one. So the
1804+second example above is equivalent to
18191805
18201806```
18211807${ for(articles) }
@@ -1830,9 +1816,7 @@ the `bibentry` partial should contain `it.title`
18301816
18311817Final newlines are omitted from included partials.
18321818
1833−Partials may include other partials. If you exceed
1834−a nesting level of 50, though, in resolving partials,
1835−the literal `(loop)` will be returned, to avoid infinite loops.
1819+Partials may include other partials.
18361820
18371821A separator between values of an array may be specified
18381822in square brackets, immediately after the variable name
@@ -1848,37 +1832,141 @@ The separator in this case is literal and (unlike with `sep`
18481832in an explicit `for` loop) cannot contain interpolated
18491833variables or other template directives.
18501834
1835+### Nesting
1836+
1837+To ensure that content is "nested," that is, subsequent lines
1838+indented, use the `^` directive:
1839+
1840+```
1841+$item.number$ $^$$item.description$ ($item.price$)
1842+```
1843+
1844+In this example, if `item.description` has multiple lines,
1845+they will all be indented to line up with the first line:
1846+
1847+```
1848+00123 A fine bottle of 18-year old
1849+ Oban whiskey. ($148)
1850+```
1851+
1852+To nest multiple lines to the same level, align them
1853+with the `^` directive in the template. For example:
1854+
1855+```
1856+$item.number$ $^$$item.description$ ($item.price$)
1857+ (Available til $item.sellby$.)
1858+```
1859+
1860+will produce
1861+
1862+```
1863+00123 A fine bottle of 18-year old
1864+ Oban whiskey. ($148)
1865+ (Available til March 30, 2020.)
1866+```
1867+
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.
1872+
18511873### Breakable spaces
18521874
18531875Normally, spaces in the template itself (as opposed to values of
18541876the interpolated variables) are not breakable, but they can be
1855−made breakable in part of the template by using the `+reflow`
1856−keyword (ended with `-reflow`).
1877+made breakable in part of the template by using the `~` keyword
1878+(ended with another `~`).
18571879
18581880```
1859−${ +reflow }This long line may break if the document is rendered
1860−with a short line length.${ -reflow }
1881+$~$This long line may break if the document is rendered
1882+with a short line length.$~$
18611883```
18621884
1863−### Nesting
1885+### Filters
18641886
1865−As noted above, the value of a variable that occurs by itself on
1866−a line will be indented to the same level as the opening
1867−delimiter of the variable.
1887+A filter transforms the value of a variable. Filters are
1888+specified using a slash (`/`) between the variable name and
1889+the filter name. They may go anywhere a variable can go.
1890+Example:
18681891
1869−In addition, any part of a template can be marked explicitly for
1870−indented rendering, using the `+nest` keyword (o start nesting at
1871−the column where it appears) and `-nest` to stop nesting.
1892+```
1893+$for(name)$
1894+$name/uppercase$
1895+$endfor$
18721896
1873−Example:
1897+$for(metadata/pairs)$
1898+- $it.key$: $it.value$
1899+$endfor$
1900+```
1901+
1902+Filters may be chained:
1903+
1904+```
1905+$for(employees/pairs)$
1906+$it.key/alpha/uppercase$. $it.name$
1907+$endfor$
1908+```
1909+
1910+Some filters take parameters:
18741911
18751912```
1876−$for(article)$
1877−- $+nest$$article.author$, "$article.title$," in $article.book$
1878− ($article.year$).$-nest$
1913+|----------------------|------------|
1914+$for(employee)$
1915+$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
18791916$endfor$
1917+|----------------------|------------|
18801918```
18811919
1920+Currently the following filters are predefined:
1921+
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,
1925+ starting with 1.
1926+
1927+- `uppercase`: Converts a textual value to uppercase,
1928+ and has no effect on other values.
1929+
1930+- `lowercase`: Converts a textual value to lowercase,
1931+ and has no effect on other values.
1932+
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.
1936+
1937+- `reverse`: Reverses a textual value or array,
1938+ and has no effect on other values.
1939+
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`.
1946+
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`.
1952+
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.
1960+
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.
1964+
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.
1968+
1969+
18821970## Variables
18831971
18841972### Metadata variables