hektor / pandoc-gls

A pandoc filter allowing easier syntax for the Latex glossaries package with Markdown documents

pandoc-gls

This filter provides a slightly cleaner syntax for the LaTeX glossaries package. This uses a syntax inspired by pandoc-ac by Eduardo Pinho.

Use the codes below in place of the \gls{label} form in your source code:

Code	Description	Translates to
(+x)	glossary entry	\gls{x}
(++x)	capitalised glossary entry	\Gls{x}
(+^x)	plural form of the glossary entry	\glspl{x}
(++^x)	capitalised plural form of the glossary entry	\Glspl{x}
(-x)	unlinked glossary entry name only	\glsentryname{x}
(-+x)	caplitalised unlinked glossary entry	\Glsentryname{x}
(-^x)	plutal unlinked glossary entry	\glsentryplural{x}
(-+^x)	caplitalised plural form of the unlinked glossary entry	\Glsentryplural{x}

The unlinked versions of the syntax are recommended for figure and table captions as this will prevent the acronyms and glossary first usages turning up in your tables of figures/tables and/or messing up your PDF bookmarks.

If you are using the hyperref package to have links from your table of contents to your sections then avoid using the anything other than (-x) in your section headings as all manor of errors await you. See the details about expandable vs non-expandable commands in section 9 of the glossaries user guide.

For possessives (e.g. "label's") and other grammar in your glossary entries the glossaries package does allow you to define custom grammars, however pandoc-gls doesn't have a syntax for these (yet). For now, you can add extra text behind your labels and this will be added to the substituted latex output. For example (+FOO)'s would become foobanator's and (+BAR)ing would become BARing.

Usage

To apply this filter to your markdown code, clone the pandoc-gls.lua to an accessible directory, then run pandoc with the --lua-filters option:

$ pandoc --from markdown --to latex -o output.pdf --lua-filter \path\to\pandoc-gls.lua input.md

In order for the glossary entries to render properly you need to include the glossaries package and a definition file (see glossary.tex in this repository for an example) in the markdown document's front matter:

header-includes:
    - \usepackage{glossaries}
    - \makenoidxglossaries
    - \include{<path to glossary definitions file>}
include-after:
    - \printnoidxglossary[sort=word]

This will include a glossary at the end of the document, however you can place it at the front by putting the print glossary command in the include-before list.

NOTE: Glossary labels cannot contain spaces but can contain "_" (underscore) and "-" (hyphen) characters. Any other punctuation characters used within labels will cause the parsing to fail.

To-Do

Lua is not my main language so this filter could probably be made more efficient. Any tips are welcome.

Currently only supports glossary entries in normal text, headings and tables. I need to add support for code blocks and other inline elements.

I need to add support for using hyperref's \texorpdfstring{TEX text}{Bookmark Text} command to the commands above so they can be used in section headings.