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.
Lists of Inline and Block elements can now be filtered via `Inlines` and
`Blocks` functions, respectively. This is helpful if a filter conversion
depends on the order of elements rather than a single element.
For example, the following filter can be used to remove all spaces
before a citation:
function isSpaceBeforeCite (spc, cite)
return spc and spc.t == 'Space'
and cite and cite.t == 'Cite'
end
function Inlines (inlines)
for i = #inlines-1,1,-1 do
if isSpaceBeforeCite(inlines[i], inlines[i+1]) then
inlines:remove(i)
end
end
return inlines
end
Closes: #6038
This follows the advise on the Lua
website (https://www.lua.org/about.html#name):
> […] "Lua" is a name, the name of the Earth's moon and the name of the
> language. Like most names, it should be written in lower case with an
> initial capital, that is, "Lua".
The functions `table.insert`, `table.remove`, and `table.sort` are added
to pandoc.List elements. They can be used as methods, e.g.
local numbers = pandoc.List {2, 3, 1}
numbers:sort() -- numbers is now {1, 2, 3}
Links and anchors now follow consistent conventions, like lowercase-only
anchor names.
This breaks some links to specific sections in the document, but will
make it much easier to link documentation in the future.
Metadata defaults can be given via the command line `--metadata-file`.
Adding raw format snippets is a common use case for Lua filters, so it
seems sensible to provide an example.
Thanks to @efx for proposing this filter.
Closes: pandoc/lua-filters#70
