Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Update Template syntax in MANUAL.txt with latest doctemplates.

Browse source
This commit is contained in:
John MacFarlane 2019-10-29 22:39:25 -07:00
parent 63cfd45406
commit 080a3cdaeb
1 changed files with 147 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

206
MANUAL.txt
View file

@ -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
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.
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.
### Filters
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:
```
$for(article)$
- $+nest$$article.author$, "$article.title$," in $article.book$
($article.year$).$-nest$
$for(name)$
$name/uppercase$
$endfor$
$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(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