Abbreviations / Acronyms¶

Abbreviations are a lightweight mechanism to define acronyms and their expansions. The spelling is PHP-Markdown-Extra's abbr, which every MkDocs site renders; in LaTeX they go through the glossaries package, which provides a rich set of commands for formatting and indexing.

The HTML specification is maintained by the W3C.

*[HTML]: HyperText Markup Language
*[W3C]: World Wide Web Consortium

TeXSmith renders that snippet as:

$ texsmith abbr.md
The \tsacr{HTML} specification is maintained by the \tsacr{W3C}.

\tsacr{KEY} renders the acronym's short form; ts-typesetting defines it over the glossaries package's \acrshort, and a template may redefine it. Typst gets the matching #ts-acr("KEY"), and the web writer emits <abbr>.

Which displays as:

Of course, this also works on this HTML site. Try hovering over the abbreviations.

Acronyms are collected automatically during the LaTeX pass:

$ uv run texsmith test.md -tarticle 1>/dev/null
$ rg newacronym build/test.tex
92:\newacronym{HTML}{HTML}{HyperText Markup Language}
93:\newacronym{W3C}{W3C}{World Wide Web Consortium}

One entry per acronym the text actually writes, keyed by the acronym with everything LaTeX cannot put in a control-sequence name removed — K&R is \newacronym{KR}{K\&R}{…}, and the short form it prints is still K&R. An acronym defined and never written is not declared: glossaries prints what is used.

Front-matter glossary¶

For longer documents you can declare acronyms under press.declare.glossary in the YAML front matter. Each entry carries an explicit description and may be attached to a group; TeXSmith renders one localised \printglossary table per group (in declaration order) followed by a default table for ungrouped entries. The *[KEY]: … body syntax keeps working and merges with the front-matter entries.

---
press:
  declare:
    glossary:
      style: long           # default; any glossaries-package style works
      groups:
        technique: Acronymes techniques
        institutionnel: Acronymes institutionnels
      entries:
        API:
          group: technique
          description: Application Programming Interface
        ONU:
          group: institutionnel
          description: Organisation des Nations Unies
        DOI: Digital Object Identifier   # short form: ungrouped, description only
---

A top-level glossary: key is the deprecated spelling; tmark lint --fix moves it under press.declare.

The section is validated with pydantic, so unknown keys, missing descriptions, or references to undeclared groups raise a clear error at conversion time. The default acronym-table title follows the document language (it expands to \acronymname from the glossaries package, which is localised by babel).

Automatic substitution and limitations¶

Unlike LaTeX, TeXSmith does not require \gls{…} / \Gls{…} calls in the source: the converter scans the body and replaces every strict, case-sensitive match of an acronym key with \tsacr{KEY}. As a consequence, casing helpers such as \Gls, \GLS, \acrlong, etc. are not synthesised — the substitution is the same regardless of where the acronym appears in the text. If you need those forms, drop down to a raw passthrough: {raw latex}(\Gls{KEY}).