Pandoc-latex-extensions is a pandoc filter. It is written in python, and so uses the pandocfilters module. Pandocxnos provides additional support.
The pandoclatex/core.py
module provides common infrastructure for each extension.
Extensions are implemented as plugins. Installing a new plugin is as easy as dropping it into pandoclatex/plugins/
.
Plugins may define action(key, value, fmt, meta)
and processor(meta, blocks)
functions. These are automatically detected and called by pandoclatex/core.py
.
The action(...)
functions are applied to each element in a pandoc document's abstract syntax tree. As per the pandocfilters documentation,
key
is the type of the pandoc object (e.g. 'Str', 'Para');value
is the contents of the object (e.g. a string for 'Str', a list of inline elements for 'Para')format
is the target output format (as supplied by the format argument of walk)meta
is the document's metadata
Processors process document meta
data and content blocks
. These are used mostly for injecting LaTeX into the document meta
data. Block processing can also be performed, although action(...)
is generally preferred.
The best way to write a new plugin is to adapt an existing plugin that does something close to what is desired.
Installing from source may require upgrading setuptools
by executing
pip install --upgrade setuptools
as root (or under sudo).
There are a few different options for installing from source:
-
To install from the github
master
branch use:pip install git+https://github.com/tomduck/pandoc-latex-extensions.git --user
(to upgrade append the
--upgrade
flag). -
To install from the
nextrelease
branch on github, usepip install git+https://github.com/tomduck/pandoc-latex-extensions.git@nextrelease --user
(to upgrade use the --upgrade flag).
-
To install from a local source distribution,
cd
into its root and usepip install -e . --user
Note that any changes made to the source will be automatically reflected when the filter is run (which is useful for development).
These are notes for release managers.
Merge the nextrelease
branch into master
using
git checkout master
git merge nextrelease
git push
Starting from the root of the master
branch, update demos in the demos
branch using
cd demos
make -B
git checkout demos
cp -rf out/* ..
git commit --amend -am "Updated demos."
git push --force
This procedure ensures that there will only be a single revision of each file (see https://stackoverflow.com/a/22827188).
See https://www.python.org/dev/peps/pep-0440/ for numbering conventions, including for pre-releases.
Check that you are in the master
branch.
Tagging (update the version number):
git tag -a 0.2.2 -m "New release."
git push origin 0.2.2
Create source and binary distributions using
python3 setup.py sdist bdist_wheel
(see https://packaging.python.org/tutorials/packaging-projects/).
Upload to pypi (update the version number) using
twine upload dist/pandoc-latex-extensions-0.2.2.tar.gz \
dist/pandoc_latex_extensions-0.2.2-py3-none-any.whl