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.3.202002050136

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.3.202002050136
File Size Uploaded Provenance Actions
pandoc-acronyms-0.3.202002050136.tar.gz 7.8 kB Without provenance Details for pandoc-acronyms-0.3.202002050136.tar.gz

Built distribution (wheel)

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

Total release size: 23.4 kB

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

Download URL pandoc-acronyms-0.3.202002050136.tar.gz
Size 7.8 kB
Tags Source
SHA-256 checksum
How to use checksums
0b11bffc4d9f2ba3f1527e5fb7b51c13d027b0e27c8a8723b1598dcd8c8a9dc0
BLAKE2b-256 checksum
How to use checksums
11c0e6457e5366c4677a6d483fc0c39feb703d3c31763182cf829336257e55a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.7.5

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

Download URL pandoc_acronyms-0.3.202002050136-py3-none-any.whl
Size 15.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2e18a60c1c12646a554ee2d5e23aa97ca31d4605d464ba76ed3fbedbbae0ce5a
BLAKE2b-256 checksum
How to use checksums
69e3fb0beed28352cf40e91a53ccec9276e1f09d37f4c636a1efc30e9d9787eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.7.5

Security for pandoc-acronyms 0.3.202002050136

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