[bug] Documentation "export as PDF"

[yreyricord]

Affected component

Documentation

Severity

Minor - degraded behaviour with workaround

Version or commit reference

v4.4.5

Environment

Operational deployment

Observed behaviour

The Build ATBD web export PDF step of the Documentation workflow (.github/workflows/docs.yml) fails on XeLaTeX with ~55 instances of:

! Package amsmath Error: \tag not allowed here.
l.NNNN \end{split}

make -C docs atbd-pdf exits with Error 12, the workflow step exits with code 2. The step is currently wrapped in continue-on-error: true, so the workflow stays green and GitHub Pages still deploys — but the ATBD PDF artifact is never produced and the run logs are polluted by the errors.

Root cause: in docs/science-guide/atbd-l2-agb/*.md, equations use \tag{} inside \begin{split}...\end{split} blocks. amsmath does not allow \tag inside split; it must be applied to the surrounding equation environment. MyST also emits the starred equation* form (because math_numfig = False in docs/conf.py), which compounds the problem since equation* does not accept \tag at all.

Affected files (~55 equations between source lines reflected as 1561–5330 of the generated .tex):

• docs/science-guide/atbd-l2-agb/03-ground-cancellation.md
• docs/science-guide/atbd-l2-agb/04-agb-estimation.md

Secondary warnings observed in the same run (out of scope for this issue, listed for completeness):

• WARNING: command 'mmdc' cannot be run (needed for mermaid output) × 8 — Mermaid CLI absent on the runner.
• LaTeX Warning: Hyper reference '…' undefined × ~30 — MyST cross-refs not resolving in the LaTeX backend.
• Package fancyhdr Warning: \headheight is too small — cosmetic.
• Numerous Overfull/Underfull \hbox — cosmetic, oversized table columns.

Expected behaviour

• make -C docs atbd-pdf runs to completion (exit code 0) inside the GitHub Actions runner.
• docs/_build/atbd-l2-agb.pdf is produced and uploaded as a workflow artifact.
• No \tag not allowed here errors in the latexmk log.
• continue-on-error: true can be removed from the Build ATBD web export PDF step, so future regressions fail loudly instead of being silently hidden.

Suggested fix path (Option A in the analysis): in the affected ATBD Markdown files, replace \begin{split}…\end{split} with \begin{aligned}…\end{aligned} and move \tag{} outside the alignment block. This builds correctly in both Sphinx HTML (MathJax) and XeLaTeX.

Pattern before:

$$
\begin{split}
y &= a x + b \\
  &= \ldots \tag{3.13}
\end{split}
$$

Pattern after:

$$
\begin{aligned}
y &= a x + b \\
  &= \ldots
\end{aligned} \tag{3.13}
$$

Steps to reproduce

1. `git clone https://github.com/BioPAL/BPS.git && cd BPS/docs`
2. `pip install -r requirements.txt && sudo apt-get install -y texlive-xetex texlive-latex-extra latexmk` (or the equivalent on macOS / from `.github/workflows/docs.yml`)
3. `make atbd-pdf` — observe the `! Package amsmath Error: \tag not allowed here.` failures and the final `make: *** [Makefile:94: atbd-pdf] Error 12`.

Reproducible identically on the CI runner: push any change matching `docs/**` to `develop` and inspect the `Documentation → build → Build ATBD web export PDF` step.

Logs and traceback

processing atbd-l2-agb.tex... 
science-guide/atbd-l2-agb/index
 science-guide/atbd-l2-agb/01-introduction
 science-guide/atbd-l2-agb/02-bps-agb-overview
 science-guide/atbd-l2-agb/03-ground-cancellation
 science-guide/atbd-l2-agb/04-agb-estimation
 science-guide/atbd-l2-agb/05-appendix
 science-guide/atbd-l2-agb/references

build succeeded, 8 warnings.

The LaTeX files are in _build/atbd-pdf/latex.

Latexmk: applying rule 'xelatex'...
Running 'xelatex --no-pdf  -no-pdf -interaction=nonstopmode -recorder  "atbd-l2-agb.tex"'

! Package amsmath Error: \tag not allowed here.

See the amsmath package documentation for explanation.
Type  H <return>  for immediate help.
 ...
l.1561 \end{split}

! Package amsmath Error: \tag not allowed here.
l.2353 \end{split}

! Package amsmath Error: \tag not allowed here.
l.2365 \end{split}

[... ~55 occurrences total, between lines 1561 and 5330 of atbd-l2-agb.tex ...]

! Package amsmath Error: \tag not allowed here.
l.5330 \end{split}

Output written on atbd-l2-agb.xdv (53 pages, 827852 bytes).
Transcript written on atbd-l2-agb.log.

Latexmk: Missing input file 'atbd-l2-agb.toc' (or dependence on it) from following:
  No file atbd-l2-agb.toc.
Latexmk: Missing input file 'atbd-l2-agb.ind' (or dependence on it) from following:
  No file atbd-l2-agb.ind.
Collected error summary (may duplicate other messages):
  xelatex: Command for 'xelatex' gave return code 1
      Refer to 'atbd-l2-agb.log' and/or above output for details

make: *** [Makefile:94: atbd-pdf] Error 12
make: Leaving directory '/home/runner/work/BPS/BPS/docs'
Error: Process completed with exit code 2.

Additional context

No response

Pre-submission checklist

• I have searched existing issues and confirmed this is not a duplicate.
• I am running a supported version (a tagged release or the current develop branch).
• I have included enough information for the defect to be reproduced.