tenkana 0.1.0: every message, the help page and the man page ============================================================ This file lists every text tenkana can print, so that the wording can be reviewed in one place. It is generated by tools/catalogue.py from the source; all texts live in src/tenkana/messages.py. 1. How tenkana's messages look ------------------------------ * TeX's own terminal output comes first, unchanged. * tenkana's messages follow at the end. * Each message is one line, starting with "tenkana: ", as Unix commands do; errors go to stderr. With --silent only errors are printed. Below, long messages are folded to fit this file. * {t} and similar placeholders are filled in at run time. Times are in seconds with one decimal (xx.xs). Example: Output written on talk.pdf (14 pages, 74150 bytes). Transcript written on talk.log. tenkana: jumped from ~xx.xs for a plain run to xx.xs (xx% less time). 2. Every message ---------------- Fragments (reasons, how a file changed, why snapshots are unavailable) are inserted into the messages that use them, as {reason}, {how}, {why} and {runs}. Shared by the version text, the help page and the installer ........................................................... [TAGLINE] tenkana, a spider that jumps from the checkpoints of your TeX document. [SPIDER] /\ ______ /\ / \ / . . \ / \ _/\___/ \__|o(O)(O)o|__/ \___/\_ / \ __ | '' | __ / \ / \/ \ \______/ / \/ \ [LLM_NOTE] tenkana was written by Claude, a large language model (LLM). See the README file for what this means for its copyright. The version text (tenkana --version) .................................... [VERSION] tenkana {version} Copyright © 2026 निरंजन (Niranjan) License GPLv3+: GNU GPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. tenkana was written by Claude, a large language model (LLM). See the README file for what this means for its copyright. The help page (tenkana --help) .............................. [USAGE] usage: tenkana [tenkana options] TeX-command [TeX options] file tenkana [tenkana options] -q file [HELP] usage: tenkana [tenkana options] TeX-command [TeX options] file tenkana [tenkana options] -q file /\ ______ /\ / \ / . . \ / \ _/\___/ \__|o(O)(O)o|__/ \___/\_ / \ __ | '' | __ / \ / \/ \ \______/ / \/ \ tenkana, a spider that jumps from the checkpoints of your TeX document. It keeps frozen copies of the TeX engine (just before \begin{document} and before each \include) and, after an edit, continues from the last one before the change. Give tenkana the TeX command line you would type without it, as with env or time: tenkana lualatex thesis tenkana pdflatex -shell-escape -synctex=1 thesis tenkana pdflatex-dev '\nonstopmode\input paper.ltx' The command may be pdflatex, lualatex, xelatex, or any other command that runs pdfTeX, LuaTeX or XeTeX (pdflatex-dev, lualatex-dev, ...). TeX runs in the current folder. tenkana options (before the TeX command): -q, --quick the file only, with the default engine: tenkana -q thesis is tenkana lualatex thesis (or $TENKANA_ENGINE thesis) -F, --final rerun until cross-references, citations and the table of contents are up to date (for submission) -d, --draft one pass, references not updated (the default) -v, --verbose also show tenkana's details: passes, changed files, snapshots, memory --silent show only TeX's output and tenkana's errors --no-snapshots build with plain runs instead of snapshots -f, --force discard snapshots and cached state, build from scratch --clean stop a document's snapshots, delete its cache, and exit: tenkana --clean thesis (or the TeX command) -V, --version show the version, copyright and license, and exit -h, --help show this help and exit -- end of tenkana options TeX's options go to TeX unchanged. tenkana itself adds only -recorder (it needs the list of files TeX reads) and, for XeTeX, -no-pdf (tenkana runs xdvipdfmx at the end). Not supported yet: -ini, -fmt, &format, -output-directory, -aux-directory, -output-format, -output-driver. Environment: TENKANA_ENGINE (the engine for -q; default lualatex), TENKANA_SILENT (if set, as --silent), TENKANA_TTL (seconds snapshots live after the document's last build, default 28800), TENKANA_SAVE_LIMIT (largest preamble snapshot to keep on disk, in MB; default 20, 0 = never), TENKANA_WATCH (more generated-file extensions to watch, e.g. 'glo2,xyz'), TENKANA_DEBUG=1 (explain snapshot decisions). See also: man tenkana. After a build ............. [FIRST_BUILD] tenkana: first build ({t}s); later builds start from its snapshots. [NO_SNAPSHOTS_MADE] tenkana: first build ({t}s), but no snapshots made; later builds are full runs. [SAVED] tenkana: jumped from ~{plain}s for {runs} to {t}s ({pct}% less time). [SLOWER] tenkana: {t}s, not faster than {runs} (~{plain}s); plain {engine} is as fast here. [FULL_RUN] tenkana: {reason}; full run, no time saved ({t}s). [DONE] tenkana: done ({t}s). [UP_TO_DATE] tenkana: nothing changed; the output is up to date. [UP_TO_DATE_DRAFT] tenkana: nothing changed; references may be out of date (--final updates them). [REFS_UNSTABLE] tenkana: references still changing after {n} passes; look for labels that move. [XDVIPDFMX_FAILED] tenkana: xdvipdfmx failed to turn {xdv} into a PDF. [RUNS_ONE] a plain run [RUNS_MANY] {n} plain runs [SLOWER_RUNS_ONE] the full run [SLOWER_RUNS_MANY] {n} full runs Why a build had to be a full run (used as {reason} in FULL_RUN) ............................................................... [REASON_PREAMBLE] the preamble changed [REASON_PREAMBLE_FILE] {file}, loaded in the preamble, {how} [REASON_GENERATED_PRE] {file} {how}, and the preamble reads it [REASON_COMMAND] the TeX command changed [REASON_UPDATED] tenkana was updated [REASON_ENDED] the snapshots had ended (a reboot, a logout, or {ttl} without a build) [REASON_UNUSABLE] the snapshots could not be used (TENKANA_DEBUG=1 shows why) [REASON_INTERRUPTED] the last build was interrupted [REASON_FAILED_EARLY] the last build stopped before \begin{document} [REASON_DISK] {why}, so the snapshot saved on disk could not be used [WHY_DISK_ENGINE] the engine is no longer installed where it was [WHY_DISK_DATA] its data is incomplete [WHY_DISK_CRASH] restoring it failed [WHY_DISK_TIMEOUT] restoring it took too long [HOW_NEW] appeared [HOW_GONE] disappeared [HOW_CHANGED] changed Snapshots not available: the build falls back to plain runs ........................................................... [NO_SNAPSHOTS] tenkana: snapshots unavailable ({why}); building without them. [WHY_PLATFORM] they need GNU/Linux on x86-64 [WHY_NO_LIBRARY] the snapshot library could not be built [WHY_NO_COMPILER] no C compiler to build the snapshot library [WHY_NO_BEGIN] no \begin{document} found in {file} [FMT_FAILED] tenkana: {engine} can't cache this preamble (see {log}); building without it. [FMT_BROKEN] tenkana: {engine} breaks with this preamble cached; built without, from now on. --clean / command-line problems ............................... [WAITING] tenkana: another build of {file} is running; waiting for it to finish. [CLEANED] tenkana: removed the cache for {file}. [NO_CACHE] tenkana: no cache for {file} in this folder; nothing to remove. [NO_MAIN_CLEAN] tenkana: which document? e.g. tenkana --clean thesis. [CLEANED_STOPPED] tenkana: removed the cache for {file} and stopped {n} snapshot{s}. [NO_COMMAND] tenkana: no TeX command given; e.g. tenkana lualatex thesis, or tenkana -q thesis. [NO_ENGINE] tenkana: {command} was not found on your PATH. [NOT_AN_ENGINE] tenkana: {command} doesn't run pdfTeX, LuaTeX or XeTeX, which tenkana needs. [NO_MAIN] tenkana: no \input in the TeX code, so no main file; running without snapshots. [UNKNOWN_OPTION] tenkana: unknown option {opt}; tenkana's options come before the TeX command. [MISSING_VALUE] tenkana: {opt} needs a value. [EXTRA_FILES] tenkana: -q takes one file ({extra} is a second one). [TEX_UNSUPPORTED] tenkana: the TeX option {opt} is not supported yet. Only with -v / --verbose ........................ [V_PASS_FULL] tenkana: pass {n} (full run, {t}s). [V_PASS_PREAMBLE] tenkana: pass {n} (resumed from the preamble snapshot, {t}s). [V_PASS_CHAPTER] tenkana: pass {n} (resumed before {file}, {t}s). [V_PASS_FALLBACK] tenkana: pass {n} (plain run, {t}s). [V_PASS_FALLBACK_FMT] tenkana: pass {n} (plain run with cached preamble, {t}s). [V_RERUN] tenkana: references changed; rerunning from the preamble snapshot. [V_REFS_DRAFT] tenkana: references changed; --final updates them. [V_CHANGED_FILES] tenkana: changed since the last build: {files}. [V_CHANGED_FILE] {file} ({how}) [V_MEMORY] tenkana: {n} snapshot{s} in memory, {mb}MB. [V_XDVIPDFMX] tenkana: xdvipdfmx ({t}s). [V_FMT_CACHED] tenkana: preamble cached ({t}s). [V_DISK] tenkana: restored the preamble snapshot from disk ({t}s). [V_SAVED] tenkana: preamble snapshot saved on disk ({mb}MB). [V_NOT_SAVED_BIG] tenkana: preamble snapshot not saved on disk ({mb}MB; the limit is {limit}MB). [V_NOT_SAVED_BIG_EST] tenkana: preamble snapshot not saved on disk (~{mb}MB; the limit is {limit}MB). [V_NOT_SAVED] tenkana: preamble snapshot not saved on disk ({why}). Only with TENKANA_DEBUG=1 (stderr, prefixed "tenkana[debug]: ") ............................................................... [D_HOLDER_DEAD] tenkana[debug]: resuming snapshot {k} failed (process {pid} is not alive) [D_NO_META] tenkana[debug]: resuming snapshot {k} failed (its data is missing; {err}) [D_FILE_REPLACED] tenkana[debug]: resuming snapshot {k} failed ({file} was replaced or deleted) [D_UNREACHABLE] tenkana[debug]: resuming snapshot {k} failed (it cannot be reached; {err}) [D_EVENT] tenkana[debug]: resuming snapshot {k} (event {ev}) [D_NO_ANSWER] tenkana[debug]: resuming snapshot {k} failed (it did not answer) 3. Installer (./install.sh) --------------------------- tenkana 0.1.0 tenkana, a spider that jumps from the checkpoints of your TeX document. /\ ______ /\ / \ / . . \ / \ _/\___/ \__|o(O)(O)o|__/ \___/\_ / \ __ | '' | __ / \ / \/ \ \______/ / \/ \ tenkana was written by Claude, a large language model (LLM). See the README file for what this means for its copyright. install.sh: removed $f usage: ./install.sh [--user | --system | --uninstall] install.sh: needs Python 3.9 or newer (python3 on your PATH). Installed successfully. install.sh: lualatex was not found; to build documents, install a install.sh: TeX distribution such as TeX Live. install.sh: no C compiler found; tenkana will build without snapshots. install.sh: but $found comes first on your PATH and runs instead; install.sh: remove it, or put $dest before it in PATH. install.sh: $dest is not on your PATH; add this line to ~/.bashrc install.sh: export PATH="$dest:$PATH" 4. Help page (tenkana --help) ----------------------------- usage: tenkana [tenkana options] TeX-command [TeX options] file tenkana [tenkana options] -q file /\ ______ /\ / \ / . . \ / \ _/\___/ \__|o(O)(O)o|__/ \___/\_ / \ __ | '' | __ / \ / \/ \ \______/ / \/ \ tenkana, a spider that jumps from the checkpoints of your TeX document. It keeps frozen copies of the TeX engine (just before \begin{document} and before each \include) and, after an edit, continues from the last one before the change. Give tenkana the TeX command line you would type without it, as with env or time: tenkana lualatex thesis tenkana pdflatex -shell-escape -synctex=1 thesis tenkana pdflatex-dev '\nonstopmode\input paper.ltx' The command may be pdflatex, lualatex, xelatex, or any other command that runs pdfTeX, LuaTeX or XeTeX (pdflatex-dev, lualatex-dev, ...). TeX runs in the current folder. tenkana options (before the TeX command): -q, --quick the file only, with the default engine: tenkana -q thesis is tenkana lualatex thesis (or $TENKANA_ENGINE thesis) -F, --final rerun until cross-references, citations and the table of contents are up to date (for submission) -d, --draft one pass, references not updated (the default) -v, --verbose also show tenkana's details: passes, changed files, snapshots, memory --silent show only TeX's output and tenkana's errors --no-snapshots build with plain runs instead of snapshots -f, --force discard snapshots and cached state, build from scratch --clean stop a document's snapshots, delete its cache, and exit: tenkana --clean thesis (or the TeX command) -V, --version show the version, copyright and license, and exit -h, --help show this help and exit -- end of tenkana options TeX's options go to TeX unchanged. tenkana itself adds only -recorder (it needs the list of files TeX reads) and, for XeTeX, -no-pdf (tenkana runs xdvipdfmx at the end). Not supported yet: -ini, -fmt, &format, -output-directory, -aux-directory, -output-format, -output-driver. Environment: TENKANA_ENGINE (the engine for -q; default lualatex), TENKANA_SILENT (if set, as --silent), TENKANA_TTL (seconds snapshots live after the document's last build, default 28800), TENKANA_SAVE_LIMIT (largest preamble snapshot to keep on disk, in MB; default 20, 0 = never), TENKANA_WATCH (more generated-file extensions to watch, e.g. 'glo2,xyz'), TENKANA_DEBUG=1 (explain snapshot decisions). See also: man tenkana. 5. Man page (man tenkana) ------------------------- tenkana(1) User Commands tenkana(1) NAME tenkana - a spider that jumps from the checkpoints of your TeX document SYNOPSIS tenkana [tenkana options] TeX-command [TeX options] file tenkana [tenkana options] -q file DESCRIPTION tenkana runs a TeX command, such as lualatex thesis, the way env(1) and time(1) run theirs, but makes repeated builds faster. While TeX runs, tenkana keeps frozen copies (snapshots) of the running engine: one just before \begin{document} and one before each \include. After an edit, tenkana continues from the last snapshot before the change, so the preamble, its packages and fonts, and all unchanged chapters before the edit are not processed again. tenkana lualatex thesis tenkana --final pdflatex -synctex=1 thesis tenkana pdflatex-dev '\nonstopmode\input paper.ltx' tenkana -q thesis The TeX command may be any command that runs pdfTeX, LuaTeX (also LuaHBTeX, LuaJITTeX) or XeTeX: pdflatex, lualatex, xelatex, pdflatex-dev and so on. tenkana finds the engine from the program the command finally runs. TeX runs in the current folder. TeX's first line, what follows its options, is usually the file name; if it is TeX code, tenkana takes the file of the first \input as the main file, and without an \input it runs the command as it is, without snapshots. The file is looked for as TeX does: in the current folder, then on TeX's search path (see kpsewhich(1)). If TeX would not find it either, tenkana runs the command as it is and TeX reports the problem. The engine and the document are not modified, and no root access is needed. tenkana runs your command as you typed it, and adds only -recorder right after the command name: it needs the list of files TeX reads, which TeX writes to job.fls. XeTeX also gets -no-pdf, followed by one xdvipdfmx(1) run at the end, as XeTeX would run it (xdvipdfmx -q -E); with your own -no-pdf, tenkana leaves the .xdv file as it is. TeX's questions (after an error, or from \typein) appear on your terminal and take your answers, and Ctrl-C reaches TeX, also when a build resumes from a snapshot. Snapshots are made with fork(2) by a small library that tenkana loads into the engine with LD_PRELOAD. They live in memory, as ordinary processes, and survive between runs of tenkana (see MEMORY). The preamble snapshot is also saved on disk, compressed, so it survives a reboot (see SNAPSHOTS ON DISK). TeX's own terminal output is shown unchanged. tenkana's messages follow it. Each is one line and starts with tenkana:; error messages go to standard error. DRAFT AND FINAL BUILDS By default tenkana makes a draft build: one pass. Cross-references, citations and the table of contents keep the values read by the last build that started at \begin{document} (a full run, a final build, or an edit that resumed from the preamble snapshot); new labels show as ??. The text and page layout are always current. With --final, tenkana reruns from the preamble snapshot until the .aux, .toc and similar files stop changing (at most 4 passes), like latexmk(1). Use it before submitting. OPTIONS tenkana's options come before the TeX command; the first word that is not one of them starts it, and -- ends them explicitly. -q, --quick Only the file is given, and the default engine is used: tenkana -q thesis is tenkana lualatex thesis (or the command in TENKANA_ENGINE). -F, --final Rerun until references, citations and the table of contents are up to date. -d, --draft One pass; references are not updated. This is the default. -v, --verbose Also show tenkana's details: passes, changed files, snapshots and their memory. --silent Show only TeX's output and tenkana's error messages. --no-snapshots Build with plain runs instead of snapshots. -f, --force Stop this document's snapshots, discard tenkana's cached state and build from scratch. --clean Stop a document's snapshots, delete its cache (see FILES), and exit. Name the document as for a build (tenkana --clean lualatex thesis) or just by its name (tenkana --clean thesis; thesis.tex and thesis.ltx mean the same). The file itself need not exist any more. -V, --version Print the version and exit. -h, --help Print a short help text and exit. TeX's options go to TeX unchanged: for example -shell-escape, -synctex=1, -interaction=batchmode, -file-line-error or -jobname=name. Not supported yet, and refused with a message: -ini, -fmt (and &format), -output-directory, -aux-directory, -output-format and -output-driver. A change of the TeX command makes the next build a full run. With SyncTeX on, the snapshot library keeps TeX's job.synctex(busy) file in tenkana's cache, where the snapshots can hold it, and copies it to job.synctex.gz at the end instead of renaming it, so snapshots work as usual. SNAPSHOTS ON DISK After a build that made a new preamble snapshot, a copy of that snapshot writes itself to tenkana's cache (see FILES) in the background, compressed with zstd (zlib if zstd is missing), unless it would be larger than TENKANA_SAVE_LIMIT. Only memory that differs from the files on disk is stored, and empty pages are skipped; typical sizes are 7–15MB. The default limit is 20MB. When the snapshots in memory have ended, tenkana starts the engine exactly as before (same command, environment and memory layout; address-space randomisation is switched off for the engine) and the snapshot library restores the image into it before the engine's main() runs, typically in 0.1–0.3s. The chapter snapshots are then made again in memory during that build. An image is used only on the same kernel and with the same engine, libraries and font files as when it was saved; otherwise tenkana makes a full run and says why. Images contain the engine's memory, including its environment variables; tenkana's cache is readable only by you. WHAT tenkana WATCHES Every file the engine reads (recorded with -recorder), assigned to the part of the run that first read it: the preamble, the body of the main file, or the stretch after one of the pauses before an \include. The parts follow what TeX actually did, so \includeonly, conditionals and \include inside an \input file are handled correctly. A change to a file read in the preamble needs a full run; a change to the main file's body resumes from the preamble snapshot; any other change resumes from the snapshot just before the part that first read the file. tenkana also records every file TeX looked for but did not find in the document's folder: a chapter not written yet, an image, a .bbl before biber(1) has run, an .ind before makeindex(1). When such a file appears, the next build continues from the part of the document that looked for it. In addition, files that other programs generate for TeX to read are watched by name, even if TeX has not looked for them yet: .bbl biber, BibTeX .ind makeindex, xindy .gls makeglossaries (main glossary) .acr makeglossaries (acronyms) .nls makeindex for nomencl .glstex bib2gls (read in the preamble: a full run) Glossary types declared in the .aux file are added automatically. Files are matched as job.ext, job-*.ext and chapter.ext. More extensions can be added with TENKANA_WATCH. Changes to the .aux, .toc and similar files written by TeX itself are deliberately ignored in draft builds. ENVIRONMENT TENKANA_ENGINE The command for -q instead of lualatex; it may have options, as in TENKANA_ENGINE="pdflatex -shell-escape". TENKANA_SILENT If set, as --silent. TENKANA_TTL Seconds the snapshots live after the document's last build (default 28800, i.e. 8 hours). TENKANA_SAVE_LIMIT Largest preamble snapshot to keep on disk, in MB (default 20). 0 turns saving off. TENKANA_WATCH Additional generated-file extensions to watch, separated by commas or spaces, e.g. TENKANA_WATCH=xyz,abc. They are assumed to be read in the preamble, so a change causes a full run. TENKANA_DEBUG If set, explain why a snapshot could not be used. TENKANA_SHIM Use this snapshot library instead of the built-in one. FILES ~/.cache/tenkana/ tenkana's cache ($XDG_CACHE_HOME/tenkana/ if that is set), readable only by you: the compiled snapshot library (kept in /tmp/tenkana-uid/ instead if the cache's path contains a space or a colon, which LD_PRELOAD cannot handle), and one folder per document under docs/, named after the job and a hash of the document's location. One build of a document runs at a time; a second one waits for the first. Nothing is written next to the document except TeX's own output (including job.fls), so a folder synchronised between computers (by Nextcloud, Syncthing, ...) carries no snapshots; each computer keeps its own. ~/.cache/tenkana/docs/job-hash/job-snap/ck000.img The preamble snapshot on disk. MEMORY A snapshot holds what the engine holds at that point, mostly fonts and packages; -v shows the total. Snapshots mark themselves as the first processes for the kernel's out-of-memory killer to stop (other memory managers, such as systemd-oomd(8), may choose differently). Snapshots are ordinary processes: they survive closing the terminal. They end at a reboot; at a logout only if the system ends a user's processes then (with systemd, when KillUserProcesses is set in logind.conf(5)); TENKANA_TTL after the document's last build; with tenkana --clean; and within half a minute after the document's cache folder is deleted. tenkana does not watch for any of this: at the next build it finds that the snapshots are gone, and restores the preamble snapshot from disk, or makes a full run if there is none. Snapshots keep the output files open. If another program replaces one of them (some synchronisation tools do), the snapshots that hold it cannot be used, and tenkana starts from an earlier one or makes a full run. EXIT STATUS 0 on success; TeX's exit status if TeX stopped with an error (or xdvipdfmx's, if it failed); 2 for a missing or unknown command or a wrong option; 128 plus the signal's number if tenkana or TeX was ended by a signal; 1 for other errors. NOTES Snapshots need GNU/Linux, a C compiler (to build the snapshot library on first use) and an x86-64 machine; without the compiler or on another processor, tenkana builds with plain runs. Snapshots need \begin{document} in the main file itself; other documents (plain TeX, for example) are built with plain runs. With \includeonly, only the chapters it includes get snapshots. \today, time stamps and \write18 side effects come from the run that made the snapshot. AUTHOR Written by Claude, a large language model (LLM) made by Anthropic. Designed, directed, reviewed and tested by निरंजन (Niranjan). COPYRIGHT Copyright © 2026 निरंजन (Niranjan). License GPLv3+: GNU GPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. tenkana was written by Claude, a large language model (LLM) made by Anthropic. Courts are divided on whether material generated by an LLM can be protected by copyright. Should it be found that the copyright claimant cannot hold copyright in any part of tenkana, that part is in the public domain. Wherever copyright does hold, tenkana is distributed under the terms of the GNU General Public License, version 3 or (at your option) any later version. SEE ALSO lualatex(1), pdflatex(1), xelatex(1), latexmk(1), biber(1), makeindex(1) tenkana 0.1.0 November 2026 tenkana(1) Copyright and license --------------------- Copyright © 2026 निरंजन (Niranjan) tenkana is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. tenkana is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with tenkana. If not, see . tenkana was written by Claude, a large language model (LLM) made by Anthropic. Courts are divided on whether material generated by an LLM can be protected by copyright. Should it be found that the copyright claimant cannot hold copyright in any part of tenkana, that part is in the public domain. Wherever copyright does hold, tenkana is distributed under the terms of the GNU General Public License, version 3 or (at your option) any later version, as stated above.