SuperAPI AI Directory

manuscript-typeset

General & other

View repository

Updated 10-16 02:35

About this skill

Manuscript Typeset

A general-purpose typesetting Skill that turns afinalized academic Markdown manuscriptinto submission-ready / publication-preview format. It does not do content writing—content belongs to other Skills; what it does islayout transformation: md → submission docx / submission PDF / publication-preview PDF / clean md, four deliverables, with a fidelity statement, placeholder list, and strip report. After any upstream writing Skill (meta-analysis L12, systematic review, empirical-imrad-writing, etc.) produces a finalized draft, it yields a typeset_request.yaml to invoke it; there are also standalone trigger scenarios ("typeset this manuscript into submission format").

First executable entry point: §4 Input contract (typeset_request.yaml) + §9 CLI. For the complete field schema see references/MANUSCRIPT-INPUT-CONTRACT.md; for the authoritative CLI summary see README.md。


1. Fidelity discipline = the soul of this Skill (read this section first)

The typesetting layer must not alter any number, citation, or claim—not a single one. This is not a promise, it is ascript assertion: before any deliverable is written to disk it must pass fidelity_check—the source (md after strip) and the deliverable (tex with LaTeX macros removed / docx text with XML removed) are compared token by token,two hard gates (exit code 2, that deliverable is not written, the whole run is blocked, no --warn-only):①any number that appears in the deliverable but not in the source → fail—faithful rendering never invents numbers out of thin air (measured EXTRA=0), so anyinjection or alteration(including pure integer counts: number of studies, PRISMA record counts, thousands-separated sample sizes, table cell counts) will inevitably surface; ②any payload number or DOI missing → fail—payload = data-form numeric values (effect size/CI/p value/%/τ²/weight) + label binding relationships (k= / N= / p< …,including relational operators, comparator flips p<.001→p>.001 are also caught) + DOI.Honesty boundary (the only direction not hard-blocked): only "pure deletion" of abare integerlegitimately rearranged by a format layer (reference page numbers / years embedded in DOIs / title counts rendered separately by the engine, where the source has it but the deliverable legitimately omits it) is reported for review rather than hard-blocked—alterations are always blocked; only silent deletion of such bare integers goes to review (see references/FIDELITY-DISCIPLINE.md §2/§4c)。

Typesetting is layout transformation, not content reprocessing. Any "optimization" that involves altering numbers / citations / claims (tweaking a wording in passing, "correcting" a number that looks wrong, automatically translating a sentence) is in every caseoutside the responsibility boundary of this Skill—that is the business of upstream writing/verification Skills. The real-world paradigm in one sentence:"No verified number, citation, or claim was altered." This Skill upgrades it from "relying on the agent's self-discipline + a statement" tomachine-enforced gates, which is the core increment over real-world practice.

Name-value binding boundary (honest, not pretending to cover it): fidelity_check's verbatim comparison naturally covers "the typesetting layer changed a number in the body text"—any change will be caught. But itcan do nothing about 'the input file itself already has a wrong name-value binding': if an upstream table labels "Costa's 0.77" incorrectly as "Abbott et al.", both sides see the same (wrong) binding and the equality check passes it. This kind of "data matched to the wrong name" isa third category of check beyond layout checking and number comparison, beyond the responsibility of the typesetting layer. Whenever a deliverable contains study name↔value bindings (tables / figure captions), BUILD_NOTES explicitly states this boundary, and it is recommended that upstream / named authors spot-check it (see references/TYPESET-BUILD-NOTES-PATTERN.md)。


2. Triggers and applicable scenarios

2.1 Trigger phrases

English:typeset manuscript、submission-ready manuscript、publication-ready、submission docx / PDF、APA 7 manuscript formatting、reference-docx、apa7 man/jou、camera-ready、strip internal traces。 Chinese: Format md academic manuscripts into submission version / publication version, produce submission docx / PDF, submission typesetting, publication preview, academic typesetting, internal trace stripping, generate submission Word.

2.2 Reverse triggers (not applicable / switch to another Skill)

User scenario Switch to
Writing / revising the content itself (Intro/Method/Results/Discussion wording) Corresponding writing Skill (empirical-imrad-writing / meta-analysis L11 / systematic-review)
Reference verification / fixing DOI / APA formatting academic-ref-check(This Skill consumesits verification artifacts, does not perform verification itself)
forest / funnel / PRISMA / RoB chart rendering meta-analysis built-in ma-plots renderer / ssci-plots
Numbered-citation journals(Vancouver / AMA / NEJM numeric superscript citations) Requires CSL file——deferred to v2, see §5 boundaries
md general conversion to Word (non-academic submission standards) academic-paper-converter and other general conversion Skills

2.3 Positioning: final-manuscript exit + independent entry

  • Final-manuscript exit (primary usage): after the writing Skill completes the final md manuscript (including the reference list verified by SP7), produce typeset_request.yaml to invoke this Skill.Assumed premise = md is finalized, citations are verified——this Skill does not go back and revise content.
  • Independent entry: the user has a finalized md manuscript ("format this one as a submission version"), fill in typeset_request.yamlthemselves (or let this Skill fall back to metadata from the md YAML header) and it can run.

