feat: fill test coverage gaps + fix \sdcol i18n labels
- examples/subst-chain.tex: substitution walkthrough with \sdbox/\sdsubst/\sdstep - examples/antipatterns.tex: four compile-clean-but-teach-false figures - tests/invalid/step-outside-row.tex, empty-row.tex, undeclared-role.tex, two-contrast-pkg.tex: negative fixtures for package-level warnings - test.sh: add tests/invalid/ loop - build.sh: allow superderive-build: allow directive to suppress intentional warnings in antipatterns galleries - superderive.sty: \sdcol respects [en] option for illegal/legal labels - references/api.md: complete rewrite, all ~12 macros documented
This commit is contained in:
dela
+98
-4
@@ -1,7 +1,101 @@
|
||||
# API
|
||||
# superderive.sty API
|
||||
|
||||
`\usepackage[cjk]{superderive}` or `[en]`.
|
||||
```tex
|
||||
\documentclass[border=10pt]{standalone}
|
||||
\usepackage[cjk]{superderive} % cjk: ctex + fandol (XeLaTeX). en: English meaning-box and sdcol labels.
|
||||
```
|
||||
|
||||
Layout: `\sdstage{n}{text}` `\sdrow[height]{name}` … `\sdrowend` `\sdbbox{all}` `\sdtopformula{F}{math}`.
|
||||
Build with `./scripts/build.sh fig.tex` — it puts `assets/` on `TEXINPUTS`, so the package
|
||||
does not need to be installed into your texmf tree.
|
||||
|
||||
Call `\sdtopformula` after the last `\sdrowend`.
|
||||
The build first runs `scripts/lint.py`. It rejects raw TikZ drawing, a formula placed
|
||||
before the last row, more than one `\sdcol` contrast pair, and more than four active hue
|
||||
families in the figure. Intentional galleries/tests may put
|
||||
`% superderive-lint: allow-raw-tikz` near the top; do not add an exemption to a
|
||||
deliverable merely to make it pass.
|
||||
|
||||
## Ledgers
|
||||
|
||||
```tex
|
||||
\sdsetrole{keep}{sdTeal} % role -> color. Macros take a ROLE, never a color.
|
||||
\sdsetlabels{Idea}{Rewrite}{Caveat} % override the three meaning-box rail labels
|
||||
```
|
||||
|
||||
Colors: `sdTeal sdOrange sdCoral sdViolet sdGray sdInk`. An unknown role falls back to
|
||||
gray **and emits a package warning**, which `build.sh` turns into a failed build.
|
||||
Redeclaring a role with the same value is harmless; changing its value emits a warning
|
||||
and keeps the original mapping.
|
||||
|
||||
## Flow layout
|
||||
|
||||
**This is the default.** `\sdrow` opens a band, every object inside is placed at the
|
||||
cursor, `\sdrowend` closes it. Hand-written offsets are the main source of layout bugs.
|
||||
|
||||
```tex
|
||||
\sdstage{D1}{stage heading} % on the left rail, below the previous band
|
||||
\sdrow[16mm]{R1} % open a band; height default is 16mm
|
||||
\sdbox[role=keep]{x}{$u$} % existing term, kept as-is
|
||||
\sdsubst[role=live]{s1}{$u$}{$x^2$} % from->to with a strike on the from
|
||||
\sdstep[role=rewrite]{s2}{QK^\top}{QK^\top/\sqrt{d_k}} % lhs -> rhs
|
||||
\sdreason{s1}{§3.2.1} % justification note, anchored to s1
|
||||
\sdrowend % fit the band
|
||||
```
|
||||
|
||||
| macro | does |
|
||||
|---|---|
|
||||
| `\sdstage{name}{text}` | stage heading on the left rail, below all ink so far |
|
||||
| `\sdrow[height]{name}` | open a band; optional height defaults to 16mm |
|
||||
| `\sdrowend` | `fit` the band, warn if empty, close it |
|
||||
| `\sdstep[keys]{name}{lhs}{rhs}` | one rewrite step: two term boxes with an arrow |
|
||||
| `\sdcancel[keys]{name}{math}` | one term, struck through |
|
||||
| `\sdsubst[keys]{name}{from}{to}` | from-term struck through, to-term in role hue |
|
||||
| `\sdbox[keys]{name}{math}` | plain term, no arrow, no strike |
|
||||
| `\sdreason{step-name}{text}` | justification note anchored to a named step |
|
||||
| `\sdcol{name}{illegal}{legal}` | one contrast pair per figure — second is a warning |
|
||||
| `\sdbbox{all}` | everything drawn so far, as one node, for `\sdmeaningbox` |
|
||||
| `\sdtopformula{F}{math}` | the claim line, centered on what was actually drawn |
|
||||
| `\sdtrack{node}` | fold a hand-placed node into the bbox and the vertical cursor |
|
||||
| `\sdvgap{4mm}` / `\sdgap{4mm}` | one-off extra space, vertical / horizontal |
|
||||
| `\sdleftrail{x}` / `\sdlayoutreset` | move the rail / start over |
|
||||
|
||||
### Keys for step/cancel/subst/box
|
||||
|
||||
| key | default | meaning |
|
||||
|---|---|---|
|
||||
| `role=` | `rewrite` for step/subst, `cancel` for cancel, `keep` for box | hue, via `\sdsetrole` |
|
||||
| `level=` | `2` | lightness level 0–3 for the fill |
|
||||
| `gap=` | `\sdgutter` | space *before* this object; `gap=0pt` = exactly adjacent |
|
||||
|
||||
Authors can declare their own roles: `\sdsetrole{live}{sdTeal}`.
|
||||
|
||||
## Contrast column
|
||||
|
||||
`\sdcol{name}{illegal}{legal}` draws two boxes side by side: the left in `sdCoral!30`
|
||||
struck, labelled **illegal** (or **非法** in `[cjk]` mode — never both); the right in
|
||||
`sdTeal!30`, labelled **legal** (or **合法**). The budget is **one per figure**; a second
|
||||
`\sdcol` triggers a package warning → build failure.
|
||||
|
||||
## Bottom
|
||||
|
||||
```tex
|
||||
\sdbbox{all}
|
||||
\sdtopformula{F}{$\mathrm{Attention}(Q,K,V)=\mathrm{softmax}(QK^\top/\sqrt{d_k})V$}
|
||||
\sdmeaningbox{mb}{120mm}{all}{Idea text}{Rewrite text}{Caveat text}
|
||||
\sdsignature{scaled-dot-product attention}{mb} % optional
|
||||
```
|
||||
|
||||
Arg 2 of `\sdmeaningbox` is the total box width; arg 3 is the node it hangs below.
|
||||
Arg 4/5/6 are the three rail rows; an empty `{}` row is dropped.
|
||||
|
||||
`\sdsignature` renders only its subject; it has no author or handle mechanism. Its node
|
||||
is named `(#2-sig)` from the anchor.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `\sdrow`, `\sdrowend`, `\sdstage` must appear outside any other flow object.
|
||||
- A band that overflows its declared height triggers `Package superderive Warning` →
|
||||
build failure.
|
||||
- `\sdcheckrole` never redefines an existing role. Use `\sdsetrole{name}{newColor}`
|
||||
to change the mapping for subsequent figures in the same document.
|
||||
- `\sdcol` labels are **not** customizable via `\sdsetlabels` — they depend only on the
|
||||
package option `[en]`/`[cjk]`.
|
||||
|
||||
Reference in New Issue
Block a user