Skip to content

scdenney/open-science-skills / plugin/skills/paper-tex

paper-tex

Verified

Typesets a working paper or journal submission in house-style LaTeX from Markdown, Word (.docx), TeX, ODT, RTF, or HTML. Converts with pandoc, wraps the body in an EB Garamond template, builds the PDF with latexmk, and sets journal-specific spacing, page limits, anonymization, disclosures, and citation style. Use to format or convert a paper to LaTeX, make a working paper, or prepare a submission to a named journal.

FileKindSize
SKILL.mdskill md14.0 KB
assets/main.template.texother731 B
assets/preamble.texother3.5 KB
assets/si.template.texother759 B
scripts/format_paper.pyexecutablescript12.4 KB

scripts/format_paper.py

View on GitHub
#!/usr/bin/env python3
r"""
format_paper.py — turn a draft in any common format into a house-style working
paper (or journal submission) in LaTeX, and optionally build the PDF.

Pipeline:  INPUT (.md/.docx/.odt/.rtf/.html/.tex)
              -> pandoc -> LaTeX body
              -> wrapped in the house template (assets/) with the EB Garamond
                 preamble, single-spaced title block, intro on its own page,
                 \figcap caption macro, [H] float placement
              -> latexmk -> PDF
              -> latexmk/bibtex byproducts removed (--keep-aux to keep them)

The driver does the mechanical 80%. The house-specific finishing (upgrading
\caption to \figcap with a real note, disclosure sections, SI cross-refs) is
done by hand afterward — see the skill's SKILL.md.

Examples
--------
  # Markdown draft -> single-spaced submission PDF, intro on its own page
  python3 format_paper.py draft.md --out build --title "My Paper" \
      --author "Jane Doe" --abstract "We show ..." --keywords "a; b; c" --build

  # Anonymous submission (blank author), double-spaced, intro on the cover page
  python3 format_paper.py draft.docx --out build --anon --spacing double \
      --cover-page --build

  # Main text + SI together (SI gets SI-A/figure numbering and an xr cross-ref)
  python3 format_paper.py main.md --si si.md --out build --build

The bibliography (`references.bib` by default) and any figures the draft
references by a relative path are copied into the out dir automatically when
they sit next to the input; docx/odt media are extracted there too.
"""
from __future__ import annotations

import argparse
import re
import shutil
import subprocess
import sys
from pathlib import Path

ASSETS = Path(__file__).resolve().parents[1] / "assets"
PANDOC_FMT = {
    ".md": "markdown", ".markdown": "markdown", ".txt": "markdown",
    ".docx": "docx", ".odt": "odt", ".rtf": "rtf",
    ".html": "html", ".htm": "html", ".org": "org", ".rst": "rst",
}
# latexmk/bibtex byproducts removed after a successful build (see clean_aux).
AUX_EXTS = ("aux", "bbl", "blg", "fdb_latexmk", "fls", "log", "out", "toc",
            "lof", "lot", "nav", "snm", "vrb", "bcf", "run.xml",
            "synctex.gz", "xdv", "spl")


def run(cmd: list[str], **kw) -> subprocess.CompletedProcess:
    return subprocess.run(cmd, check=True, text=True, capture_output=True, **kw)


def need(tool: str) -> None:
    if shutil.which(tool) is None:
        sys.exit(f"error: required tool not found on PATH: {tool}")


def to_latex_body(src: Path, out_dir: Path, body_name: str) -> None:
    """Convert any supported source to a LaTeX body fragment at out_dir/body_name.
    Pandoc runs with cwd=out_dir so extracted-media paths resolve at build time."""
    out_body = out_dir / body_name
    ext = src.suffix.lower()
    if ext == ".tex":
        text = src.read_text(encoding="utf-8")
        if "\\begin{document}" in text:
            body = text.split("\\begin{document}", 1)[1].rsplit("\\end{document}", 1)[0]
            for pat in (r"\\maketitle", r"\\begin\{abstract\}.*?\\end\{abstract\}",
                        r"\\bibliography\{[^}]*\}", r"\\bibliographystyle\{[^}]*\}",
                        r"\\thispagestyle\{[^}]*\}"):
                body = re.sub(pat, "", body, flags=re.DOTALL)
            print("note: extracted body from a full .tex document")
        else:
            body = text
        out_body.write_text(body, encoding="utf-8")
        return
    fmt = PANDOC_FMT.get(ext)
    if fmt is None:
        sys.exit(f"error: unsupported input extension {ext!r}. "
                 f"Supported: {', '.join(sorted(PANDOC_FMT))}, .tex")
    need("pandoc")
    cmd = ["pandoc", str(src.resolve()), "-f", fmt, "-t", "latex", "--natbib",
           "--wrap=preserve", "-o", body_name]
    if fmt in ("docx", "odt"):
        cmd += ["--extract-media=media"]   # relative to out_dir
    run(cmd, cwd=out_dir)


