patch_latex.py

Go to the documentation of this file.

"""Post-process Doxygen's refman.tex before pdflatex, to match the Cryptnox PDF style.
 
Usage: python3 docs/patch_latex.py docs/latex/refman.tex ["Friendly Title"]
"""
import os
import re
import sys
 
path = sys.argv[1]
title = sys.argv[2] if len(sys.argv) > 2 else None
 
# pdflatex can't embed the committed SVG logo directly, so convert it to a PDF beside
# refman.tex for the \includegraphics{cryptnox-logo-dark} on the cover (cairosvg in CI).
try:
    import cairosvg
except ImportError as _e:
    raise RuntimeError(
        "PDF docs build requires cairosvg to generate the cover logo; "
        "install it (pip install cairosvg)."
    ) from _e
cairosvg.svg2pdf(
    url=os.path.join(os.path.dirname(path), os.pardir, "cryptnox-logo.svg"),
    write_to=os.path.join(os.path.dirname(path), "cryptnox-logo-dark.pdf"),
)
 
with open(path, encoding="utf-8") as _f:
    s = _f.read()
 
# Use TeX Gyre Heros (sans) for the whole document, like the Sphinx PDFs.
# Doxygen already defaults to \sfdefault; just swap its Helvetica for TeX Gyre Heros.
s = s.replace(r"\usepackage[scaled=.90]{helvet}", "\\usepackage{tgheros}\n\\usepackage{tgtermes}")
 
# Remove the "Generated by Doxygen X.Y.Z" credit from the title page
s = re.sub(r"\{\\large Generated by Doxygen[^}]*\}\\\\\s*", "", s)
 
# Right-align the title-page block and put the logo inside the same flushright as the
# title, with identical spacing to the Sphinx covers (\vskip 1em / logo / \vskip 2em).
# Must run BEFORE the title-font edit below, which rewrites \Large -> \LARGE\bfseries.
s = s.replace(
    "\\begin{center}%\n  {\\Large",
    "\\begin{flushright}%\n"
    "  \\vskip -0.5em%\n"
    "  \\includegraphics[width=7cm]{cryptnox-logo-dark}\\par\n"
    "  \\vskip 2em%\n"
    "  {\\Large",
)
s = s.replace(
    "\\end{center}\n  \\end{titlepage}",
    "\\end{flushright}\n  \\vfill\n  \\begin{flushright}\\large June 20, 2026\\end{flushright}\n  \\end{titlepage}",
)
 
# Title: use the friendly name (passed as arg) + "Manual", in the Sphinx cover font.
# Falls back to the Doxygen project name if no title is given.
if title:
    s = re.sub(r"\{\\Large [^}]*\}\\\\",
               lambda m: r"{\LARGE\sffamily\bfseries " + title + r" Manual}\\", s, count=1)
else:
    s = re.sub(r"\{\\Large ([^}]*)\}\\\\", r"{\\LARGE\\sffamily\\bfseries \1 Manual}\\\\", s, count=1)
 
# Version: prefix with "Release", unify the font (\large\itshape), and add more space
# above it (title -> version gap), via the \\ optional length
s = re.sub(r"\‍[1ex\‍]\\large (.*?) \\\\", r"[1.5em]{\\large\\itshape Release \1}\\\\", s, count=1)
 
# Headings (chapters, sections, "Contents") in the sans heading font, like the
# Sphinx PDFs and the Yubico manual (TeX Gyre Heros bold), keeping Doxygen's gray.
s = re.sub(
    r"\\doxyallsectionsfont\{%\s*\\fontseries\{bc\}\\selectfont%\s*\\color\{darkgray\}%\s*\}",
    lambda m: (
        r"\doxyallsectionsfont{\sffamily\bfseries\color{black}}"
        "\n\\makeatletter"
        "\n\\renewcommand{\\@makechapterhead}[1]{%"
        "\n  \\vspace*{50\\p@}{\\parindent\\z@\\raggedright\\sffamily"
        "\n    \\ifnum\\c@secnumdepth>\\m@ne"
        "\n      \\huge\\bfseries\\color{black}\\@chapapp\\space\\thechapter\\par\\nobreak\\vskip 20\\p@\\fi"
        "\n    \\interlinepenalty\\@M\\Huge\\bfseries\\color{black}#1\\par\\nobreak\\vskip 40\\p@}}"
        "\n\\renewcommand{\\@makeschapterhead}[1]{%"
        "\n  \\vspace*{50\\p@}{\\parindent\\z@\\raggedright\\sffamily"
        "\n    \\interlinepenalty\\@M\\Huge\\bfseries\\color{black}#1\\par\\nobreak\\vskip 40\\p@}}"
        "\n\\makeatother"
    ),
    s, count=1,
)
 
# One-sided layout (no blank filler pages)
s = s.replace(r"\documentclass[twoside]", r"\documentclass[oneside]")
 
# Footer: replace "Generated by Doxygen" with the copyright, in the sans heading font
# (footer only; the title-page credit uses \large, so it is left untouched)
s = s.replace(
    r"\bfseries\scriptsize Generated by Doxygen",
    r"\sffamily\fontsize{11}{13.6}\selectfont \copyright{} 2026 Cryptnox SA",
)
 
