sphinx-doc
LaTeXTranslator fails to build documents using the "acronym" standard role.
Describe the bug
The documentation of the Moin 2 project at https://app.readthedocs.org/projects/moin-20/ fails to build because of an
NotImplementedError: <class 'sphinx.writers.latex.LaTeXTranslator'> departing unknown node type: acronym
The <acronym> element is defined in the docutils.dtd and documented in https://docutils.sourceforge.io/docs/ref/doctree.html#acronym and implemented in the Python class docutils.nodes.acronym.
It is supported by all Docutils writers and Sphinx's HTML writer.
How to Reproduce
Try to export a document using the "acronym" standard role to LaTeX.
For example, index.rst containing the line
This document is written in reStructuredText (:ac:`rST`).
make latex
Environment Information
Platform: linux; (Linux-6.12.48+deb13-amd64-x86_64-with-glibc2.41)
Python version: 3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0])
Python implementation: CPython
Sphinx version: 8.2.3
Docutils version: 0.22.4b1.dev
Jinja2 version: 3.1.6
Pygments version: 2.18.0
Sphinx extensions
None
Additional context
The issue occured with a recent Documentation update at readthedocs (https://app.readthedocs.org/projects/moin-20/) The environment described above was used to reproduce.
The simplest solution would be to define stubs:
def visit_acronym(self, node):
pass
def depart_acronym(self, node):
pass
This would prevent aborting the LaTeX generation and simply write the <acronym> element's content.
The Docutils LaTeX writer uses
def visit_acronym(self, node) -> None:
node['classes'].insert(0, 'acronym')
self.visit_inline(node)
def depart_acronym(self, node) -> None:
self.depart_inline(node)
I.e. it is handled similar to a custom role with class "acronym" to allow authors to style acronyms.
I Sphinx, acronyms also come with a "tooltip".
The LaTeX package "pdfcomment" provides a \pdftooltip macro that creates pop-ups in PDF output. Like the HTML "title" attribute, it can be used on paragraphs, tables, footnote references, and more.
However, the "tooltip" is not available in printed media and hence has a limited raison d'être with LaTeX output.
I will have a look.
About acronyms, issues #4298 and #4861 are related (perhaps not to this issue per se though). About acronyms, I am a bit wary of any LaTeX world solution. See this recent LaTeX discussion and especially its comments to observe a typical example of what can happen with the upstream LaTeX of our times which is dynamically maintained and thus causes regularly bug reports from users of external to LaTeX team packages. Add to this that many Sphinx users have LaTeX installations at least 5 years old and anything added from LaTeX world as a Sphinx dependency can become a maintenance burden, and potentially also impact negatively build times.
As per pdfcomment I am not familiar with it but I notice that it has received no updates since 2018 and appears to target particularly Adobe Reader. I thus concur with your
has a limited raison d'être with LaTeX output.
Considering the fact that the HTML5 standard conflates <abbr> and <acronym> (https://html.spec.whatwg.org/multipage/obsolete.html#acronym), the Sphinx LaTeX writer could look to visit_abbreviation() for inspiration.
I noticed that HTML rendering relies on this CSS:
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
I find this disconcerting that the mouse pointer becomes a question mark (in Firefox) but nothing happens on click. I wanted to include a screenshot but I can not capture the transformed mouse pointer in Firefox.