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

MANUAL.txt: Add fuller documentation of templates.

Browse source 
Including new template syntax, partials, etc.

Closes #5779.
This commit is contained in:
John MacFarlane 2019-09-29 15:00:34 -07:00
parent 0e02d5cacc
commit ac4067fe2e
2 changed files with 274 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

333
MANUAL.txt
View file

@ -1438,9 +1438,268 @@ directory (see `--data-dir`, above). *Exceptions:*
Templates contain *variables*, which allow for the inclusion of
arbitrary information at any point in the file. They may be set at the
command line using the `-V/--variable` option. If a variable is not set,
pandoc will look for the key in the document's metadata – which can be set
pandoc will look for the key in the document's metadata, which can be set
using either [YAML metadata blocks][Extension: `yaml_metadata_block`]
or with the `-M/--metadata` option.
or with the `-M/--metadata` option. In addition, some variables
are given default values by pandoc.
If you use custom templates, you may need to revise them as pandoc
changes. We recommend tracking the changes in the default templates,
and modifying your custom templates accordingly. An easy way to do this
is to fork the [pandoc-templates] repository and merge in
changes after each pandoc release.
[pandoc-templates]: https://github.com/jgm/pandoc-templates
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.
### Interpolated variables
A slot for an interpolated variable is a variable name surrounded
by matched delimiters. Variable names must begin with a letter
and can contain letters, numbers, `_`, `-`, and `.`. The
keywords `it`, `if`, `else`, `endif`, `for`, `sep`, and `endfor` may
not be used as variable names. Examples:
```
$foo$
$foo.bar.baz$
$foo_bar.baz-bim$
$ foo $
${foo}
${foo.bar.baz}
${foo_bar.baz-bim}
${ foo }
```
Variable names with periods are used to get at structured
variable values. So, for example, `employee.salary` will return the
value of the `salary` field of the object that is the value of
the `employee` field.
- If the value of the variable is simple value, it will be
rendered verbatim. (Note that no escaping is done;
the assumption is that the calling program will escape
the strings appropriately for the output format.)
- If the value is a list, the values will be concatenated.
- 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
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:
```
$if(foo)$bar$endif$
$if(foo)$
$foo$
$endif$
$if(foo)$
part one
$else$
part two
$endif$
${if(foo)}bar${endif}
${if(foo)}
${foo}
${endif}
${if(foo)}
${ foo.bar }
${else}
no foo!
${endif}
```
The keyword `elseif` may be used to simplify complex nested
conditionals. Thus
```
$if(foo)$
XXX
$elseif(bar)$
YYY
$else$
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.
Examples:
```
$for(foo)$$foo$$sep$, $endfor$
$for(foo)$
- $foo.last$, $foo.first$
$endfor$
${ for(foo.bar) }
- ${ foo.bar.last }, ${ foo.bar.first }
${ endfor }
```
You may optionally specify a separator between consecutive
values using `sep` (enclosed in matched delimiters). The
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.
```
${ for(foo.bar) }
- ${ it.last }, ${ it.first }
${ endfor }
```
### Partials
Partials (subtemplates stored in different files) may be
included using the syntax
```
${ boilerplate() }
```
Partials will be sought in the directory containing
the main template, and will be assumed to have the
same extension as the main template if they lack
an explicit extension. (If the partials are not
found here, they will also be sought in the `templates`
subdirectory of the user data directory.)
Partials may optionally be applied to variables using
a colon:
```
${ date:fancy() }
${ 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
```
${ for(articles) }
${ it:bibentry() }
${ endfor }
```
Note that the anaphoric keyword `it` must be used when
iterating over partials. In the above examples,
the `bibentry` partial should contain `it.title`
(and so on) instead of `articles.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.
A separator between values of an array may be specified
in square brackets, immediately after the variable name
or partial:
```
${months[, ]}$
${articles:bibentry()[; ]$
```
The separator in this case is literal and (unlike with `sep`
in an explicit `for` loop) cannot contain interpolated
variables or other template directives.
### 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`).
```
${ +reflow }This long line may break if the document is rendered
with a short line length.${ -reflow }
```
### 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.
Example:
```
$for(article)$
- $+nest$$article.author$, "$article.title$," in $article.book$
($article.year$).$-nest$
$endfor$
```
Metadata variables
------------------
@ -2014,76 +2273,6 @@ on the output format, and include the following:
: title of table of contents (works only with EPUB,
opendocument, odt, docx, pptx, beamer, LaTeX)
Using variables in templates
----------------------------
Variable names are sequences of alphanumerics, `-`, and `_`,
starting with a letter. A variable name surrounded by `$` signs
will be replaced by its value. For example, the string `$title$` in
<title>$title$</title>
will be replaced by the document title.
To write a literal `$` in a template, use `$$`.
Templates may contain conditionals. The syntax is as follows:
$if(variable)$
X
$else$
Y
$endif$
This will include `X` in the template if `variable` has a truthy
value; otherwise it will include `Y`. Here a truthy value is any
of the following:
- a string that is not entirely white space,
- a non-empty array where the first value is truthy,
- any number (including zero),
- any object,
- the boolean `true` (to specify the boolean `true`
value using YAML metadata or the `--metadata` flag,
use `true`, `True`, or `TRUE`; with the `--variable`
flag, simply omit a value for the variable, e.g.
`--variable draft`).
`X` and `Y` are placeholders for any valid template text,
and may include interpolated variables or other conditionals.
The `$else$` section may be omitted.
When variables can have multiple values (for example, `author` in
a multi-author document), you can use the `$for$` keyword:
$for(author)$
<meta name="author" content="$author$" />
$endfor$
You can optionally specify a separator to be used between
consecutive items:
$for(author)$$author$$sep$, $endfor$
Note that the separator needs to be specified immediately before the `$endfor`
keyword.
A dot can be used to select a field of a variable that takes
an object as its value. So, for example:
$author.name$ ($author.affiliation$)
The value of a variable will be indented to the same level as the variable.
If you use custom templates, you may need to revise them as pandoc
changes. We recommend tracking the changes in the default templates,
and modifying your custom templates accordingly. An easy way to do this
is to fork the [pandoc-templates] repository and merge in changes after each
pandoc release.
Templates may contain comments: anything on a line after `$--`
will be treated as a comment and ignored.
[pandoc-templates]: https://github.com/jgm/pandoc-templates
Extensions

25
changelog.md
View file

@ -498,20 +498,21 @@
* Improvements in templates system (from doctemplates-0.6.1):
+ Pandoc templates now support a number of new features that
have been added in doctemplates: notably, partials and keywords
to control nesting and reflowing of text.
have been added in doctemplates: notably, `elseif`, `it`,
partials and keywords to control nesting and reflowing of
text.
+ We now used templates parameterized on doclayout Doc types.
The main impact of this change is better reflowing of content
interpolated into templates. Previously, interpolated variables
were rendered independently and intepolated as strings,
which could lead to overly long lines. Now the templates
interpolated as Doc values which may include breaking
spaces, and reflowing occurs after template interpolation
rather than before.
The main impact of this change is better reflowing of
content interpolated into templates. Previously,
interpolated variables were rendered independently and
intepolated as strings, which could lead to overly long
lines. Now the templates interpolated as Doc values which
may include breaking spaces, and reflowing occurs after
template interpolation rather than before.
+ Remove code from the LaTeX, Docbook, and JATS writers that
looked in the template for strings to determine whether it is a
book or an article, or whether csquotes is used. This was
always kludgy and unreliable.
looked in the template for strings to determine whether it
is a book or an article, or whether csquotes is used. This
was always kludgy and unreliable.
+ Change template code to use new API for doctemplates.
* Template changes: