dela
db5598fbf7
Standalone LaTeX/TikZ skill for non-tensor paper figures: node/edge macros, lint-on-warning build, golden examples, and negative fixtures.
87 lines
3.2 KiB
Markdown
87 lines
3.2 KiB
Markdown
# superfig
|
|
|
|
A paper-figure toolkit for non-tensor diagrams: a LaTeX/TikZ macro package, a
|
|
build pipeline that fails on silent corruption, worked examples, and an agent
|
|
skill that ties them together.
|
|
|
|
It is the generic-node sibling of `supertensor`. Same house style, same
|
|
role/cursor/warning discipline. The primitives are nodes, edges and groups,
|
|
not tensor faces. Use `supertensor` when axis lengths and shape identities
|
|
are the claim.
|
|
|
|
This repository is a **child** of SuperPaper, the family parent that
|
|
routes paper notes to the right figure toolkit. Clone SuperPaper with
|
|
`--recurse-submodules` for the whole family; use this directory alone
|
|
when you only need node/edge figures.
|
|
|
|
```
|
|
SKILL.md the skill entry point (lean; loads references on demand)
|
|
references/ grammar, layout, style, api, checklist, antipatterns
|
|
assets/superfig.sty the macro package
|
|
scripts/preflight.sh is the TikZ + CJK path available?
|
|
scripts/lint.py reject source-level invariant escapes
|
|
scripts/build.sh lint, compile, audit the log, export pdf/svg/png/thumb
|
|
scripts/test.sh positive examples plus negative package/lint fixtures
|
|
examples/ four golden examples + an anti-pattern gallery
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
./scripts/preflight.sh # 0 = full path, 1 = degraded, 2 = no LaTeX
|
|
./scripts/build.sh examples/pipeline.tex # -> examples/build/pipeline.{pdf,svg,png}
|
|
./scripts/test.sh
|
|
```
|
|
|
|
A minimal figure:
|
|
|
|
```tex
|
|
\documentclass[border=10pt]{standalone}
|
|
\usepackage[cjk]{superfig}
|
|
|
|
\sfsetrole{input}{sfTeal}
|
|
\sfsetrole{model}{sfOrange}
|
|
|
|
\begin{document}\begin{tikzpicture}
|
|
\sfstage{S}{one band, placed by cursor}
|
|
\sfrow{R1}{14mm}
|
|
\sfnode[role=input]{x}{输入 $x$}{16mm}{12mm}
|
|
\sfconn{e1}{预处理}
|
|
\sfnode[role=model]{f}{模型 $f_\theta$}{18mm}{12mm}
|
|
\sfrowend
|
|
\sflane{R1}
|
|
\sfcaption{x}{$x$}{原始输入}
|
|
\sfcaption{f}{$f_\theta$}{可学习参数}
|
|
\end{tikzpicture}\end{document}
|
|
```
|
|
|
|
See `references/api.md` for the full macro list.
|
|
|
|
## Examples
|
|
|
|
| file | shows |
|
|
|---|---|
|
|
| `pipeline.tex` | cursor flow; loss as a side object, not a station on the forward path |
|
|
| `branch-architecture.tex` | residual skip; a group captioned on the shared lane |
|
|
| `state-flow.tex` | time/state step; one `\sfcallout` on a finished band |
|
|
| `dependency-graph.tex` | dual-encoder join, fusion placed from existing anchors |
|
|
| `antipatterns.tex` | four figures that compile cleanly and still teach something false |
|
|
|
|
## Using it as an agent skill
|
|
|
|
`SKILL.md` is the entry point; the `references/` files are loaded on demand.
|
|
Point your agent runtime at this directory. The skill assumes `scripts/` and
|
|
`assets/` sit beside it.
|
|
|
|
## Why the build script fails on warnings
|
|
|
|
`Missing character` drops a CJK glyph silently. `Overfull \hbox` lets a label
|
|
escape its lane. `Package superfig Warning` is an undeclared role, a
|
|
single-member group, a band overflow, a second callout, or a callout hanging
|
|
off a node. `build.sh` greps for all of them and exits non-zero.
|
|
|
|
A clean build also proves the source avoided raw TikZ drawing, a formula
|
|
placed before the last row, and more than four active hues. It still cannot
|
|
prove that the relationships are right; that is what `references/checklist.md`
|
|
is for.
|