Skip to content

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

Notifications You must be signed in to change notification settings

tomncooper/pandoc-gls

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

18 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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) capitalised unlinked glossary entry \Glsentryname{x}
(-^x) plural unlinked glossary entry \glsentryplural{x}
(-+^x) capitalised 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.

About

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

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published