dela
5b24eba3c8
- 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
102 lines
4.6 KiB
Markdown
102 lines
4.6 KiB
Markdown
# superderive.sty API
|
||
|
||
```tex
|
||
\documentclass[border=10pt]{standalone}
|
||
\usepackage[cjk]{superderive} % cjk: ctex + fandol (XeLaTeX). en: English meaning-box and sdcol labels.
|
||
```
|
||
|
||
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.
|
||
|
||
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]`.
|