New templates variables can be added by giving variable-value pairs as a
second return value of the global function `Doc`.
Example:
function Doc (body, meta, vars)
vars.date = vars.date or os.date '%B %e, %Y'
return body, vars
end
Closes: #6731
API changes:
- The function T.P.Filter.applyFilters now takes a filter
environment of type `Environment`, instead of a ReaderOptions value.
The `Environment` type is exported from `T.P.Filter` and allows to
combine ReaderOptions and WriterOptions in a single value.
- Global, exported from T.P.Lua, has a new type constructor
`PANDOC_WRITER_OPTIONS`.
Closes: #5221
The function `pandoc.read` is updated to use the same state that was
used while parsing the main input files. This ensures that log messages
are preserved and that images embedded in the input are added to the
mediabag.
Affiliations were `xlink`ed even in the articleauthoring tag set, but
`<aff>` are not allowed as children of `contrib-group` elements in that
tag set. Each affiliation must be listed directly in the contrib
element.
The function behaves like the default `type` function from Lua's
standard library, but is aware of pandoc userdata types. A typical
use-case would be to determine the type of a metadata value.
The objects now also follow the principle that element attributes are
accessible through the `.attr` field. Rows in `TableHead` and
`TableFoot` are available via the `.rows` field. Row objects have a
`.cells` field, containing the list of table cells.
Closes: #7718
The traversal order of filters can now be selected by setting the key
`traverse` of the filter to either `'topdown'` or `'typewise'`; the
default remains `'typewise'`.
Topdown traversals can be cut short by returning `false` as a second
value from the filter function. No child-element of the returned element
is processed in that case.
Retry conversion by passing a string instead of sources when the
`Reader` fails with a message that hints at an outdated function. A
deprecation notice is reported in that case.
The first argument passed to Lua `Reader` functions is no longer a plain
string but a richer data structure. The structure can easily be
converted to a string by applying `tostring`, but is also a list with
elements that contain each the *text* and *name* of each input source as
a property of the respective name.
A small example is added to the custom reader documentation, showcasing
its use in a reader that creates a syntax-highlighted code block for
each source code file passed as input.
Existing readers must be updated.
- `walk` methods are added to `Block` and `Inline` values; the methods
are similar to `pandoc.utils.walk_block` and
`pandoc.utils.walk_inline`, but apply to filter also to the element
itself, and therefore return a list of element instead of a single
element.
- Functions of name `Doc` are no longer accepted as alternatives for
`Pandoc` filter functions. This functionality was undocumented.
The new `pandoc.Inlines` function behaves identical on string input, but
allows other Inlines-like arguments as well.
The `pandoc.utils.text` function could be written as
function pandoc.utils.text (x)
assert(type(x) == 'string')
return pandoc.Inlines(x)
end
The function converts a string to `Inlines`, treating interword spaces
as `Space`s or `SoftBreak`s. If you want a `Str` with literal spaces,
use `pandoc.Str`.
Closes: #7709
The `lpeg` and `re` modules are loaded into globals of the respective
name, but they are not necessarily registered as loaded packages. This
ensures that
- the built-in library versions are preferred when setting the globals,
- a shared library is used if pandoc has been compiled without `lpeg`,
and
- the `require` mechanism can be used to load the shared library if
available, falling back to the internal version if possible and
necessary.
Reader options can now be passed as an optional third argument to
`pandoc.read`. The object can either be a table or a ReaderOptions value
like `PANDOC_READER_OPTIONS`. Creating new ReaderOptions objects is
possible through the new constructor `pandoc.ReaderOptions`.
Closes: #7656
- For LineEnding use lowercase constructors, e.g. `crlf`, `native`.
This was the original intent, but there was a bug in the
implementation.
- For HTMLSlideVariant use lowercase constructors.
- For ReaderOptions use e.g. `default-image-extension`
instead of `readerDefaultImageExtension` for field names.
- For Extension, use e.g. `tex_math_dollars` instead of
`Ext_tex_math_dollars` as constructor.
- For Extensions, use an array of Extensions, instead of
an object wrapping the tag `Extensions` and an integer.
(The representation is not supposed to be part of the
public API.)
- For Opt, use field names like `tab-stop` instead of `optTabStop`.
This is imported from the website; in the future the website
version will be drawn from here.
Added a FAQ on the use of `\AtEndPreamble` for cases when
the contents of `header-includes` need to refer to definitions
that come later in the preamble. See #7422.
Since it seem to be a common source of confusion, this commit adds a note in
org-mode documentation referring users to consult org-mode's export
documentation when they find themselves in a pinch.
The partitioning the components of a name into surname, given names,
etc. is not always possible or not available. Using `author.name` allows
to give the full name as a fallback to be used when `author.surname` is
not available.
A new type `SimpleTable` is made available to Lua filters. It is
similar to the `Table` type in pandoc versions before 2.10;
conversion functions from and to the new Table type are provided.
Old filters using tables now require minimal changes and can use,
e.g.,
if PANDOC_VERSION > {2,10,1} then
pandoc.Table = pandoc.SimpleTable
end
and
function Table (tbl)
tbl = pandoc.utils.to_simple_table(tbl)
…
return pandoc.utils.from_simple_table(tbl)
end
to work with the current pandoc version.
This changes the Lua API. It is highly unlikely for this change to
affect existing filters, since the documentation for the new Table
constructor (and type) was incomplete and partly wrong before.
The Lua API is now more consistent, as all constructors for elements
with attributes now take attributes as the last parameter.
