Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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

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.dev202002202125
File Size Uploaded Provenance Actions
pandoc-acronyms-0.3.dev202002202125.tar.gz 8.2 kB Without provenance Details for pandoc-acronyms-0.3.dev202002202125.tar.gz

Built distribution (wheel)

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

Total release size: 24.3 kB

Release files / pandoc-acronyms-0.3.dev202002202125.tar.gz

Download URL pandoc-acronyms-0.3.dev202002202125.tar.gz
Size 8.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b0bda6fc6145d5243803c687a3923975fdf92cbc62cae7b321f354eb191cb86d
BLAKE2b-256 checksum
How to use checksums
c4b76007a90726eeaabb80b689c88446be6cd321d9bf83eac118b262a3832511
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.3.dev202002202125-py3-none-any.whl

Download URL pandoc_acronyms-0.3.dev202002202125-py3-none-any.whl
Size 16.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5dd8824aa004feeb131b3c5c4a9618f8f7aef6c3d457b075a7938484990b57b3
BLAKE2b-256 checksum
How to use checksums
8ed0865c1c3ba5201bc64551a04deb0651114fcb09cd6d0dabb69237d415e6f8
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.3.dev202002202125

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