Feature Discussion: Subequation Groups (`<mds>`)
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 8/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Ferma
- Stack tecnologico
- html, latex, xml
- Ambito
- documentation
Direzione di ricerca
This is a design proposal awaiting maintainer feedback, not a task to pick up. The payload names schema/pretext.rng, xsl/pretext-assembly.xsl, xsl/pretext-common.xsl, xsl/pretext-latex-common.xsl and xsl/pretext-html.xsl, plus the fork's examples/test-subequations/. Done would mean a maintainer decision on whether <mds> belongs upstream, and the work would span all output backends.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Feature Discussion: Subequation Groups (<mds>)
Summary
This discussion proposes a new display-math element, <mds> (math display subequations), that brings PreTeXt to feature parity with LaTeX's \begin{subequations} environment. The element allows authors to group a collection of related equations under a single parent number, with each row in the group receiving a letter suffix — for example, equations 3a, 3b, 3c sharing the parent number 3, where a cross-reference to the group resolves to "3" and a cross-reference to an individual row resolves to "3a".
This is not a pull request — it is a request for feedback on whether the feature aligns with PreTeXt's direction and whether the implementation approach is suitable for upstream integration. A working implementation is available on a fork (https://github.com/saustinp/pretext) on the feature/subequations branch with end-to-end test coverage in all four output backends.
I ported an academic research paper to PreTeXt for submission to an AIAA journal, and during the port I repeatedly hit the absence of grouped equation numbering. In LaTeX this is a daily-use feature in physics, engineering, and applied mathematics writing — Maxwell's equations, the Navier-Stokes equations, kinematic equation sets, conservation laws, and so on are virtually always presented as a numbered group with sub-letters, not as four separate equations occupying four counter slots. The absence forced me into one of two unsatisfactory workarounds: (a) manually @tag each row with arbitrary symbols (@tag="star", @tag="dagger", etc.), losing automatic numbering and breaking cross-references, or (b) accept that the equations would be numbered (1), (2), (3), (4) as if unrelated, breaking the convention readers in the field expect.
Nobody has explicitly requested this feature on the issue tracker that I could find, but I believe that is because authors who need it have, like me, simply worked around it or chosen not to port papers that depend on it. Closing this gap is a meaningful step toward making PreTeXt a viable target for technical research papers.
What <mds> does
Authored XML
<mds xml:id="eq-maxwell">
<mrow xml:id="eq-gauss-e">\nabla \cdot \mathbf{E} \amp= \frac{\rho}{\epsilon_0}</mrow>
<mrow xml:id="eq-gauss-m">\nabla \cdot \mathbf{B} \amp= 0</mrow>
<mrow xml:id="eq-faraday">\nabla \times \mathbf{E} \amp= -\frac{\partial \mathbf{B}}{\partial t}</mrow>
<mrow xml:id="eq-ampere">\nabla \times \mathbf{B} \amp= \mu_0 \mathbf{J} + \mu_0 \epsilon_0 \frac{\partial \mathbf{E}}{\partial t}</mrow>
</mds>
Rendered output
If the <mds> block occupies equation slot 3 in its enclosing section, the four rows render as (3a), (3b), (3c), (3d). A cross-reference <xref ref="eq-maxwell"/> resolves to "Equations 3", and a cross-reference to an individual row such as <xref ref="eq-faraday"/> resolves to "(3c)". The group occupies exactly one slot in the equation counter — the equation immediately following the <mds> block is numbered (4), not (7).
The element supports the same @alignment and @alignat-columns attributes as the existing <md> element (align, gather, alignat), and <intertext> is supported for inserting prose between rows of the group.
Why this is the right shape for PreTeXt
The design closely mirrors an existing precedent in the codebase: subfigures, where a figure/sidebyside/figure consumes one slot in the figure counter and its child figures receive lettered serial numbers via <xsl:number format="a"/>. The same parent-number-plus-letter pattern is exactly what subequations requires, and it allowed the implementation to follow established PreTeXt patterns rather than inventing new mechanisms.
The element naming follows the existing PreTeXt convention: md is "math display" (multi-line, unnumbered by default), mdn was the now-deprecated "math display numbered," and mds reads naturally as "math display subequations." The name is short, follows the prefix pattern, and is unlikely to collide with anything.
The element is positioned in the schema as one more <choice> inside the existing MathDisplay definition, so it appears as a valid block-level element wherever <md> is currently allowed, with no impact on any other content model.
Implementation overview
The implementation spans nine files. The total diff is approximately 280 lines of additions, with no file rewrites and no existing template signatures changed in a way that affects backwards compatibility.
Schema (schema/pretext.rng)
Added <mds> as a new element inside the MathDisplay <choice>. It has:
- A
MetaDataTarget(so the group can carry an@xml:idfor cross-referencing) - Optional
@break,@alignment,@alignat-columnsattributes (consistent with<md>) - A required first
<mrow>followed by zero or more<mrow>or<intertext>children - No
@numberattribute — every row in an<mds>is numbered by definition (that is the whole point)
Assembly preprocessing (xsl/pretext-assembly.xsl)
Three new repair templates:
mds[mrow] mode="repair"preserves the<mds>element rather than normalizing it to<md>(unlike theme/men/mdnrepair templates, the wrapper carries semantic meaning that affects numbering and backend output, so it must be retained through assembly)mds/mrow mode="repair"forces@pi:numbered="yes"on all child rows (with@tagstill respected as an override)mds[intertext] mode="repair"is the analog of the existingmd[intertext]exploder, but the explosion produces<md>fragments inside the<mds>wrapper rather than as top-level siblings, so the grouping is preserved across intertext
Numbering (xsl/pretext-common.xsl)
The numbering work is the most subtle part of the change and mirrors the subfigure pattern exactly:
mrow[@pi:numbered = 'yes'] mode="serial-number"(existing template) had its count expression broadened frommrow[@pi:numbered = 'yes']tomrow[@pi:numbered = 'yes' and not(ancestor::mds)] | mds. This ensures the equation counter sees an<mds>block as exactly one numbered item (consuming one slot) and excludes the rows inside it from the global count. For documents that contain no<mds>elements, this is a strict no-op —not(ancestor::mds)is trivially true and the union withmdsadds nothing.mds mode="serial-number"(new) computes the parent number for the group, using the same subtree-level logic as the existingmrowtemplatemds//mrow[@pi:numbered = 'yes'] mode="serial-number"(new) computes the letter suffix using<xsl:number format="a" level="any" from="mds"/>mds mode="structure-number"(new) inherits from the enclosing division, exactly like a regular equationmds//mrow mode="structure-number"(new) returns the parent<mds>'s full number, parallelingfigure/sidebyside/figure mode="structure-number"mode="number"had one new<xsl:when>added to its separator-selection<xsl:choose>, suppressing the period between structure and serial when the context is anmrowinside an<mds>(so the output is "3a", not "3.a"). This sits alongside the existing analogous condition for subfigures.
LaTeX backend (xsl/pretext-latex-common.xsl)
A new top-level mds template wraps its inner content in \begin{subequations}...\end{subequations}. LaTeX's native subequations environment handles the parent-number-plus-letter assignment automatically, so \label{} on the group and on individual <mrow> elements works naturally with no further modification. The inner equation environment (\begin{align} or \begin{gather}) is selected by the existing alignment-detection logic, which was generalized from md[mrow] to also match mds[mrow].
HTML / MathJax backend (xsl/pretext-html.xsl)
A new mds[mrow] template delegates to the same mode="body" as md[mrow]. The existing mrow mode="tag" template that emits \tag{<computed-number>} for MathJax to render is unchanged — it works correctly out of the box because step 3 above ensures mode="number" produces "3a" for mds//mrow. New templates were added for mds in the display-math-wrapper, is-hidden, body-element, body-css-class, heading-xref-knowl, and xref-as-knowl modes, each parallel to the existing md[mrow] template.
EPUB backend (xsl/pretext-epub.xsl)
A one-line addition: mds was added to the existing match="m|md[mrow]" pattern of the math rendering template, so <mds> elements are looked up in the pre-rendered SVG/MathML representation file alongside other math.
Math extraction (xsl/support/extract-math.xsl)
Two one-line additions: mds was added to the extraction and display-math-wrapper template matches, so the math extraction phase that produces representation files for HTML, EPUB, and braille correctly walks into <mds> elements.
Braille backend (xsl/pretext-braille-preprint.xsl)
Two one-line additions:
mdswas added to themeld-mathmode template that attaches the pre-rendered Nemeth braille to math elementsmdswas added to the math display template at line 1617
Localization (xsl/localizations/en-US.xml)
A new mds localization string was added with the value "Equations" (the plural form, since a group of equations is being referenced). This is used by the cross-reference type-name lookup so that <xref ref="eq-maxwell"/> renders as "Equations 3" rather than the bare number.
Cross-reference target list (xsl/pretext-common.xsl)
mds was added to the is-xref-target match pattern, registering it as a valid cross-reference target type.
Verification
A test document is included in the fork at examples/test-subequations/. It contains:
- A regular
<men>numbered equation before the subequation block (to verify counter continuity) - A four-row
<mds>block (Maxwell's equations) with@alignment="align" - A regular
<men>after the block (to verify the counter increments by exactly one) - A second
<mds>block in a different section using@alignment="gather"(kinematic equations) - Cross-references to both the group and individual rows of both
<mds>blocks
The document was built in all four output formats and verified end-to-end:
| Format | Group cross-ref | Sub-letter cross-refs | Equation rendering |
|---|---|---|---|
| HTML / MathJax | ✅ "Equations 1.2" | ✅ "(1.2a)" through "(1.2d)" | ✅ |
| LaTeX → PDF | ✅ "Equations 1.2" | ✅ "(1.2a)" through "(1.2d)" | ✅ via native \begin{subequations} |
| EPUB (SVG math) | ✅ "Equations 1.2" | ✅ "(1.2a)" through "(1.2d)" | ✅ |
| Braille (Nemeth) | ✅ "Equations 1.2" | ✅ "(1.2a)" through "(1.2d)" | ⚠️ see "Braille testing" section — separate upstream issue, not subequations-specific |
The HTML output has \tag{1.1}, \tag{1.2a} through \tag{1.2d}, and \tag{1.3} — exactly the expected sequence with the group consuming slot 1.2. The LaTeX output produces clean \begin{subequations}\label{eq-maxwell}\begin{align}...\label{eq-gauss-e}\\...\end{align}\end{subequations} blocks. The EPUB renders identically to HTML. The braille output has the correct cross-reference text for both the group ("Equations 1.2") and individual rows ("(1.2a)", "(1.2c)", "(2.1b)") — the equation interiors of all numbered display math (including plain <men>) are currently empty in braille due to a separate upstream SRE limitation that predates and is unrelated to this work; details in the "Braille testing" section below.
Braille testing — what was verified, and an unrelated upstream limitation
I want to be transparent about what was verified for braille and what wasn't, because the picture is more nuanced than the other three formats — and because understanding the structure of PreTeXt's braille build is necessary to interpret the test results correctly.
Two parallel pipelines feed the final .brf
PreTeXt's braille build assembles its output from two independent subsystems that share nothing except the final .brf file format:
-
Text pipeline. Section headings, body prose, captions, and all cross-reference text are produced by the XSL stylesheets (
pretext-braille-preprint.xsland its imports) and handed off as plain English text to liblouis (file2brl), which encodes everything character-by-character into UEB ASCII braille. This pipeline does not invoke MathJax or SRE —mode="number",mode="structure-number", andmode="serial-number"all run as ordinary XSL templates and their string outputs flow through to liblouis as prose. -
Math pipeline. The interiors of display equations (the actual
E = mc^2,\nabla \cdot \mathbf{E} = \rho/\epsilon_0, etc.) are produced by extracting LaTeX from each math element, sending it to MathJax + the Speech Rule Engine via the Node.js helper atscript/mjsre/mj-sre-page.js, receiving Nemeth braille Unicode back, and re-injecting the result into the document tree as a<math-nemeth>child element. The braille preprint XSL then emits this content between Nemeth math markers in the final.brf.
The subequations feature is implemented entirely in the text pipeline. All of the new XSL templates added in this PR — the structure-number and serial-number templates for mds and mds//mrow, the separator suppression in mode="number", the assembly repair templates, the string-id and localization additions — are part of pipeline 1.
What was verified in braille
The text pipeline is fully exercised for braille and produces correct output. Inspecting the cross-reference paragraph in the test document's output/braille/main.brf:
,equa;ns #a4b4 ,gauss's law = electric;y
is "<#a4b;a">4 ,f>a"d's law is "<#a4b;c">4
Decoded from UEB ASCII (where , is a capital indicator, ;n is the contraction for the "tion" suffix, # is the digit indicator, 4 is the period when in number/punctuation context, ;a/;c are letter indicators followed by the letter, = is the contraction for "for", and > is the contraction for "ar"):
"Equations 1.2. Gauss's law for electricity is (1.2a). Faraday's law is (1.2c)."
All three subequation cross-reference cases are present and correctly numbered:
- The
<mds>group reference (<xref ref="eq-maxwell"/>) → "Equations 1.2" - Individual
mds//mrowreferences (<xref ref="eq-gauss-e"/>,<xref ref="eq-faraday"/>) → "(1.2a)", "(1.2c)" - The same pattern holds for the second
<mds>block in section 2:"<#b4a;b">decodes to "(2.1b)"
This demonstrates that the new templates for mds and mds//mrow are reaching the braille build correctly: the structure number is being computed from the parent <mds>, the serial letter is being computed from <xsl:number format="a"/>, the period separator is correctly suppressed between them, and the localization string "Equations" is being looked up via the new string-id template. Equation numbering also correctly skips from "1.1" to "1.3" past the <mds> block, confirming that the modified equation counter is treating the group as a single slot in the braille build as well.
The pre-existing limitation that affects equation interiors (not subequations)
PreTeXt's separate math-rendering pipeline (LaTeX → MathJax → SRE → Nemeth braille) is what produces the equation interiors that sit between the Nemeth math markers in the .brf. This pipeline is currently broken for any numbered equation due to an issue in the upstream Speech Rule Engine library, with the result that the equation interiors of all numbered display math (not just <mds>) come out empty in the final braille. This is unrelated to the subequations work — the same failure occurs for plain <me>, <men>, and <md> elements containing numbered equations, and reproduces on upstream pretext-cli as well as on this fork.
The specific issue is:
SRE 4.0.7 silently produces empty Nemeth braille output for any LaTeX equation that contains a
\tag{}command. This was confirmed by testing identical input with and without\tag{}againstscript/mjsre/mj-sre-page.jsdirectly. Without the tag, SRE produces correct Nemeth braille (e.g.,⠠⠑⠀⠨⠅⠀⠍⠉⠘⠆forE = mc²); with the tag, the<mjx-braille>output element is empty. SRE 4.0.7 is the version pinned inscript/mjsre/package.json, so this affects every PreTeXt installation that has run theupdate-srescript recently.
PreTeXt's HTML/MathJax pipeline emits \tag{} commands as the visible-equation-number mechanism for MathJax — for HTML, EPUB, and PDF this is correct and necessary. For braille the tag is what's tripping SRE, but the equation number for the braille rendering is generated separately through pipeline 1 (the text pipeline) via mode="number", so the tag is functionally redundant in the braille context.
I did not include a fix for this in the subequations PR because it is a pre-existing braille pipeline issue that affects every numbered equation in every PreTeXt document, not just subequations. I have a working one-line patch (strip \tag{...} in mj-sre-page.js when the --braille argument is set) that I am happy to file as a separate issue or PR.
There is also a second pre-existing braille issue I noticed during testing: cross-references to <men> elements (not <mds>) render as empty parentheses in braille. The cause is the meld-math template wrapping the inner <mrow> of an <men> (which becomes <md @pi:authored-one-line> after assembly) inside a <math-original> element, which breaks the select="mrow" direct-child XPath in the existing md[@pi:authored-one-line] mode="serial-number" template. The original braille developer left a comment in pretext-braille-preprint.xsl lines 100-104 acknowledging this kind of issue:
NB: after a md[mrow] goes through MathJax/SRE there is no "mrow" left. So they are absent in "math-nemeth". They are present in "math-original" but that introduces a new element in-between "md" and "mrow", so matches on "md[mrow]" can be problematic here (and perhaps elsewhere).
This is also out of scope for the subequations PR, but I note it for the record.
Bottom line
The subequations feature itself is verified working in the braille build via the text pipeline: cross-references to <mds> groups and to individual mds//mrow rows render correctly in the final .brf, and the equation counter correctly treats each <mds> block as one slot. This is the part of the build that the new XSL templates affect. The pre-existing limitation in the math pipeline (empty equation interiors for any tagged equation) affects the visual presentation of all numbered display math in every PreTeXt document, and is worth fixing in separate work — but it is neither caused by nor specific to subequations.
What is affected by inclusion
This is a question I want to address directly because it is the question I would ask first as a maintainer.
Existing documents are unaffected. The change to the equation counter at xsl/pretext-common.xsl line 4254 (from count="mrow[@pi:numbered = 'yes']" to count="mrow[@pi:numbered = 'yes' and not(ancestor::mds)] | mds") is the only modification to a pre-existing template's behavior. For any document that contains no <mds> elements, not(ancestor::mds) is trivially true and | mds adds nothing — the count is identical to before. I verified this against the existing examples/sample-article document: equation numbering in derivatives.html, section-mathematics.html, etc. is unchanged after the modification (sequential \tag{6.1} through \tag{7.6}, no gaps, no shifts).
The remaining changes are purely additive. All other modified templates either add mds to an existing match pattern (via the | union operator), or add brand-new templates with match patterns specific to mds and its descendants. None of them can match elements that existed before this PR.
The schema change is also additive. <mds> is added as a new option inside the MathDisplay <choice>. Documents that don't use <mds> continue to validate against the schema unchanged.
No deprecation. Nothing is being removed, renamed, or marked deprecated. <md>, <mdn>, <me>, <men>, and the @number and @tag attributes on <mrow> all continue to work exactly as before.
Cross-stylesheet stylesheets that import these files (custom publisher stylesheets in user projects) should not be affected unless they happen to override one of the modified templates by name. The most likely candidate would be a custom override of the mrow[@pi:numbered = 'yes'] mode="serial-number" template, which is rare in practice — most custom publisher work overrides higher-level templates like mode="number" or layout templates, not the leaf-level numbering templates. If such an override does exist in someone's stylesheet, the failure mode is graceful: their custom template wins as usual, and mds simply doesn't get the new numbering behavior in their build (it would fall back to whatever their override does for mrow).
Open questions for the maintainers
A few things I would appreciate guidance on before this becomes a PR:
-
Element name. I chose
mdsto follow themd/mdnpattern. If the project would prefer a different name (subequations,equations,eqn-group, or something else), I am happy to rename — the implementation is mechanical to update. -
Localization string. I added
mds→ "Equations" inen-US.xml. Should this go through the existing translation workflow before merging, or is adding the English string sufficient and other locales can be added later? -
Schema versioning. PreTeXt's schema does not appear to be strictly versioned. Should new elements like this be gated behind a version attribute or feature flag, or is direct addition the norm?
-
Whether to fold the braille fixes into this PR or keep them separate. My instinct is to keep them separate (one PR per concern), but if the maintainers would prefer a single coordinated change to ship "subequations + working braille" together, I can combine them.
-
Test placement. Where should the
examples/test-subequations/test document live? Inexamples/, intests/, or in the existing sample-article as new sections?
I am happy to discuss any aspect of the implementation, iterate on the design, or rework the approach based on feedback. The fork is at https://github.com/saustinp/pretext on the feature/subequations branch.
- Lingua principale
- XSLT
- Stelle
- 466
- Fork
- 251
- Merge medio
- 4m
- PR unite (30g)
- 13
Preparare l'ambiente
Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di PreTeXtBook/pretext
-
The print preview leaves writing space short by the margins of hidden headers, footers and solutionsAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
PreTeXtBook/pretext#3329 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 1-3 ore Idoneità per principianti 82/100
PreTeXtBook/pretext#3305 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
PreTeXtBook/pretext#3297 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 88/100
PreTeXtBook/pretext#3285 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
PreTeXtBook/pretext#3283 ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di PreTeXtBook/pretext
Issue simili
-
Difficoltà 1/5 1-3 ore Idoneità per principianti 75/100
cran-task-views/Spatial#130 ·
-
clawsweeper:fix-shape-clear clawsweeper:queueable-fix clawsweeper:source-repro impact:ux-friction issue-rating: 🦞 diamond lobster no-stale P2
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
openclaw/openclaw-windows-node#2287 · 2 commenti · 1 reazione ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 78/100
daniel-ospina/tortoise#13343 ·
I maintainer di solito rispondono entro 1 giorno
-
[Docs]: Clarify theme variables location and usage in CONTRIBUTING.mdForse già presa @srishtimishra520-beep l’ha presa oggi. Apertakind/docs
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 88/100
meshery/meshery.io#3220 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
Revise communication normsApertacurrent task
Difficoltà 1/5 1-3 ore Idoneità per principianti 88/100
Sunday-School-Software/Sunday-School-Scheduler#87 ·
I maintainer di solito rispondono entro 1 giorno