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.4.dev202002202110
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pandoc-acronyms-0.4.dev202002202110.tar.gz | 8.2 kB | Without provenance | Details for pandoc-acronyms-0.4.dev202002202110.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pandoc_acronyms-0.4.dev202002202110-py3-none-any.whl | Python 3 | none | any | Details for pandoc_acronyms-0.4.dev202002202110-py3-none-any.whl |
Total release size: 24.3 kB
Release files / pandoc-acronyms-0.4.dev202002202110.tar.gz
| Download URL | pandoc-acronyms-0.4.dev202002202110.tar.gz |
|---|---|
| Size | 8.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e017fae322b73f4f4be292bfda127d2288bff32e22a683de833375af0e69184
|
|
BLAKE2b-256 checksum How to use checksums |
5db557fdea583ccdc6b5dd0d7995d9d1b11e3ade7d56504504504ac9f9c9dfed
|
| 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.dev202002202110-py3-none-any.whl
| Download URL | pandoc_acronyms-0.4.dev202002202110-py3-none-any.whl |
|---|---|
| Size | 16.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c1f9fdeccd493f131e5787193f13511296f8b5e21aaf309ee99b76d086ea03e7
|
|
BLAKE2b-256 checksum How to use checksums |
d260b1ee99afe3ec50b16f40a8ee4cf58dd1d2983753d08aca08d726ea441fcc
|
| 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.dev202002202110
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.