def here_floats(body_path: Path) -> None:
    """Pin figures and tables exactly where written ([H])."""
    t = body_path.read_text(encoding="utf-8")
    t = re.sub(r"\\begin\{figure\}(?!\[)", r"\\begin{figure}[H]", t)
    t = re.sub(r"\\begin\{table\}(?!\[)", r"\\begin{table}[H]", t)
    body_path.write_text(t, encoding="utf-8")


def stage_local_graphics(body_path: Path, src_dir: Path, out_dir: Path) -> None:
    """Copy figures the body references by a relative path (next to the source)."""
    t = body_path.read_text(encoding="utf-8")
    for m in re.finditer(r"\\includegraphics(?:\[[^\]]*\])?\{([^}]+)\}", t):
        rel = m.group(1)
        if rel.startswith(("/", "media/")) or "media/media" in rel:
            continue
        cand = (src_dir / rel)
        dest = (out_dir / rel)
        if cand.is_file() and not dest.exists():
            dest.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy(cand, dest)
            print(f"staged figure: {rel}")


def fill(template: str, mapping: dict[str, str]) -> str:
    for k, v in mapping.items():
        template = template.replace("{{" + k + "}}", v)
    return template


def copy_bib(bib: str, search_dirs: list[Path], out_dir: Path) -> None:
    if (out_dir / f"{bib}.bib").exists():
        return
    for d in search_dirs:
        cand = d / f"{bib}.bib"
        if cand.is_file():
            shutil.copy(cand, out_dir / f"{bib}.bib")
            print(f"staged bibliography: {cand}")
            return


def build(out: Path, stem: str, engine: str) -> bool:
    need("latexmk")
    pdf_engine = "-pdfxe" if engine == "xelatex" else "-pdf"
    try:
        run(["latexmk", pdf_engine, "-bibtex", "-interaction=nonstopmode",
             "-halt-on-error", f"{stem}.tex"], cwd=out)
    except subprocess.CalledProcessError:
        # bibtex-class failures (a missing .bib, an unresolvable entry) report in
        # {stem}.blg, not {stem}.log — scanning only the .log printed an empty
        # diagnostic on the single most common real failure.
        errs: list[str] = []
        sources = [out / f"{stem}.log", out / f"{stem}.blg"]
        for src in sources:
            if not src.exists():
                continue
            errs += [f"{src.name}: {ln}" for ln in src.read_text(errors="ignore").splitlines()
                     if ln.startswith("! ") or "Error" in ln or "not found" in ln
                     or "couldn't open" in ln or "I found no" in ln]
        tail = "\n".join(errs[:8])
        seen = ", ".join(str(s) for s in sources if s.exists()) or "no log files"
        pdf = out / f"{stem}.pdf"
        if pdf.exists():
            # latexmk exited nonzero but produced a PDF — warn, do not fail the run.
            print(f"BUILD WARNING for {stem}.tex (PDF was still produced at {pdf}):\n"
                  f"{tail or '(see ' + seen + ')'}", file=sys.stderr)
            return True
        print(f"BUILD FAILED for {stem}.tex:\n{tail or '(see ' + seen + ')'}", file=sys.stderr)
        return False
    pdf = out / f"{stem}.pdf"
    pages = "?"
    if shutil.which("pdfinfo"):
        m = re.search(r"^Pages:\s+(\d+)", run(["pdfinfo", str(pdf)]).stdout, re.MULTILINE)
        pages = m.group(1) if m else "?"
    print(f"built {pdf}  ({pages} pages)")
    return True


def clean_aux(out: Path, stems: list[str], keep: tuple[str, ...] = ()) -> None:
    """Remove latexmk/bibtex byproducts so the out dir holds only sources,
    staged assets, and PDFs. With an SI, si.aux is kept (passed via `keep`):
    xr-hyper reads it to resolve SI cross-refs when main is rebuilt by hand."""
    removed = 0
    for stem in stems:
        for ext in AUX_EXTS:
            f = out / f"{stem}.{ext}"
            if f.name not in keep and f.exists():
                f.unlink()
                removed += 1
    if removed:
        kept = f" (kept {', '.join(keep)} for SI cross-refs)" if keep else ""
        print(f"cleaned {removed} LaTeX build artifacts{kept}; pass --keep-aux to keep them")


