Abbreviation processing order alternative · Issue #1465 · Python-Markdown/markdown (original) (raw)

Currently the abbr extension implements the last definition of an abbreviation.
In MkDocs with the pymdownx.snippet extension, a glossary can be auto-appended to Markdown pages.

The problem is that this prevents pages from overriding abbreviations from the glossary. To circumvent this I've been manually adding the glossary snippet to the top of all pages. But this requires some page specific abbreviations to be declared before the snippet and some after. As the lists continue to grow this can quickly cause some abbreviations to be incorrect.

Example of the currently required order:

In glossary.md:

*[process]: process definition one *[ABC]: Abbreviation definition one *[XYZ]: Abbreviation definition two (newly added)

In page.md:

*[specialized process]: process definition specialization --8<-- "glossary.md" *[XYZ-A]: Unrealized Abbreviation due to change in glossary.md *[ABC]: Abbreviation definition one redefinition

• 'specialized process' must be defined before the snippet so the entire phrase is processed before 'process' is implemented
• 'ABC' must be defined after the snippet otherwise it will be overridden by the glossary definition
• 'XYZ-A' is no longer implemented since the snippet now defines and implements 'XYZ' first

Proposals:

• Option 1: An option to have the abbr extension only keep/process the first instance of an abbreviation instead of the last.
• Option 2: An option to sort the abbreviation list to process 'superset' abbreviations first to transparently illuminate the issues with terms like the 'specialized process' and 'XYZ-A' in the example.

Both options would allow effective use of auto-append and illuminate the issue of needing to analyze how abbreviations are processed every time one is written and reassessing/adjusting the ordering in pages when a new term is added to the glossary.

The second option would require more processing time, but prevent issues (from Option1) with a page declaring an abbreviation that breaks an abbreviation in an auto-appended glossary.