Pandocacro API

pandocacro

Translate acronyms in the Pandoc flavored Markdown to LaTeX’s acro syntax or just do the replacement directly. Acronyms are defined in the acronyms map in the metadata and used in text with the key prepended by + or in a native_span. Each acronym must have a long and short field. On first use, the expansion is long (short). After that, the replacement is short unless overridden by the class of the span. In LaTeX mode, the markup is simply translated to the acro macro. If a key is not defined in the metadata, no transformation is done.

pandocacro.finalize(doc: Doc) → None

Clear all temporary attributes from the elements

The utilities can place attributes on the elements that are prepended by ‘pandocacro-’. Before we return the

pandocacro.prepare(doc: Doc) → None

Prepare the document

If acronyms map is in the metadata, generate the LaTeX definitions of the acronyms and count the number of uses of the acronyms in the document. These details are to be used by the writer or the main filter.

pandocacro.pandocacro

Class definitions for the package

pandocacro.pandocacro.Acronym

A map of options passed to \DeclareAcronym and metadata variables.

alias of Dict[str, Union[str, int, bool]]

pandocacro.pandocacro.Options

Options to pass to \usepackage when loading acro.

alias of Dict[str, Union[str, int, bool]]

class pandocacro.pandocacro.PandocAcro(acronyms: Dict[str, Dict[str, Union[str, int, bool]]])

A class for managing the acronyms in a document

This class stores a copy of the acronyms field from the metadata in a easily modifiable location. It loads the options into a dictionary where the keys map to the values, and it places the acronyms into a dictionary that maps the keys to the formatting options for the acronym. The acronyms can also be accessed using a mapping notation obj['key']. The intended usage is to initialize the class from the call to the document’s get_metadata():

obj = PandocAcro(doc.get_metadata("acronyms"))

acronyms

The mapping of the acronym keys to the formatting options for the acronym. The keys can also be accessed using index notation.

Type:

map of strings Acronyms

options

The mapping of the option names to the values.

Type:

Options

pandocacro.keys

The module for defining and parsing the key from an element.

class pandocacro.keys.Key(elem: Optional[Element] = None)

The key value and associated details

A key is an alphanumeric string preceded by a + either outside of or within a panflute.Span. A key may also have a * after the leading + but before the key indicating the use should not be counted in regards to the first usage. A key that is not within a panflute.Span may also have trailing punctuation such as a period, comma, or possessive markings.

value

The acronym key.

Type:

str

count

The entry should be counted (False if ‘*’ and True otherwise).

Type:

bool, optional

type

The version of the acronym to typeset.

Type:

str, in {“full”, “short”, “long”}, optional

capitalize

Capitalize the first work of the acronym.

Type:

bool, optional

plural

Use the plural form of the acronym.

Type:

bool, optional

post

The trailing punctuation.

Type:

str, optional

Parameters:

elem (panflute.Element) – The document element from which to extract the acronym key.

PATTERN: ClassVar[Pattern[str]] = re.compile('[+](?P<count>[*]?)(?P<value>\\w+)(?P<post>.*)')

The pattern for extracting a key

TYPES: ClassVar[Set] = {'full', 'long', 'short'}

The valid class options for the type of acronym expansion

static match(elem: Element) → Optional[Match[str]]

Pattern match for a key in the element

We can convert a given element to a string and match it against the known format for an acronym key. This method manages converting an element to a string, while appropriately stripping unnecessary punctuation, and passing the result to the re.match().

Parameters:

elem (panflute.Element) – The document element to inspect for an acronym key.

Returns:

The result of the re.match() call with the string version of the element.

Return type:

Match

parse(elem: Element) → None

Parse the key from a document element

This method does the low-level details of extracting the relevant information from a document panflute.Element. It inspects the key for the + followed by the optional “don’t count” flag * followed by the actual key. It then extracts the class details to set the type, capitalization, and plural details if the element has the appropriate classes attribute.

Raises:

RuntimeError: – If the classes of the element contain more than one of the valid TYPES.

pandocacro.keys.count(elem: Element, doc: Doc) → None

Count the use of acronyms in the document

This method investigates the element and increments the ‘count’ value of the acronym in the panflute.MetaMap of the document. If the acronym does not have a ‘count’ field, it is added. It is intended to be used to prepare the document before actually doing the actual substitution. It also sets the ‘used’ field to False.