def main() -> None:
    ap = argparse.ArgumentParser(description="Format a draft as a house-style LaTeX paper.")
    ap.add_argument("input", type=Path, nargs="?", help="draft: .md/.docx/.odt/.rtf/.html/.tex")
    ap.add_argument("--out", type=Path, required=True, help="output directory")
    ap.add_argument("--si", type=Path, help="supplementary-information source (same formats)")
    ap.add_argument("--title", default="TITLE")
    ap.add_argument("--author", default="")
    ap.add_argument("--abstract", default="")
    ap.add_argument("--keywords", default="")
    ap.add_argument("--date", default="\\today")
    ap.add_argument("--spacing", choices=["single", "double"], default="single",
                    help="body spacing (the title block is always single)")
    ap.add_argument("--anon", action="store_true", help="blank the author (double-anonymous)")
    ap.add_argument("--cover-page", action="store_true",
                    help="keep the intro on the title page (default: intro starts on its own page)")
    ap.add_argument("--bib", default="references", help="bibliography base name (no .bib)")
    ap.add_argument("--no-here-floats", action="store_true", help="do not inject [H] on floats")
    ap.add_argument("--engine", choices=["pdflatex", "xelatex"], default="pdflatex")
    ap.add_argument("--build", action="store_true", help="run latexmk after writing the .tex")
    ap.add_argument("--keep-aux", action="store_true",
                    help="keep latexmk byproducts (.aux/.log/.fls/...) after a successful build")
    ap.add_argument("--clean", action="store_true",
                    help="remove latexmk byproducts from --out and exit (run after hand rebuilds)")
    args = ap.parse_args()

    out: Path = args.out
    if args.clean:
        if not out.is_dir():
            sys.exit(f"error: --out directory not found: {out}")
        stems = sorted({p.stem for p in out.glob("*.tex")}) or ["main", "si"]
        clean_aux(out, stems)
        return
    if args.input is None:
        ap.error("input is required (or pass --clean to tidy an existing --out directory)")
    out.mkdir(parents=True, exist_ok=True)
    shutil.copy(ASSETS / "preamble.tex", out / "preamble.tex")
    src_dir = args.input.resolve().parent

    # --- main body ---
    to_latex_body(args.input, out, "body.tex")
    body = out / "body.tex"
    if not args.no_here_floats:
        here_floats(body)
    stage_local_graphics(body, src_dir, out)

    spacing = "\\singlespacing" if args.spacing == "single" else "\\doublespacing"
    titlebreak = "" if args.cover_page else "\\newpage"
    externaldoc = "\\externaldocument{si}" if args.si else ""
    main_tex = fill((ASSETS / "main.template.tex").read_text(encoding="utf-8"), {
        "TITLE": args.title, "AUTHOR": "" if args.anon else args.author, "DATE": args.date,
        "ABSTRACT": args.abstract, "KEYWORDS": args.keywords, "SPACING": spacing,
        "TITLEBREAK": titlebreak, "EXTERNALDOC": externaldoc, "BODYFILE": "body",
        "DISCLOSURES": "", "BIB": args.bib,
    })
    (out / "main.tex").write_text(main_tex, encoding="utf-8")
    print(f"wrote {out/'main.tex'} and {body}")

    # --- optional SI ---
    if args.si:
        to_latex_body(args.si, out, "si_body.tex")
        si_body = out / "si_body.tex"
        if not args.no_here_floats:
            here_floats(si_body)
        stage_local_graphics(si_body, args.si.resolve().parent, out)
        si_tex = fill((ASSETS / "si.template.tex").read_text(encoding="utf-8"), {
            "TITLE": args.title, "AUTHOR": "" if args.anon else args.author,
            "DATE": args.date, "BODYFILE": "si_body", "BIB": args.bib,
        })
        (out / "si.tex").write_text(si_tex, encoding="utf-8")
        print(f"wrote {out/'si.tex'} and {si_body}")

    copy_bib(args.bib, [src_dir, Path.cwd()], out)

    if args.build:
        # SI first: main's \externaldocument{si} reads si.aux, so SI cross-refs
        # resolve on main's first build instead of printing ??.
        ok = build(out, "si", args.engine) if args.si else True
        ok = build(out, "main", args.engine) and ok
        if not ok:
            sys.exit(1)   # keep the .log files for diagnosis
        if not args.keep_aux:
            stems = ["main"] + (["si"] if args.si else [])
            clean_aux(out, stems, keep=("si.aux",) if args.si else ())

    print("\nnext (house-finishing by hand — see SKILL.md):")
    print("  - upgrade each \\caption{...} to \\figcap{title}{note}; put CI/N/source in the note")
    print("  - add disclosure \\section*{Data availability}/{Ethics}/{Funding} as full sentences")
    print("  - thread SI cross-references; remove any bold-period run-in subheaders")


if __name__ == "__main__":
    main()
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall