Skip to main content

pandoc-acronyms - A Pandoc filter for managing acronyms

Acronyms? WTF?

There is a convention in more precise writing to provide the full text of an acronym at first use. This can get difficult for example if the text of documents is split over multiple files, which makes it hard for the authors to know where the acronym will be used first. Such a task is best left to the computer. This is what the pandoc-acronyms filter is for. Authors list acronyms in a data file and then reference them in the text.

HOWTO

Write a data file that contains your acronyms:

{
	"aba": {
		"shortform": "ABA",
		"longform": "a better acronym"
	},
	"bba": {
		"shortform": "BBA",
		"longform": "beer brewing attitude"
	}
}

Then in the text, use the acronym in encoded form like [!bba]. The filter will recognize it. On first use it replaces the marker with beer brewing attitude (BBA). Any later use will be replaced by BBA. The filter will print a notice if an acronym is found in the text that is not defined in the data file.

Using the filter

The filter mechanism is a built-in feature of pandoc. The filter is added to how pandoc is invoked:

> pandoc --filter pandoc-acronyms document.md

Unfortunately, pandoc does not allow to pass parameters to filters. The acronym filter needs to load the acronyms from the data file. To work around this, the parameters to the filter can be passed in environment variables:

> pandoc-acronyms --help
Usage: pandoc-acronyms [OPTIONS] [FORMAT]...

The pandoc-acronyms filter.

Options:
	-a, --acronyms TEXT           A file with acronym definitions in JSON format.
	-v, --verbose / --no-verbose  Enable verbose output.
	-v, --debug / --no-debug      Enable debug output.
	--help                        Show this message and exit.

The environment variable PANDOC_ACRONYMS_ACRONYMS can be used to replace the --acronyms option. Similarly, the variable PANDOC_ACRONYMS_VERBOSE enables diagnostic output.

Installation

The pandoc acronym filter is installed using Python setuptools:

> python setup.py install
...

After that, it is available as a stand-alone program in the installation location used by Python.

Testing and debugging

The pandoc-acronyms code uses the standard Python unittest framework. Most tests are data-driven in that they use regular Markdown files and JSON acronym dictionaries as input and test how the code handles them. To test the filter code as regular Python unit tests, test Markdown input is first converted into the Pandoc "native JSON" format in memory and then fed to the filter code by the tests. This means the unit tests run stand-alone (without the need for Pandon to invoke them as a filter), making the test code easily debugable.

How to contribute

The Git repository for the pandoc acronym filter is hosted on Gitlab. It uses the Gitlab CI to ensure quality, also for development branches and incoming merge requests. To contribute, please submit a merge request. Your merge request should maintain or increase the test coverage.

Metadata

Release files for pandoc-acronyms 0.4.202002202125

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pandoc-acronyms 0.4.202002202125
File Size Uploaded Provenance Actions
pandoc-acronyms-0.4.202002202125.tar.gz 8.2 kB Without provenance Details for pandoc-acronyms-0.4.202002202125.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pandoc-acronyms 0.4.202002202125
File Interpreter ABI Platform Actions
pandoc_acronyms-0.4.202002202125-py3-none-any.whl Python 3 none any Details for pandoc_acronyms-0.4.202002202125-py3-none-any.whl

Total release size: 24.2 kB

Release files / pandoc-acronyms-0.4.202002202125.tar.gz

Download URL pandoc-acronyms-0.4.202002202125.tar.gz
Size 8.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e13e4b4c60a91ca3ceb12d2da4b04476ae74969a0d8756b17c61e7a449c9ac92
BLAKE2b-256 checksum
How to use checksums
03e6961e67481cf36d59be90a58b854074839b515c74921506def1833994e6c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.7.5

Release files / pandoc_acronyms-0.4.202002202125-py3-none-any.whl

Download URL pandoc_acronyms-0.4.202002202125-py3-none-any.whl
Size 16.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d85477e49d3df14c9ae1e7b937f960cf5e862d4e2fc42f46ddf71564a2ca3659
BLAKE2b-256 checksum
How to use checksums
2fb337820fd3b6b5fd682ddc677e3b52c627f436a3cc8303665e697f0fc3cc1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.7.5

Security for pandoc-acronyms 0.4.202002202125

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page