Parameters:

• elem (panflute.Element) – The element under inspection

• doc (panflte.Doc) – The main document

pandocacro.keys.get(elem: Element, doc: Doc) → Optional[Key]

Extract the key from an element

Check if the given element contains a key in the metadata acronyms field preceded by +. If it is, return the key and all its details. Otherwise, return None.

Parameters:

• elem (panflute.Element) – The element under inspection

• doc (panflte.Doc) – The main document

Returns:

The populated Key if the value is in the acronyms metadata. Otherwise, None.

Return type:

Key

pandocacro.translate

Functions to translate keys to proper output

pandocacro.translate.latex(key: Key) → RawInline

Generate the LaTeX output from a key

This method inspects the given keys.Key and determine the properly formatted version of the LaTeX acronym.

Parameters:

key (keys.Key) – The keys.Key to interpret.

Returns:

The LaTeX formatted acronym.

Return type:

panflute.RawInline

pandocacro.translate.plain(key: Key, acronyms: PandocAcro) → Str

Generate the plain text acronym expansion from a key

This method inspects the given keys.Key and deduces the appropriate expansion based on the details in the given Acronyms mapping. It explicitly checks the user requested formatting (‘long’, ‘short’, ‘full’, etc.) to do the formatting, but it falls back on inspecting the number of usages based on the ‘count’ and ‘used’ fields for the acronym. Further, it increments the ‘used’ field in the Acronyms unless the key was marked “do not count.”

Parameters:

key (keys.Key) – The keys.Key to interpret.

Returns:

The plain text formatted acronym expansion.

Return type:

panflute.Str

Raises:

NotImplementedError: – When an unknown first or single style is requested.

pandocacro.translate.translate(elem: Element, doc: Doc) → Optional[Element]

Translate a marked acronym to the expanded version

This method is the filter interface to actually inspect an element and translate it to the appropriate replacement. This includes generating the appropriate LaTeX macro or fully expanding the text based on the panflute.Doc format.

Parameters:

• elem (panflute.Element) – The element to inspect and replace.

• doc (panflute.Doc) – The document under consideration.

Returns:

The replacement element with the acronym replacement.

Return type:

panflute.Element, optional

pandocacro.list

Functions to generate the list of acronyms

pandocacro.list.latex(elem: Union[Div, Header], doc: Doc) → RawBlock

Assemble the LaTeX version of the acronym list

The base LaTeX output is the \printacronyms macro, but we need to extract the possible name, and sort variables based on the content and attributes. The content is stringified and set to the name option and sort is translated as lower case. If one of the attributes cannot be interpreted, it is omitted from the option list and a warning is logged.

Parameters:

• elem (panflute.Div or panflute.Header) – The element to replace

• doc (panflute.Doc) – The document under consideration.

Returns:

The replacement for the block.

Return type:

panflute.RawBlock

pandocacro.list.plain(elem: Union[Div, Header], doc: Doc) → Optional[Div]

Assemble the plain text version of the acronym list

The base plain text output is a bulleted list of acronyms in the following format:

-   {short}: {long}

in a new panflute.Div with the identifier “acronym-list”. If the given element is a panflute.Div, the list is placed under a level 1 header with the text “Acronyms” unless the name or level attributes are set in which case, the request is honored. The list is sorted by the short version of the acronyms by default unless the sort attribute is set to “false” (case insensitive) in which case the order is unspecified. If an attribute cannot be interpreted, it is omitted and a warning is logged.

Parameters:

• elem (panflute.Div or panflute.Header) – The element to replace

• doc (panflute.Doc) – The document under consideration.

Returns:

The replacement for the block.

Return type:

panflute.Div, optional

pandocacro.list.printacronyms(elem: Element, doc: Doc) → Optional[Block]

Print the list of acronyms.

This is the high level filter to generate a list of acronyms. It checks for a panflute.Div or panflute.Header that has the identifier ‘acronyms’ and replaces it with the appropriate list of acronyms.

Parameters:

• elem (panflute.Element) – The element to inspect and replace.

• doc (panflute.Doc) – The document under consideration.

Returns:

The replacement block with the acronym list.

Return type:

panflute.Block, optional