3. Dual engine (each does its own job, single engine not required)

Artifact Engine Description
Submission docx pandoc + reference-apa7.docx APA 7 style tuned once into a committed asset; line numbers via OOXML post-processing (stdlib, no dependency on python-docx)
Submission PDF(apa7 man) XeLaTeX + apa7 class Double spacing + line numbers (lineno) + figures/tables placed at end + CJK 0 missing glyphs
Publication preview PDF(apa7 jou) XeLaTeX + apa7 class Two-column single spacing + \leftheader adaptation + hanging indent 0.18in + wide content \onecolumn placed at end
generic PDF (fallback) XeLaTeX + generic article Single-column submission fallback when there is no apa7 class dependency

Why not pursue a single pandoc engine to produce PDF: apa7's man/jou details——automatic title page, running head, line numbers, de-float end placement structure, CJK unicode-map character-by-character mapping, jou two-column adaptation (leftheader/hang/onecolumn/de-float GRADE table)——cannot be achieved by pandoc's default template. In practice the LaTeX route has been verified to 0 error / 0 missing glyphs / both PDFs compiled successfully, so the dual engine each does its job: docx only goes through pandoc + reference-docx, PDF only goes through LaTeX. docx's CJK and complex table capabilities are weaker than LaTeX, and BUILD_NOTES honestly annotates the quality status of each item.


4. Input contract (authoritative = typeset_request.yaml; G9 wires accordingly)

Upstream produces typeset_request.yaml, declaring:manuscript(body md) / outputs(requested output subset) / template_family(apa7 | generic)/ metadata(bibliographic records, md YAML header fallback) / references(default profile = faithful rendering) / tables(md: pandoc or raw_tex: dual-mode direct-through)/ figures(at the end, order = presentation order)/ strip_rules(optional)/ docx_line_numbers(optional).

field-by-field schema, manuscript.md YAML header conventions, IMRaD heading levels, metadata override rules, see the full text at references/MANUSCRIPT-INPUT-CONTRACT.md(this is the authority for the G9 wiring). Minimum runnable example = scripts/typeset_request.example.yaml(pointing to scripts/tests/fixtures/smoke/ synthetic non-meta-analysis IMRaD manuscript, proving generality).

4.1 Four outputs + attachments

requested outputs subset, each as in §3; additionallythree attachments must be produced every time:

  • BUILD_NOTES.md — fidelity statement + recompile instructions + quality status per item (page count / missing word count / overfull) + name-value binding boundary honesty statement. Template see references/TYPESET-BUILD-NOTES-PATTERN.md。
  • PLACEHOLDERS.md — placeholder list (author / affiliation / funding / corresponding, clearly marked in PDF/docx, for the user to fill in).
  • STRIP_REPORT.md — stripping report (what was stripped / what was kept / why—judgment record retained).

