SuperDerive/references/api.md

superderive.sty API

\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

\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.

\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

\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].