Ansel 0.0
A darktable fork - bloat + design vision
Loading...
Searching...
No Matches
doxygen-math-filter.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2"""Doxygen input filter : Markdown dollar-math -> Doxygen native math.
3
4Converts `$...$` (inline) and `$$...$$` (display) LaTeX equations into
5Doxygen's `\\f$...\\f$` and `\\f[...\\f]` commands, so that:
6
7 1. formula bodies are protected from Doxygen's Markdown pass (a raw `$c_{mix}$`
8 would have its underscore parsed as emphasis and reach MathJax broken);
9 2. rendering goes through the stock Doxygen + MathJax machinery
10 (USE_MATHJAX = YES in doc/Doxyfile), no client-side delimiter hacks.
11
12This mirrors the convention of the user documentation (Hugo + MathJax), so the
13same equation markup works in both doc trees. Applied to *.md files only, via
14FILTER_PATTERNS in doc/Doxyfile — C/C++ comments keep using \\f$ natively
15(and their `$MIN/$MAX/$DEFAULT` introspection tokens are never touched).
16
17Rules, matching the usual Markdown-math conventions:
18 - `$$...$$` may span several lines; `$...$` must stay on one line;
19 - the opening `$` must be immediately followed by a non-space, the closing
20 `$` immediately preceded by one (so "5$ and 10$" or "$5 vs $10" are left
21 alone);
22 - `\\$` is an escaped, literal dollar;
23 - fenced code blocks (``` / ~~~) and inline code spans (`...`) are never
24 converted.
25"""
26
27import re
28import sys
29
30# display math, possibly multiline ; escaped \$ do not delimit
31_DISPLAY = re.compile(r"(?<!\\)\$\$(.+?)(?<!\\)\$\$", re.S)
32# inline math, single line, snug delimiters ; body may contain escaped chars ;
33# the closing $ must be preceded by a non-space that is not a backslash, so an
34# escaped \$ can never close a formula (backtracking would otherwise allow it)
35_INLINE = re.compile(r"(?<![\\$])\$(?=\S)((?:\\.|[^$\n])+?)(?<=\S)(?<!\\)\$(?!\$)")
36# fenced code blocks, indented code blocks (4 spaces / tab, the old Markdown
37# style), then inline code spans, all kept verbatim
38_FENCED = re.compile(r"(```.*?```|~~~.*?~~~)", re.S)
39_INDENTED = re.compile(r"((?:^(?:[ ]{4,}|\t).*\n?)+)", re.M)
40_CODE_SPAN = re.compile(r"(`[^`\n]*`)")
41
42
44 text = _DISPLAY.sub(r"\\f[\1\\f]", text)
45 return _INLINE.sub(r"\\f$\1\\f$", text)
46
47
48def convert(text):
49 out = []
50 for i, block in enumerate(_FENCED.split(text)):
51 if i % 2 == 1: # fenced code : verbatim
52 out.append(block)
53 continue
54 for j, chunk in enumerate(_INDENTED.split(block)):
55 if j % 2 == 1: # indented code : verbatim
56 out.append(chunk)
57 continue
58 for k, span in enumerate(_CODE_SPAN.split(chunk)):
59 out.append(span if k % 2 == 1 else _convert_prose(span))
60 return "".join(out)
61
62
63if __name__ == "__main__":
64 with open(sys.argv[1], encoding="utf-8", errors="replace") as f:
65 sys.stdout.write(convert(f.read()))