5. Citations: v1 only does the default mode + author-date locked boundary

  • Default mode (the only one v1 supports) = upstream SP7-verified md reference list → faithful rendering: parse md(## 组标题 grouping, e.g. Cited / Included / Excluded, one paragraph per entry) → hanging-indent tex (man 0.5in / jou 0.18in).does not introduce citeproc, does not go through .bib。
  • Rationale (R5-A10, stronger than the blueprint): the risk is not in citeproc formatting itself (it does not change the data), but in the step "SP7-verified APA text → .bib structuring"reconversion without verification—avoiding it = preserving the 0-hallucination chain. The upstream citation ground truth is already in the verified artifact; the typesetting layer has no authority to further process it.
  • author-date locked boundary (honest): default modeonly serves author-date journals (APA family). Submitting tonumbered-style journals (Vancouver / AMA) must use the CSL mode, and at that point the citation text must be re-verified—CSL / .bib general citation mode = v2 ledger V6, explicitly deferred(enabled at the first numbered-style submission need).
  • Root-cause interface wish (additive, does not block v1): handoff to academic-ref-check a wish—at verification timeproduce in sync a verified CSL-JSON sidecar(the verifier already queries CrossRef/OpenAlex, the structured data is at hand, zero-cost to write to disk along the way). Thereafter the CSL mode = a second rendering of the same verified ground truth; the two modes go from a "fidelity vs flexibility" dilemma to "two renderings of the same ground truth".

6. Internal trace stripping (strip)

Before typesetting,all input items (body + references + tables)according to strip_rules.yaml strip internal process traces and produce a stripping report. This is anew problem category:

  • strip:gate codes(SP7 §3c / SP7 open item), internal corpus ID (papersearchpro-1628, directly causing overfull hbox), process top note (L11 integrated final draft)。
  • keep: methodological disclosure (the SP1–SP7 sign-off gates in Method is an intentional supervision process disclosure)—the strip rules are precise enough to distinguish, and the judgment goes into the stripping report for the record.
  • safety assertion: strip can only delete configured trace patterns; a deleted span must not contain any digit / citation token(strip_traces self-check, violation exit 2).
  • Note: sample traces are often inreferences and tablesrather than the main text (SP7 §3c in References,papersearchpro-1628 in the Table 1 ID column)—strip scope = all typeset input files, don't just grep the main text.

strip_rules missing → identity copy + report states "not configured" (non-blocking). Rule schema see references/STRIP-RULES-SPEC.md(Lane C)。


7. Exit code contract (unified across all scripts)

Code Meaning
0 Success (all requested outputs built + fidelity all green)
1 Input / contract error (request missing fields / file missing / hard dependency missing and no fallback)—hard fail
2 fidelity assertion failure or strip safety violation(number / citation / claim change)—iron rule, no --warn-only, must block, do not emit that artifact
3 Empty (no main text to typeset)

Dependency fallback (honest): missing xelatex → fall back to docx + md two artifacts(requested PDF artifact marked skipped, stderr WARN + BUILD_NOTES declaration, overall exit 0); missing pandoc → not even docx can be produced → exit 1.fidelity failure never falls back(code 2 hard block). See §8 + README for details.


8. Dependency honesty (aligned with G10 doctor)

  • User runtime hard dependencies:pandoc(required for docx),xelatex(TinyTeX, required for PDF),python3 + pyyaml。
  • Not dependent python-docx / lxml: reference-apa7.docx is a committed binary asset; docx line-number injection uses stdlib zipfile+xml。make_reference_docx.py uses python-docx only dev-time(when regenerating assets), users don't need it.
  • Fonts: Times New Roman (main) / Songti SC 宋体 (CJK) / Heiti SC (CJK sans)—bundled with macOS; missing-font detection + fallback notes see README + BUILD_NOTES.
  • Detection:typeset.py checks at startup shutil.which('pandoc'/'xelatex'), based on which it decides whether to fall back (see §7). Authoritative summary of fallback paths see README.md。

9. CLI overview (authoritative signature see README)

Orchestrator typeset.py reads request → strip_traces(all input files) → for each requested engine runs build_pdf / build_docx → for each artifact runs fidelity_check(source=stripped input, rendered=that artifact) → only emits that artifact if all green; any fidelity fail (code 2) → that artifact not emitted + overall exit 2 + report. Produces BUILD_NOTES / PLACEHOLDERS / STRIP_REPORT.

Four underlying scripts (build_pdf.py / build_docx.py / strip_traces.py / fidelity_check.py) + orchestrator typeset.py 'scomplete CLI signatures, parameters, machine-readable summary JSON, exit codes, authoritative summary see README.md。


10. Boundaries and template family (no over-engineering)

  • Template family v1 = apa7(man + jou)+ generic. APA 7 covers the main battlefield of psychology / social science, enough for the first version.
  • scripts/templates/<family>/ keep onlyempty slots(Elsevier / two-column conference proceedings etc.)—add later based on real demand = v2, no pre-filling.
  • No automatic translation: table localization (e.g. Chinese GRADE table → English) = upstream provides an already-localized version, goes through raw_tex: passthrough, this Skill absolutely never self-translates (violates fidelity).
  • CSL / .bib generic citation profiles, numbered-style journals, non-APA journal families = v2 deferred (§5 / §10 V6).

11. File organization

manuscript-typeset/
├── SKILL.md                              本文件:触发 / 忠实性纪律 / 输入契约 / 双引擎 / 边界
├── README.md                             CLI 签名权威 + 依赖探测 + 降级路径 + 目录导览
├── LICENSE                               dual: PolyForm-NC 1.0.0 (code) + CC BY-NC-SA 4.0 (docs)
├── references/
│   ├── MANUSCRIPT-INPUT-CONTRACT.md      输入契约全文(G9 接线权威)
│   ├── TYPESET-BUILD-NOTES-PATTERN.md    BUILD_NOTES / 占位符 / 忠实性声明 / 名值边界 模板
│   ├── FIDELITY-DISCIPLINE.md            铁律 + 断言覆盖边界(Lane C)
│   └── STRIP-RULES-SPEC.md               strip_rules schema + 剥离报告格式(Lane C)
└── scripts/
    ├── typeset.py                        编排器(读 request → strip → 引擎 → fidelity gate → 四件+附件)
    ├── build_pdf.py / build_docx.py      PDF / docx 引擎
    ├── strip_traces.py / fidelity_check.py   剥离 + 忠实性门
    ├── typeset_request.example.yaml      最小可跑样例(指向合成非 MA 稿)
    ├── assets/tex/                        preamble-common / unicode-map / apa7-man/jou/generic 模板
    ├── assets/docx/reference-apa7.docx    APA7 样式 reference-docx(committed 资产)
    ├── templates/<family>/                v2 期刊族槽位(空)
    └── tests/                             各引擎回归 + fixtures/smoke 非 MA 冒烟稿