# Running header: sans, regular weight, 11pt — same size as the Sphinx PDFs
s = s.replace(r"\fancyhead[LE, RO]{\bfseries\thepage}", r"\fancyhead[LE, RO]{\sffamily\fontsize{11}{13.6}\selectfont\thepage}")
s = s.replace(r"\fancyhead[LO]{\bfseries\rightmark}", r"\fancyhead[LO]{\sffamily\fontsize{11}{13.6}\selectfont\rightmark}")
s = s.replace(r"\fancyhead[RE]{\bfseries\leftmark}", r"\fancyhead[RE]{\sffamily\fontsize{11}{13.6}\selectfont\leftmark}")
 
# Sans-serif TOC entries
s = s.replace(r"\tableofcontents", r"\addtocontents{toc}{\protect\sffamily}\tableofcontents", 1)
 
# 4pt gap between header/footer text and their rules
s = s.replace(
    r"\pagestyle{fancyplain}",
    r"\def\headruleskip{4pt}\def\footruleskip{4pt}\pagestyle{fancyplain}",
    1,
)
 
# pdflatex (inputenc utf8) aborts on any Unicode char it doesn't know. Declare the
# math relations we want rendered as real glyphs (used in @c doc comments, e.g.
# "len <= 254"); everything else non-ASCII is transliterated to safe ASCII at the end
# of this script. Without this, pdflatex stops with "Unicode character not set up".
s = s.replace(
    r"\begin{document}",
    "\\DeclareUnicodeCharacter{2264}{\\ensuremath{\\leq}}\n"
    "\\DeclareUnicodeCharacter{2265}{\\ensuremath{\\geq}}\n"
    "\\begin{document}",
    1,
)
 
# Drop the alphabetical index
s = s.replace(r"\printindex", "")
s = s.replace(r"\addcontentsline{toc}{chapter}{\indexname}", "")
 
# Replace the default top gap with just the top rule (the logo is injected inside the
# flushright above, matching the Sphinx layout)
s = s.replace(r"\vspace*{7cm}", r"\noindent\rule{\textwidth}{1pt}\par")
 
with open(path, "w", encoding="utf-8") as _f:
    _f.write(s)
print("patched", path)
 
# Section/subsection headings are defined in doxygen.sty (not refman.tex) with a
# hardcoded \normalfont (serif); switch them to the sans heading font + gray.
sty = os.path.join(os.path.dirname(path), "doxygen.sty")
if os.path.exists(sty):
    with open(sty, encoding="utf-8") as _f:
        d = _f.read()
    d = d.replace(r"{\raggedright\normalfont", r"{\raggedright\sffamily\color{black}")
    with open(sty, "w", encoding="utf-8") as _f:
        _f.write(d)
    print("patched", sty)
 
# Strip the "Download this documentation as PDF" link from the mainpage (README) —
# pointless inside the PDF itself. Kept in README.md for GitHub/HTML.
idx = os.path.join(os.path.dirname(path), "index.tex")
if os.path.exists(idx):
    with open(idx, encoding="utf-8") as _f:
        i = _f.read()
    i = re.sub(r"^.*Download this documentation as PDF.*\n", "", i, flags=re.MULTILINE)
    with open(idx, "w", encoding="utf-8") as _f:
        _f.write(i)
    print("patched", idx)
 
# Final safety net: Doxygen emits non-ASCII from source comments and the README
# (box-drawing art in directory trees / wiring diagrams, arrows, stray symbols) into
# every *.tex file. pdflatex's inputenc fatally stops on any codepoint it doesn't
# know, and which ones appear changes as the docs change — so instead of declaring
# each one, transliterate to ASCII here. Chars LaTeX already renders well are kept;
# box-drawing is mapped to ASCII; anything else is dropped so the build cannot fail
# on an unexpected glyph. Runs last, over all .tex files (the .sty files are pure
# LaTeX and contain no such literals).
import glob
 
# Codepoints inputenc/textcomp already render (verified in CI logs) plus the math
# relations declared above — left untouched so their nicer glyphs survive.
keep = frozenset({
    0x00A0, 0x00B2, 0x00B3, 0x00D7,            # nbsp, superscript 2/3, multiplication
    0x2013, 0x2014, 0x2026,                    # en/em dash, ellipsis
    0x2018, 0x2019, 0x201C, 0x201D,            # curly quotes
    0x2190, 0x2192, 0x2194,                    # left/right/both arrows
    0x2264, 0x2265,                            # <= and >= (declared in the preamble)
})
 
 
def _to_ascii(match):
    cp = ord(match.group(0))
    if cp in keep:
        out = match.group(0)
    elif 0x2500 <= cp <= 0x257F:
        # Box-drawing block: verticals -> '|', corners/tees -> '+', the rest -> '-'.
        if cp in (0x2502, 0x2503, 0x2551):
            out = "|"
        elif 0x250C <= cp <= 0x254B:
            out = "+"
        else:
            out = "-"
    else:
        out = ""
    return out
 
 
for tex in glob.glob(os.path.join(os.path.dirname(path), "*.tex")):
    with open(tex, encoding="utf-8") as _f:
        body = _f.read()
    # refman.tex's preamble holds Doxygen's own \doxynewunicodechar{<char>}{...}
    # declarations; transliterating those would empty the first argument and crash.
    # Only rewrite the document body. Other .tex files are pure body (no \begin{document}),
    # so the marker is absent and the whole file is processed.
    marker = "\\begin{document}"
    split = body.find(marker)
    head = body[:split] if split != -1 else ""
    tail = body[split:] if split != -1 else body
    fixed = head + re.sub(r"[^\x00-\x7F]", _to_ascii, tail)
    if fixed != body:
        with open(tex, "w", encoding="utf-8") as _f:
            _f.write(fixed)
        print("transliterated", tex)