diff options
| -rw-r--r-- | MANUAL.txt | 333 | ||||
| -rw-r--r-- | changelog.md | 25 |
2 files changed, 274 insertions, 84 deletions
diff --git a/MANUAL.txt b/MANUAL.txt index 384bff7fe..418683c5d 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -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 diff --git a/changelog.md b/changelog.md index 3ce84a10e..d4314aaa3 100644 --- a/changelog.md +++ b/changelog.md @@ -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: |