From 9b8019701566b5f9dbeccd55bdf76e9f0aa7313b Mon Sep 17 00:00:00 2001 From: Kevin Raymond Date: Thu, 12 Nov 2026 21:58:12 -0600 Subject: [PATCH] Docs: say where prumo does what existing tools do The README's Related tools now names the tool for each thing prumo does that another tool already does, and then says what differs. It adds SaTeX, DEPP and pdffonts, and a Built on list. docs/02-prior-art.md has the same list, rows for SaTeX, DEPP, Joseph Wright's script, texdepend, texdeps and the TeX.SE per-page timer, and the tex-live thread of April 2024. Its gaps are dated facts now, without verdicts, and docs/06 got the same pass. The README says what the byte-identical test does. CLAUDE.md no longer calls texprof pdfTeX. docs/08 records the candidates from the review, with no defaults. --- CLAUDE.md | 12 ++- README.md | 79 +++++++++++++++--- docs/02-prior-art.md | 123 +++++++++++++++++++++------- docs/06-unused-packages.md | 14 +++- docs/08-open-questions.md | 19 +++++ docs/STATUS.md | 163 +++++++------------------------------ 6 files changed, 233 insertions(+), 177 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e4b417b..69b059b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,7 +65,17 @@ else, pick the simplest thing that passes the fixtures and note the choice in th ## Don't reinvent -- Per-macro profiling → point at `texprof` (TeX Live, pdfTeX only). prumo stays at package/file/page. +- Per-macro profiling → point at `texprof` (TeX Live's `hitex` package). It is its own engine + (TeX + e-TeX + Prote) and writes DVI, so it measures itself, not pdfTeX, XeTeX or LuaTeX. + prumo stays at package/file/page. +- Static checks without a build (unused definitions, preamble cost) → `SaTeX`. prumo measures + a real build. +- Package lookup by file, command or environment name → `texfindpkg`. `packages` starts from a + build, not from names. +- A `DEPENDS.txt` for minimal installs → `DEPP` (Island of TeX) writes one from a `file/before` + hook. Read it before giving `packages` a dependency-file output. +- Precompiled preambles, draft mode, TikZ externalization → `mylatexformat`, `-draftmode` (or + `-no-pdf`) and tikz's external library. `whatif` measures them and never reimplements them. - Log parsing for file nesting → read how `texlogsieve` does it before writing a log parser; prumo prefers hook records and uses the log only as a cross-check. - Build orchestration → `latexmk`. prumo wraps it (`-usepretex`, `-jobname`), never replaces it. diff --git a/README.md b/README.md index b3ad77c..7eb8ec8 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ in performance and in optimization, and prumo is how I look inside a LaTeX build instrumented build shows where the time goes, which package loaded which, and what you can drop. +Most of the individual pieces already exist in other tools, and [Related tools](#related-tools) +names them. prumo puts them behind one instrumented build on the stock pdfTeX, XeTeX and +LuaTeX engines. + It has been run on my own corpus and on public documents from an ACM paper to the 7,710-page Stacks Project (see [the benchmarks](docs/benchmarks/README.md)). Please report what breaks! @@ -263,8 +267,12 @@ TEXINPUTS=tex: pdflatex -recorder -jobname=main "\RequirePackage{prumo}\PrumoEnv It only listens to the LaTeX hook management system and writes one event per line to `main.prumo`: files, packages and classes opening and closing, the steps of `\begin{document}` and `\end{document}`, each shipout, and the environments it was asked to -watch. It never changes typesetting: the PDF is byte-identical with and without it, on all -three engines, and that is a test. prumo reads that record, the engine's `-recorder` file list +watch. It never changes typesetting. A test builds each fixture twice, once plain and once +with the probe, and compares the two PDFs byte for byte, with nothing skipped. Both builds run +in the same directory, because LuaTeX's `/ID` depends on the output path, and with +`SOURCE_DATE_EPOCH=0` and `FORCE_SOURCE_DATE=1`, so the dates in the PDF and from `\today` are +fixed. That is eight fixtures, seven of them on all three engines and the fontspec one on +XeTeX. prumo reads that record, the engine's `-recorder` file list (`main.fls`) and the PDF into one model and reports from there. The reference analyzer, `scripts/prumo_report.py`, is the oracle the Rust implementation must @@ -316,19 +324,26 @@ seconds longer; `compare` runs every engine twice for that reason, and the - **Package and page, not macro.** For per-line and per-macro profiling there is `texprof` (below). prumo answers the questions before that one: which package, which file, which page, which environment, which font, which `\usepackage` line. -- **Experiments, not guesses.** "Unused" means the document was rebuilt without the request and +- **Experiments.** "Unused" means the document was rebuilt without the request and nothing observable changed: page count, text, a coarse render. The caveat is printed with it. ## Related tools These are the tools I know of that touch the same questions. Each was installed and run on -TeX Live 2026 (November 2026) before I described it here. +TeX Live 2026 (November 2026) before I described it here, except DEPP, which I have read but +not run. - **texprof and texprofile** (Martin Ruckert, TUGboat 45:2, 2024; in TeX Live, in the `hitex` package). texprof is a TeX engine of its own, Knuth's TeX with e-TeX and Prote, and it writes DVI. It timestamps every command and charges the time to the file and line the command came from, a macro's to where it was defined. texprofile prints the tables and a call graph. +- **SaTeX** (Florian Sihler, Rust, 0.2.2 of November 2026, on crates.io; its README says it is + still work in progress). An abstract interpreter for TeX and LaTeX: it expands macros and + runs primitives, and it does not typeset. `satex lint` has a `preamble-cost` note, an + `unused-package` hint (nothing the package defines is used), and `missing-dependency` and + `unused-dependency` checks against a `DEPENDS.txt`. `--timings` breaks SaTeX's own run down + by phase and file, not the engine's. - **latexpkges3** (Python, on PyPI since 2021, a fork of LaTeXpkges from 2015). Removes each `\usepackage` in the main file's preamble in turn, rebuilds, and compares an MD5 of the output. By design it looks only at the main file's top level. @@ -348,12 +363,44 @@ TeX Live 2026 (November 2026) before I described it here. found" errors name, until the build gets through. - **mkjobtexmf** (Heiko Oberdiek, 2011, in TeX Live). Collects the files one run read, from `-recorder` or strace, into a texmf tree for that job. - -prumo's answers come from hooks on the build you already run, on any of the three engines. -The package graph is what the hooks saw load, not what the source text names. `unused` -compares page count, text and a coarse render, not a checksum or an exit code. The package -list is the files the engine read, mapped through your `texlive.tlpdb`. The installers above -add what is missing; `prune` subtracts what a corpus does not use. +- **DEPP** (Marei Peischl, Island of TeX, 0.4 of January 2026, on GitLab and not yet on CTAN; + not run). A package loaded ahead of the document. On each `file/before` hook it names the + file's TeX Live package from where the file sits in the tree, asks `tlmgr search --file` + through shell-escape for the rest, and writes the list to `DEPENDS.txt` for a minimal Docker + image or a Nix `texlive.withPackages`. Its documentation says it works with LuaLaTeX and + that the other engines are in progress. +- **pdffonts** (Poppler). Lists the fonts in a PDF with their type and encoding, and whether + each one is embedded and subset. + +### Same idea as existing tools + +Where prumo does what one of the tools above already does: + +- `unused`: remove the request, rebuild, compare the output. LaTeXpkges did it in 2015, and + latexpkges3 and stygtfo do it too. SaTeX's `unused-package` asks the same question from its + analysis, without a build. +- `graph`: a package dependency graph with Graphviz output, as latex-dependency-grapher draws. +- `packages`: the files a run read (`-recorder`), mapped to TeX Live packages. mkjobtexmf + collects the same file list. Joseph Wright described the same `.fls`-to-package lookup on + the [tex-live list](https://tug.org/pipermail/tex-live/2024-April/050431.html) in April 2024 + and posted it as a [script on TeX.SE](https://tex.stackexchange.com/a/716373). DEPP builds + its list from a `file/before` hook, as prumo's probe does. +- `prune`: a small install for a set of documents. TinyTeX and texliveonfly get there by + adding, mkjobtexmf by building a per-job tree, and DEPP by writing the list to install. +- `fonts`: the embedded side is pdffonts output. +- `time`: per-page timing with `\pdfelapsedtime` is a known technique, from a + [2014 TeX.SE answer](https://tex.stackexchange.com/a/211572). texprof goes finer, to the line + and the macro. +- `whatif`: a preamble precompiled with mylatexformat, draft mode and TikZ externalization are + existing techniques. prumo only measures them. + +### What differs + +- The answers come from hooks on the build you already run, on any of the three engines. +- The package graph is what the hooks saw load, not what the source text names. +- `unused` compares page count, text and a coarse render, not a checksum or an exit code. +- The package list is the files the engine read, mapped through your `texlive.tlpdb`. +- The installers above add what is missing; `prune` subtracts what a corpus does not use. ### Why not texprof @@ -366,12 +413,22 @@ package of hooks on the engine you already use, so the numbers are your build's, of packages, files, pages and environments. When prumo points at a package and you want to know which of its macros, that is texprof's question. +## Built on + +- The LaTeX hook management system (`\AddToHook`), which the probe listens to. +- expl3's `\sys_timer:`, the timer in every record. +- The engines' `-recorder` file list. +- `texlive.tlpdb`, TeX Live's package database, for `packages` and `prune`. +- The Poppler tools: `pdffonts`, `pdftotext`, `pdftoppm` and `pdfinfo`. +- latexmk, which drives the build with `--latexmk`. +- mylatexformat, for the precompiled preamble in `whatif`. + ## What it will not do - Profile macros. prumo stops at package, file, page and environment; `texprof` goes below that. - Change your build. The probe adds hooks and writes one record file; the PDF is - byte-identical with and without it, and that is a test. + byte-identical with and without it (see [How it works](#how-it-works) for the test). - Touch your files. Builds run on a copy; artifacts go to your cache directory (or whatever `--out` says), nothing next to your document. `prune --apply` is the one destructive command, it re-prints its plan first and needs `--yes`. diff --git a/docs/02-prior-art.md b/docs/02-prior-art.md index d803ba8..50c3825 100644 --- a/docs/02-prior-art.md +++ b/docs/02-prior-art.md @@ -1,9 +1,29 @@ # 02 — Prior art -Survey done 2026-11-06; the tools in A, B, C and E were installed and run on TeX Live 2026 on -2026-11-10 and the rows corrected. Verdict first: none of the six areas has a mature, maintained, -general-purpose tool. Two have narrow, usable prior art (dependency bundling; install-on-demand). -The rest have scripts, building blocks, or abandoned projects. +Survey done 2026-11-06. The tools in A, B, C and E were installed and run on TeX Live 2026 on +2026-11-10 and the rows corrected. SaTeX, DEPP, texdepend, texdeps, two TeX.SE questions and a +tex-live thread were added on 2026-11-12. SaTeX 0.2.2 and pdffonts were run that day; DEPP, +texdepend and texdeps were read but not run. Each gap below is what a +tool did on the date given, as a fact to design around, not a verdict on the tool. + +## Where prumo does the same thing + +- `unused`: remove the request, rebuild, compare the output. LaTeXpkges did it in 2015, and + latexpkges3 and stygtfo do it too (A). SaTeX's `unused-package` lint asks the same question + without a build. +- `graph`: a package dependency graph with Graphviz output, as latex-dependency-grapher draws + (C). +- `packages`: the files a run read (`-recorder`), mapped to TeX Live packages. mkjobtexmf + collects the same file list (E). Joseph Wright described the same `.fls`-to-package lookup + on the tex-live list in April 2024 and posted it as a script on TeX.SE (E, Demand signals). + DEPP builds its list from a `file/before` hook, as prumo's probe does (E). +- `prune`: a small install for a set of documents. TinyTeX and texliveonfly get there by + adding, mkjobtexmf by building a per-job tree, and DEPP by writing the list to install (E). +- `fonts`: the embedded side is pdffonts output (D). +- `time`: per-page timing with `\pdfelapsedtime` is a TeX.SE answer from 2014 (B). texprof + goes finer, to the line and the macro. +- `whatif`: a preamble precompiled with mylatexformat, draft mode and TikZ externalization are + existing techniques. prumo only measures them. ## By area @@ -11,79 +31,96 @@ The rest have scripts, building blocks, or abandoned projects. | Tool | Approach | Gap | |---|---|---| -| LaTeXpkges (bazzilic, 2015) / latexpkges3 (TarasKuzyo fork, PyPI 1.0, 2021) | Remove each top-level `\usepackage`, rebuild twice, compare an MD5 of the output (`.pdf`, `.xdv`, `.dvi`) with `/ID` stripped; `--visual` compares Ghostscript JPEGs | Top-level only (by its own README); the date patterns never match (missing commas in its pattern list), so timestamps trip the hash; `--visual` compares against a deleted directory and calls everything removable (checked 2026-11-10); writes trial files and deletes outputs in the document's directory | -| stygtfo (PyPI 0.1.0, 2022) | Comment out each column-0 `\usepackage` line, rebuild, compare pages with diff-pdf-visually | Tectonic only in practice (its README says so); with ImageMagick 7 identical pages compare as different; overwrites the input without `-o` | -| latex-dependency-grapher v1.0 (Java, CTAN 2024-01) | Regex scan of `\usepackage`/`\RequirePackage`/`\input`/`\include`, kpsewhich, GraphViz; "unused" = comment the line out, pdflatex still exits 0 | No output comparison; pdflatex only; the regex misses `\usepackage[opts]{x}`; no release since 1.0 | +| LaTeXpkges (bazzilic, 2015) / latexpkges3 (TarasKuzyo fork, PyPI 1.0, 2021) | Remove each top-level `\usepackage`, rebuild twice, compare an MD5 of the output (`.pdf`, `.xdv`, `.dvi`) with `/ID` stripped; `--visual` compares Ghostscript JPEGs | Top-level only, by its own README. Checked 2026-11-10: its date patterns never match (missing commas in the pattern list), so timestamps change the hash. `--visual` compares against a directory it has deleted and reports every package removable. It writes trial files and deletes outputs in the document's directory | +| stygtfo (PyPI 0.1.0, 2022) | Comment out each column-0 `\usepackage` line, rebuild, compare pages with diff-pdf-visually | Its README says it was tested with Tectonic only. Checked 2026-11-10: with ImageMagick 7, identical pages compare as different. Without `-o` it overwrites the input | +| latex-dependency-grapher v1.0 (Java, CTAN 2024-01) | Regex scan of `\usepackage`/`\RequirePackage`/`\input`/`\include`, kpsewhich, GraphViz; "unused" = comment the line out, pdflatex still exits 0 | No output comparison; pdflatex only. Checked 2026-11-10: the regex misses `\usepackage[opts]{x}`. No release since 1.0 | +| SaTeX 0.2.2 (Florian Sihler, Rust, 2026-11-12), `unused-package` lint | Static: an abstract interpretation of the document, no build. Fires when every name a loaded package defines is unused | A hint by its own description: side effects (layout, hooks, fonts, `\AtBeginDocument` code) are not seen. Run 2026-11-12 on prumo's basic fixture: no note for xcolor, which prumo's `unused` finds removable | | cmdtrack, refcheck, chklref, checkcites | Find unused *commands*, *labels*, *citations* | Not packages | | texlab, LaTeX Workshop, TeXstudio, LTeX | Editor diagnostics | No unused-package diagnostic | -**Reuse:** nothing to reuse; the idea of "remove and rebuild" is right, the execution is not. -prumo blocks packages at the kernel level (works for class-loaded packages too), seeds candidates -from probe data, and compares page text, not bytes. See `06-unused-packages.md`. +**Same idea:** prumo's `unused` is the remove-and-rebuild experiment LaTeXpkges ran in 2015, +and latexpkges3 and stygtfo run it too. The candidates come from the probe's records, so a +request in the user's own class or package counts as well. The request is deleted from its +loader's source, with blocking as the fallback. The comparison is page count, text and a +render, not bytes. See `06-unused-packages.md`. ### B. Compile-time profiling | Tool | Approach | Gap | |---|---|---| -| **texprof / texprofile** (Ruckert; TUGboat 45:2, 2024; in TeX Live's `hitex` package) | Its own engine (TeX + e-TeX + Prote, DVI output) records time per input line and per macro into `.tprof`; `texprofile` reports by file/line/macro with call-graph data; `-pdf` only stands in pdfTeX primitives when building a format | Not pdfTeX, XeTeX or LuaTeX; TeX Live 2026 ships no texprof formats, and a LaTeX format does not build against the 2026-11-01 kernel (macro stack overflow in expl3-code.tex); not package-oriented | +| **texprof / texprofile** (Ruckert; TUGboat 45:2, 2024; in TeX Live's `hitex` package) | Its own engine (TeX + e-TeX + Prote, DVI output) records time per input line and per macro into `.tprof`; `texprofile` reports by file/line/macro with call-graph data; `-pdf` only stands in pdfTeX primitives when building a format | Not pdfTeX, XeTeX or LuaTeX. TeX Live 2026 ships no texprof formats, and a LaTeX format does not build against the 2026-11-01 kernel (macro stack overflow in expl3-code.tex). Not package-oriented | +| TeX.SE 210139 (2014), Robert's answer 211572 | `\pdfelapsedtime` printed and `\pdfresettimer` called in `\AtBeginDocument` and `\AtBeginShipout`, one `timer:` line per page in the log; a 2020 answer (558409) does the same on LuaLaTeX with `os.clock()` | Added by hand, per page only. The answer itself notes that TeX's asynchronous output routine charges a page with material from the pages around it. `os.clock()` is CPU time, not wall clock | +| SaTeX 0.2.2, `--timings` | Per phase and per file, with token counts, for SaTeX's own interpretation of the document | Measures SaTeX's run, not the engine's ("Both measure the run itself", its README). Run 2026-11-12 on prumo's biblatex fixture: `biblatex.sty` 1,098 ms; the first run built a kernel cache from `latex.ltx` in 55 s | | l3benchmark (`\benchmark:n`, `tic`/`toc`) | expl3 timers you place by hand | Building block | | regstats, scrtime | Whole-run time | No breakdown | | ConTeXt `mtxrun --script profile` | Lua/TeX profiling | ConTeXt only | | latexmk | Build orchestration | No timing beyond `time latexmk` | -**Reuse:** `\sys_timer:` (expl3, all engines) — verified. Point users at texprof for per-macro -work; prumo is the engine-agnostic package/file/page layer above it. Ruckert's article notes that -no profiling tool had been available to macro package authors before texprof — that is the demand -signal. +**Same idea:** per-page timing is the TeX.SE answer's technique. prumo takes it from the +shipout hooks with `\sys_timer:` (expl3, all engines, verified) and adds packages, files and +phases. Point users at texprof for per-macro work; prumo is the engine-agnostic +package/file/page layer above it. Ruckert's article notes that no profiling tool had been +available to macro package authors before texprof, which is the demand signal. ### C. Package dependency graph | Tool | Approach | Gap | |---|---|---| -| latex-dependency-grapher | Regex scan of the source, kpsewhich resolution | Includes conditional loads that never happen (xcolor → colortbl); misses loads written with options or spaces, and class loads | +| latex-dependency-grapher | Regex scan of the source, kpsewhich resolution, Graphviz output | Checked 2026-11-10: includes conditional loads that never happen (xcolor → colortbl); misses loads written with options or spaces, and class loads | +| SaTeX 0.2.2, `--timings` | Prints the tree of files its interpretation read, which file under which | From the interpretation, not a build | | texfindpkg (Lyu, CTAN 2024A, in TeX Live and MiKTeX) | Which package provides a file, command or environment, its dependencies, and `tlmgr`/`miktex` install, from TeXstudio `.cwl` data and the tlpdb | Names in, not a document; the `.cwl` dependency data differs from what a build reads | | snapshot + bundledoc | `\listfiles`-style flat `.dep` list, then archive the files | Flat; no edges | +| texdepend (Friendly, Perl, 0.92), texdeps (Cozens); CTAN, not in TeX Live; not run | Scan the source for `\input`, `\include`, `\usepackage` and `\includegraphics` (texdeps optionally through kpsewhich) and print the files, for make or tar | Source scan; flat | | `\listfiles`, adhocfilelist, inputtrc | Flat lists / traces | No graph | | `-recorder` `.fls` | Every file read/written | Flat; no nesting | | texlogsieve (Lua, 1.6.1, 2026-01) | Rebuilds file nesting from the log's parentheses to filter messages | Does not export the tree; but its parser is the reference for log-based nesting | -**Reuse:** nothing directly; the `package/before` hook plus the depth counter gives exact edges -(verified). Use texlogsieve's approach as the cross-check parser for logs from runs without the -probe. +**Same idea:** latex-dependency-grapher draws the same kind of graph with Graphviz. prumo's +edges come from the `package/before` hook and a depth counter (verified), so they are the +loads that happened. Use texlogsieve's approach as the cross-check parser for logs from runs +without the probe. ### D. Font usage | Tool | Approach | Gap | |---|---|---| -| pdffonts (Poppler) | Lists fonts embedded in the PDF | Only the output side; Type 3 fonts are anonymous (`F44`) | +| pdffonts (Poppler; 26.07.0 run 2026-11-12) | Lists the fonts in the PDF: type, encoding, embedded, subset | Only the output side; Type 3 fonts are anonymous (`F44`) | | tracefnt / `\tracingfonts` | NFSS load/substitution trace in the log | Raw; no report | | pdfTeX log trailer | `<...pfb>` list of embedded Type 1 files | Hand parsing | -**Reuse:** pdffonts as the cross-check. The `.fls` is the better source on pdfTeX: `.tfm` INPUT = -loaded, `.pfb`/`.pk` INPUT = embedded (verified). Nothing links either to the package that caused -the load; prumo can, via the `.fd` file hook context. +**Same idea:** the embedded side of `fonts` is pdffonts output. The `.fls` is the better +source on pdfTeX: `.tfm` INPUT = loaded, `.pfb`/`.pk` INPUT = embedded (verified). Nothing +above links either to the package that caused the load; prumo does, through the `.fd` file +hook context. ### E. Slimming / pruning TeX Live | Tool | Approach | Gap | |---|---|---| | mkjobtexmf (Oberdiek, v0.8, 2011) | Run with `-recorder`/strace, symlink (or `--copy`) the used files into a job-local texmf tree | File level, one job, "experimental" by its own docs | +| DEPP 0.4 (Marei Peischl, Island of TeX, 2026-01-07; GitLab, not on CTAN; read, not run) | A package loaded before the document. A `file/before` hook guesses each file's TeX Live package from its path (`tex///`); `tlmgr search --file` through shell-escape for the rest; fonts through luaotfload, hyphenation patterns from babel or polyglossia. Writes `DEPENDS.txt` | Its documentation: works with LuaLaTeX, other engines in progress. Its README: the list is written at `\begin{document}`, so fonts loaded later are not in it yet. Lists what to install | +| `depreader.lua` (Joseph Wright, TeX.SE answer 716373, 2024-04-24) | Reads the `.fls`, runs `tlmgr search --file /` per file, prints the TeX Live packages and the files with no match | By its own list: only files a TeX run reads (not biber or makeindex), not format files, slow (one `tlmgr` call per file), no tlpdb `depend` edges | | snapshot + bundledoc (Pakin) | Archive a document's dependencies | For archiving, not for an install | | texliveonfly (2011) | Install missing packages via tlmgr while compiling | Add-only | | TinyTeX (Yihui Xie; the installer needs no R, the auto-install is in the R package) | Small TeX Live (about 100 packages by default) + auto-install missing packages from the log | Add-only | -| tlmgr | `scheme-minimal`, `scheme-infraonly`, `remove`, `search --global --file`, pinning, `--usermode` | No "remove what these documents don't use" | +| tlmgr | `scheme-minimal`, `scheme-infraonly`, `remove`, `search --global --file`, `search --json` (since 2024-04, after the thread below; works on TeX Live 2026), pinning, `--usermode` | No "remove what these documents don't use" | | Tectonic bundles | Self-contained bundles; custom bundles from a hand-written spec | No usage-driven subsetting | | MiKTeX | Install on the fly | No pruning | -**Reuse:** `texlive.tlpdb` as the file→package map (it is what `tlmgr search --file` reads). -Everything else only adds or copies. The inverse — subtract what the corpus doesn't use — is new. +**Same idea:** `packages` is the `.fls`-to-package lookup from the tex-live thread, and +mkjobtexmf collects the same file list. prumo reads `texlive.tlpdb` directly (it is what +`tlmgr search --file` reads), so it makes one read, not one `tlmgr` call per file. +`prune`'s `keep.txt` and `install-tl` profile serve the purpose DEPP's `DEPENDS.txt` does. The +tools above add packages, copy files or list what to install. None of them works out what an +installation can remove. ### F. General linters chktex, lacheck, nag, texlogsieve, texlogfilter, texfot, latexindent, TeXtidote, LTeX+, texcount, arara, rubber, latexmk, llmk, texlab: none covers A–E. `nag` warns about *obsolete* packages, which is adjacent and worth linking to in the unused report ("also: nag says this one is -obsolete"). +obsolete"). SaTeX (2026) lints a document by abstract interpretation and covers parts of A, +B and E (above). ## Kernel and distribution capabilities prumo stands on @@ -97,20 +134,46 @@ obsolete"). (XeTeX), and on LuaTeX to `os.gettimeofday()` minus an epoch that l3kernel sets to `gettimeofday() - os.clock()` when its Lua code loads (wall clock; finding 52). Unit: scaled seconds, 1/65536 s. +- **Poppler**: `pdffonts`, `pdftotext`, `pdftoppm`, `pdfinfo`. +- **latexmk** drives multi-pass builds; **mylatexformat** builds `whatif`'s precompiled + preamble. ## Demand signals -- TUGboat 45:2 (2024): texprof article — profiling demand from package authors. -- latex3/latex2e issue #1877 (Oct 2025): "LuaLaTeX is disproportionately slow" — engine - performance is an active topic; a per-package breakdown is the natural next question. +- TUGboat 45:2 (2024): texprof article, profiling demand from package authors. +- latex3/latex2e issue #1877 (Oct 2025): "LuaLaTeX is disproportionately slow". Engine + performance is an active topic, and a per-package breakdown is the natural next question. - LaTeX Workshop issue #2797: user asking which TeX Live packages are "absolutely necessary" because the default install is gigabytes of unneeded packages. +- TeX.SE 210139 (2014-11-02, "how to find bottleneck of long compiling time for my + document"): a 340-page document, and the asker wants "those 20% of the things which might + cause 80% of the compiling time". With the per-page timer, about 20 of the 340 pages took + more than half the time. +- TeX.SE 716306 (2024-04-23, "Automatically determine all ctan packages necessary to + compile") and the tex-live thread "tlmgr search output" that followed (2024-04-24, + messages 050431 to 050441). Joseph Wright started a script that uses `--recorder`, parses + the `.fls` and looks up the TeX Live package for each line. Marei Peischl replied that she + runs `tlmgr search --file` through shell-escape in a container, in a project on the Island + of TeX GitLab. DEPP is her project there, created in January 2024, and it does that. + Norbert Preining said he does this regularly, showed the output of + `tlmgr search --file /article.cls`, and added `tlmgr search --json` that day. Markus Kohm + pointed at texliveonfly. What came of it: Joseph's script as TeX.SE answer 716373, + `tlmgr search --json`, and DEPP, public on GitLab at 0.4. CTAN's package list has nothing + from the script as of 2026-11-12. ## Sources - https://github.com/bazzilic/LaTeXpkges · https://pypi.org/project/latexpkges3 - https://ctan.org/tex-archive/support/latex-dependency-grapher - https://tug.org/TUGboat/tb45-2/tb140ruckert-profiler.html +- https://github.com/EagleoutIce/satex-analyzer (SaTeX; github.com/gigalasr/satex-analyzer + is a fork from 2026-09-26 at 0.1.0) · https://crates.io/crates/satex-analyzer +- https://gitlab.com/islandoftex/texmf/depp +- https://tex.stackexchange.com/questions/210139 · https://tex.stackexchange.com/a/211572 +- https://tex.stackexchange.com/questions/716306 · https://tex.stackexchange.com/a/716373 +- https://tug.org/pipermail/tex-live/2024-April/050431.html (thread start) · + https://tug.org/pipermail/tex-live/2024-April/050436.html (Preining, `tlmgr search --file`) · + https://tug.org/pipermail/tex-live/2024-April/050440.html (`tlmgr search --json`) - https://ctan.org/pkg/texlogsieve - https://ctan.org/tex-archive/support/bundledoc · https://mirrors.mit.edu/CTAN/macros/latex/contrib/snapshot/snapshot.pdf - https://yihui.org/tinytex/ · https://github.com/cran/tinytex diff --git a/docs/06-unused-packages.md b/docs/06-unused-packages.md index 535f95c..09a1eb2 100644 --- a/docs/06-unused-packages.md +++ b/docs/06-unused-packages.md @@ -3,8 +3,16 @@ The question "can I delete this `\usepackage`?" cannot be answered by reading the source, because packages act by side effect (microtype, hyperref, babel, fontenc, geometry), by redefining existing commands (amsmath's `\boldsymbol`, `\eqref`), or by being loaded for a -single option. The honest answer is experimental: remove it, rebuild, see what changes. Prior -tools do that badly (top-level only, hash of PDF bytes). prumo does it properly. +single option. The answer has to come from an experiment: remove it, rebuild, see what +changes. + +Same idea as existing tools: LaTeXpkges did this in 2015, and latexpkges3 and stygtfo do it +too (`02-prior-art.md`, section A). SaTeX's `unused-package` lint asks the same question from +an abstract interpretation, without a build. In prumo the candidates come from the probe's +records, so a request in the user's own class or package counts as well, and the +comparison is page count, text and a render. LaTeXpkges looks only at the main file's top +level and compares an MD5 of the output; stygtfo compares rendered pages and was tested with +Tectonic only, by its README (both checked 2026-11-10). ## Candidates @@ -20,7 +28,7 @@ Skip list, reported as "loaded for side effects — not tested": `fontenc`, `inp `polyglossia`, `fontspec`, `microtype`, `geometry`, `hyperref`, `bookmark`, `lmodern` and other pure font-selection packages, `etoolbox`/`xparse`/`expl3` (kernel-adjacent), `nag`, `showframe`, `layout`, `lipsum`? (no — lipsum is testable). Keep the list short and editable -(`--test-all` overrides it). Hard-coding judgement is a smell; the list exists only because +(`--test-all` overrides it). Hard-coding judgment is a smell; the list exists only because these packages will always "pass" the no-change test while obviously doing something. ## Removing the request (the default since hardening 2) diff --git a/docs/08-open-questions.md b/docs/08-open-questions.md index 7f15e65..d7656a1 100644 --- a/docs/08-open-questions.md +++ b/docs/08-open-questions.md @@ -55,3 +55,22 @@ clearly marked placeholder. will reshape M4/M5. 12. **CTAN upload of the probe.** Yes/no, and whether to name it `prumo.sty` or something generic like `buildprobe.sty` so the CTAN package outlives the tool's name. + +## After launch: candidates from the prior-art review (2026-11-12) + +Recorded only. None of these is planned, and none has a default. + +13. **Per-pass and per-tool timing under latexmk:** pass 1, biber, pass 2, makeindex. Under + latexmk the record file is the last pass's, and there is no finalization phase. +14. **`prumo diff a.json b.json`**, and a budget or exit-code mode for CI. +15. **Opt-in command timing** on the generic `cmd//before` and `cmd//after` hooks. + The kernel implements those hooks by patching the command (`\__hook_patch_command:Nnn`, + ltcmdhooks), which conflicts with CLAUDE.md rules 3 and 5. A conflict to decide, not a + plan. +16. **`packages` on MiKTeX**, where texfindpkg maps names to packages and prumo reports files. + Also `packages` output as a `tlmgr install` line or a `DEPENDS.txt` (DEPP's file). +17. **Trace export:** speedscope or Chrome trace-event JSON. +18. **`unused --pairs`**, already mentioned in `06-unused-packages.md`: removing two packages + together when each one alone passes. + +On 12: texprof (in the `hitex` package) and texfindpkg both ship in TeX Live. diff --git a/docs/STATUS.md b/docs/STATUS.md index 80a4019..9899e63 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,140 +1,39 @@ # Status -## Launch prep (2026-11-09 and 10) - -This round adds a table of where a LaTeX run's time goes, from engine start to the closed -PDF, on each engine. Everything below was measured, and the method is in the repo so anyone -can check it. - -### Probe v0.2 - -- New records: `docstart` (end of `\begin{document}`), `lastpage` (after the final - `\clearpage`), and `env+`/`env-` for the environments named with - `\PrumoEnvironments{...}`. The CLI passes `--env` (default: tikzpicture, axis, tcolorbox, - tblr, longtable, tabularx, minted, lstlisting, forest; `none` for none). A command and not - a package option, because raw option handling changed since the 2021-06 floor. -- `docstart` and `end` go through `\AddToHookNext`, so they come after the code 92 TeX Live - files add to `begindocument/end` (amsmath among them) and after document-level code - (finding 53). -- A `ship` with no `page` is a discarded shipout. The model keeps it apart and the pages - section says so. -- Loaded from the main file's first line (Overleaf), the probe dropped its first event and - recorded its own `pkg-`. Both fixed (finding 56). -- PDF byte-identical with and without the probe on the seven fixtures and three engines, on - TeX Live 2026 and on Ubuntu 22.04's TeX Live 2021 (kernel 2021-11-15). New fixture - `environments` with seven claims, all tested. -- Oracle first: `prumo_report.py` has the phases, environments and discarded shipouts, the - goldens are regenerated, and the Rust matches on all 19 TeX Live 2026 sets. - `make_artifacts.sh` now sets `FORCE_SOURCE_DATE=1`; beamer's `\today` had changed a font - subset from one day to the next. - -### Phases, and how time is measured - -- `time` leads with the phase table (text, `--json` `phases`, `--html`): startup, preamble, - begin-document, typesetting, shipout, end-document, finalization. JSON adds `timer`, - `phases`, `environments` and `discarded_shipouts`; nothing was renamed. -- Finalization is the engine process's wall time minus the last record. `run.json` keeps - `wall_ns`, polled every millisecond (it was 20). Not measured under latexmk. -- The brief said LuaTeX's timer is `os.clock()`. It is not: l3kernel reads - `os.gettimeofday()` and uses `os.clock()` only to place the zero (finding 52). All three - timers are wall clock, and the README says how each is read. -- `compare` has a phases-by-engine table and ranks by wall time. The old total left out - startup and finalization and called LuaLaTeX fastest on a one-line document it was - slowest on (finding 55). With `--runs` 3 or more the median warm run is reported. - -### Benchmarks (`docs/benchmarks/`) - -- Ten documents now, three engines. Three live here (one line, the five-page paper, the - 3,991-page generated book). Seven are fetched at a pinned commit and never stored: the - ACM sigconf sample with BibTeX and with biblatex, the metropolis demo deck, florilegium's - manual, the HoTT book, Open Logic and the 7,710-page Stacks Project. `corpus.toml` has - each one's commit, license, engines and prepare step, `fetch.py` lays them out. kaobook - was left out, because thmtools' `sibling=` fails on the 2026-11-01 kernel, in five lines - too. -- `bench.py` has three modes: the phases (as before), `--overhead` (builds with and without - the probe in turns, plus per-package times from the probed records) and `--whatif`. - `charts.py` draws four SVG charts, light and dark, from the JSON. Color means phase in - all of them, and every pair of colors, the gray included, is checked with the dataviz - validator. -- The probe costs 7 ms on the one-line document and under 6% everywhere. On the paper, - LuaLaTeX's extra preamble time is biblatex (+151 ms) and fontspec's LuaTeX code (67 ms). -- On the corpus, the precompiled preamble works on two of the six pdfLaTeX - documents (paper 49%, deck 25%). Draft pays on XeLaTeX (13 to 38%). Externalize pays on - the deck and florilegium (15 to 32%), but its first run on a long book is a pass per - picture: 93 minutes on Open Logic for 4 s a build. -- The run had seven P-cores busy at once, and its phase numbers came out 0.3 to 5% slower - than the quieter run before it. The README says so. - -### Public documents - -ClassicThesis, the metropolis demo and the Llama 2 paper's arXiv source run through every -report command. kaobook's documentation fails on TeX Live 2026 with or without prumo. What -they changed: a failed build prints its first `!` error, plain output lists the slowest -`--top` pages instead of all of them, and the shipout hint names page and image writing, not -only hooks (finding 58). - -### Release check - -- v0.1.1 has its ten assets. `install.sh` from the README works in a clean Debian container, - `install.ps1` on the Windows box, `cargo install prumo` in `rust:1-slim`. -- `doctor` without LaTeX now says where to get it, folds the four Poppler rows into one that - says what is lost, and names MiKTeX when there is no tlpdb. -- v0.2.0 is released (2026-11-10, after the `whatif` PR). The release has its ten assets, - crates.io has 0.2.0, and ghcr has `0.2.0` and `0.2.0-small` for amd64 and arm64. The - one-line installer from the README installs 0.2.0 in a clean Debian container. - -### Related tools - -texprof, latexpkges3, latex-dependency-grapher, texfindpkg, stygtfo, TinyTeX, texliveonfly -and mkjobtexmf were each installed and run on TeX Live 2026. The README has a section on them -and a paragraph on texprof. texprof is not a pdfTeX: it is TeX with e-TeX and Prote, writes -DVI, and could not build a LaTeX format against the 2026-11-01 kernel. `docs/02-prior-art.md` -is corrected; CLAUDE.md still says "pdfTeX only". - -### whatif - -- `prumo whatif main.tex [--try preamble,draft,externalize] [--runs 5] [--shell-escape]`. - Each experiment rebuilds its own copy of the directory with one change. - The timed builds run without the probe: a warm-up each, then the baseline and the variants - in turns. Medians are compared. A difference no larger than the larger spread (2 ms at - least, the polling resolution) is "within noise". The output is compared by page count, - the words on each page and a 24 dpi render (finding 63). `--json` has the same fields - under schema 1. -- The builds run one at a time, not on `unused`'s parallel pool, because parallel builds - slow each other down. The temp copy, the timeout and the text comparison come from `run` - and `unused`. -- `preamble` works on pdfTeX (the fixture goes from 244 to 91 ms). XeTeX and LuaTeX fail, - and the row gives the error (finding 60). `doctor` has a mylatexformat row and the TeX - image installs it. -- `externalize`: turned on from the command line alone, the external library made every - picture build typeset the whole document (finding 61). The system call now carries the hook and names the engine. The text - is identical on all three engines, and ten pictures went from 944 to 138 ms. Without - `--shell-escape` it is refused when asked for and not run by default. The table and the - README mark it experimental. -- New fixture `whatif`, eight claims, all tested. `make_artifacts.sh whatif` regenerates one - fixture now. The fixture turned up finding 62: `doctor --check-log` now tells an - existence check from a read. -- Defaults: `--runs` is at least 2. The comparison uses the last run's PDF. Logs go to - `//whatif//`. With `--shell-escape` the probed run is - `--build " -shell-escape"`, so `time` rebuilds afterwards. No `--latexmk` or - `--build`, since their wall time is several passes. -- `cargo test`, clippy and fmt pass, and so do the 19 TeX tests in the image. TeX Live 2021 - runs it too (on a copy of the fixture without siunitx, which that image lacks). - -### Only if cheap - -- `prumo time output.prumo` and `prumo graph output.prumo` read records from a build prumo - did not run, and build nothing. `docs/overleaf.md` says how, from Overleaf's source; not - tried on overleaf.com. -- LuaLaTeX font definitions per page: the `luaotfload.patch_font` hypothesis is wrong for - `\addfontfeature`, so nothing shipped (finding 57). - -**Blocked:** nothing. -**Open questions:** should the LuaTeX font count go in after all, through `font.nextid()`? -Should `compare` default to three runs, so it reports a median? +## Prior art credited (2026-11-12) + +Docs only. Nothing in `src/`, `tex/`, `tests/` or `fixtures/` changed. Where prumo does what +an existing tool already does, the README and the design docs now say so by name, before +saying what differs. + +- README: Origin says most of the pieces exist elsewhere. Related tools has SaTeX, DEPP and + pdffonts, a "Same idea as existing tools" list and a "What differs" list. A new Built on + section credits the hooks, `\sys_timer:`, `-recorder`, the tlpdb, Poppler, latexmk and + mylatexformat. +- `docs/02-prior-art.md` has the same list, rows for SaTeX, DEPP, Joseph Wright's script, + texdepend, texdeps and the TeX.SE per-page timer, and the tex-live thread of April 2024 + under demand signals. Its gaps are dated facts now, without verdicts. + `06-unused-packages.md` got the same pass. +- SaTeX 0.2.2 and pdffonts 26.07.0 were run on TeX Live 2026. DEPP, texdepend and texdeps + were read, not run. +- The byte-identical test compares the whole PDF, built twice in one directory with + `SOURCE_DATE_EPOCH=0` and `FORCE_SOURCE_DATE=1`. The README says that now. The test passes + on the TeX Live 2026 image (2026-11-12). +- CLAUDE.md no longer calls texprof pdfTeX, and "Don't reinvent" names SaTeX, texfindpkg, + DEPP and mylatexformat. + +**Blocked:** nothing. DEPP is still to be run. +**Open questions:** 13 to 18 in `08-open-questions.md`, recorded from the review. CLAUDE.md +rule 3 allows more than the test checks ("modulo /CreationDate and ID"); should it say what +the test does? Carried over: should the LuaTeX font count go in through `font.nextid()`, and +should `compare` default to three runs? ## Earlier milestones, one line each +- **Launch prep, v0.2.0 (11-09 to 10):** probe v0.2 (`docstart`, `lastpage`, environments), + the phase table and wall-time finalization, `compare` by wall time, ten-document benchmarks + with probe overhead and `whatif`, the `whatif` command, Related tools, public documents, + v0.2.0 released. - **M6, polish and release (11-07 to 09):** `--html`, terminal charts, artifacts in the cache directory, `docker/prumo`, release images and binaries, the public repo at v0.1.0 then v0.1.1 (crate under trusted publishing), Windows verified on MiKTeX, one-line installers,