//! `docs/reference.html`, rendered from the primitive corpus.
//!
//! The page and the language server read the SAME table (`src/corpus.rs`), so a
//! primitive cannot be documented on the site and unknown to the editor, or the
//! other way round. `tests/docs_generated.rs` fails when the committed page and
//! this renderer disagree, which is what stops the file being hand-edited back
//! into drift.
//!
//! Regenerate with:
//!
//! ```sh
//! cargo run --bin gen-docs
//! ```
use std::fmt::Write as _;
use crate::corpus::{Entry, CHAPTERS, CORPUS};
/// The chrome above the generated chapters: head, header, scheme strip, title.
const HEAD: &str = "<!DOCTYPE html>
<html lang=\"en\">
<head>
<meta charset=\"utf-8\">
<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">
<meta name=\"color-scheme\" content=\"dark light\">
<meta name=\"description\" content=\"texrs — Primitive reference. Every TeX primitive texrs carries: category codes, macro definition, expansion, conditionals, count registers and their arithmetic, with what each one lowers to. MIT licensed.\">
<title>texrs — Primitive Reference</title>
<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">
<link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin>
<link href=\"https://fonts.googleapis.com/css2?family=Orbitron:wght@400;600;700;900&family=Share+Tech+Mono&display=swap\" rel=\"stylesheet\">
<link rel=\"stylesheet\" href=\"hud-static.css\">
<link rel=\"stylesheet\" href=\"tutorial.css\">
<style>
.tutorial-main { max-width: 76rem; }
.file-table { width:100%;border-collapse:collapse;margin:0.6rem 0;font-size:12px; }
.file-table th { background:var(--bg-secondary);color:var(--cyan);font-family:'Orbitron',sans-serif;font-size:10px;font-weight:700;letter-spacing:1.2px;text-transform:uppercase;text-align:left;padding:7px 10px;border:1px solid var(--border); }
.file-table td { padding:6px 10px;border:1px solid var(--border);color:var(--text-dim);vertical-align:middle; }
.file-table tr:hover td { background:var(--bg-hover); }
.file-table td:first-child { font-family:'Share Tech Mono',monospace;color:var(--accent-light);font-weight:600;white-space:nowrap; }
.file-table code { font-size:11px;color:var(--accent-light);background:var(--bg-primary);padding:1px 4px;border-radius:2px; }
.stat-grid { display:grid;grid-template-columns:repeat(auto-fill,minmax(14rem,1fr));gap:0.75rem;margin:1.2rem 0; }
.stat-card { border:1px solid var(--border);border-top:3px solid var(--cyan);background:var(--bg-card);padding:1rem 1.2rem;border-radius:2px;text-align:center; }
.stat-card .stat-val { font-family:'Orbitron',sans-serif;font-size:28px;font-weight:900;color:var(--cyan);line-height:1.1;text-shadow:0 0 20px var(--cyan-glow); }
.stat-card .stat-val.accent { color:var(--accent);text-shadow:0 0 20px var(--accent-glow); }
.stat-card .stat-label { font-family:'Orbitron',sans-serif;font-size:9px;font-weight:700;letter-spacing:2px;text-transform:uppercase;color:var(--text-muted);margin-top:0.5rem; }
.feature-grid { display:grid;grid-template-columns:repeat(auto-fill,minmax(22rem,1fr));gap:0.65rem;margin:0.8rem 0; }
.feature-card { border:1px solid var(--border);border-left:3px solid var(--cyan);background:var(--bg-card);padding:0.7rem 1rem;border-radius:2px; }
.feature-card h4 { font-family:'Orbitron',sans-serif;font-size:10px;font-weight:700;letter-spacing:1.5px;text-transform:uppercase;color:var(--cyan);margin:0 0 0.3rem; }
.feature-card p { margin:0;font-size:11px;color:var(--text-dim);line-height:1.55; }
.feature-card code { font-size:10.5px;color:var(--accent-light);background:var(--bg-primary);padding:1px 4px;border-radius:2px; }
.section-rule { border:none;border-top:1px dashed var(--border);margin:2rem 0; }
.hub-scheme-strip { border-bottom:1px dashed var(--border);background:color-mix(in srgb, var(--bg-secondary) 85%, transparent);padding:0.55rem 1.5rem 0.65rem;position:relative; }
.hub-scheme-strip-inner { max-width:76rem;margin:0 auto;display:flex;align-items:center;gap:0.85rem; }
.hub-scheme-strip .hud-scheme-label { flex:0 0 auto;font-family:'Orbitron',sans-serif;font-size:9px;font-weight:700;letter-spacing:2px;text-transform:uppercase;color:var(--accent);text-align:left; }
.hub-scheme-strip .scheme-grid { flex:1 1 auto;display:grid;grid-template-columns:repeat(5,minmax(0,1fr));gap:6px; }
@media (max-width:720px){ .hub-scheme-strip-inner{flex-direction:column;align-items:stretch}.hub-scheme-strip .scheme-grid{grid-template-columns:repeat(2,minmax(0,1fr))} }
.docs-build-line { margin:0.35rem 0 0;font-family:'Share Tech Mono',ui-monospace,monospace;font-size:11px;color:var(--text-dim);letter-spacing:0.03em;max-width:44rem;opacity:0.75; }
</style>
</head>
<body>
<div class=\"app tutorial-app\" id=\"docsApp\">
<div class=\"crt-scanline\" id=\"crtH\" aria-hidden=\"true\"></div>
<div class=\"crt-scanline-v\" id=\"crtV\" aria-hidden=\"true\"></div>
<header class=\"tutorial-header\">
<div class=\"tutorial-header-inner\">
<div>
<h1 class=\"tutorial-brand\">// TEXRS — PRIMITIVE REFERENCE</h1>
<nav class=\"tutorial-crumbs\" aria-label=\"Breadcrumb\">
<a href=\"index.html\">Docs</a>
<span class=\"sep\">/</span>
<a href=\"report.html\">Engineering Report</a>
<span class=\"sep\">/</span>
<span class=\"current\">Reference</span>
<span class=\"sep\">/</span>
<a href=\"https://github.com/MenkeTechnologies/texrs\" target=\"_blank\" rel=\"noopener noreferrer\">GitHub</a>
</nav>
<p class=\"docs-build-line\">texrs v__TEXRS_VERSION__ · TeX on fusevm · mouth → expander → command stream → bytecode → Cranelift JIT · MIT · in active development</p>
</div>
<div class=\"tutorial-toolbar\">
<button type=\"button\" class=\"btn btn-secondary\" id=\"btnTheme\" title=\"Toggle light/dark\">Theme</button>
<button type=\"button\" class=\"btn btn-secondary active\" id=\"btnCrt\" title=\"CRT scanline overlay\">CRT</button>
<button type=\"button\" class=\"btn btn-secondary active\" id=\"btnNeon\" title=\"Neon border pulse\">Neon</button>
<a class=\"btn btn-secondary\" href=\"index.html\">Docs</a>
<a class=\"btn btn-secondary\" href=\"report.html\">Report</a>
<a class=\"btn btn-secondary\" href=\"https://github.com/MenkeTechnologies/texrs\" target=\"_blank\" rel=\"noopener noreferrer\">GitHub</a>
</div>
</div>
</header>
<div class=\"hub-scheme-strip\">
<div class=\"hub-scheme-strip-inner\">
<span class=\"hud-scheme-label\">// Color scheme</span>
<div class=\"scheme-grid\" id=\"hudSchemeGrid\"></div>
</div>
</div>
<h2 class=\"tutorial-title\"><span class=\"step-hash\">>_</span>PRIMITIVE REFERENCE</h2>
<p class=\"tutorial-subtitle\">Every primitive texrs carries, what it does, and where it happens — at compile time while lowering, or at run time on the VM. A primitive not on this page is not implemented; <a href=\"https://github.com/MenkeTechnologies/texrs/blob/main/BUGS.md\">BUGS.md</a> says so explicitly for the ones that are commonly reached for.</p>
";
/// The chrome below them: the command-line table, the links, and the closing
/// tags. Not corpus-driven — the flags are the binary's, not the language's.
const FOOT: &str = " <section class=\"tutorial-section\">
<h2>Command line</h2>
<table class=\"file-table\">
<thead><tr><th>Invocation</th><th>What it does</th></tr></thead>
<tbody>
<tr><td><code>texrs FILE.tex</code></td><td>Run the file and print its <code>\\message</code> stream as <code>(./FILE.tex … )</code>.</td></tr>
<tr><td><code>texrs --dump-tokens FILE</code></td><td>Print the mouth's token stream and exit. No expansion happens.</td></tr>
<tr><td><code>texrs --disasm FILE</code></td><td>Print the lowered fusevm bytecode and exit.</td></tr>\n <tr><td><code>texrs --tiers FILE</code></td><td>Run it, then report which fusevm tier took its bytecode, asked of fusevm's own eligibility and cache predicates.</td></tr>\n <tr><td><code>texrs --aot FILE</code></td><td>Compile the document to a standalone native executable beside it. Requires a C toolchain for the link.</td></tr>\n <tr><td><code>texrs --repl</code></td><td>Start the interactive prompt: a line is read with every line before it still in effect.</td></tr>\n <tr><td><code>texrs --lsp</code></td><td>Speak the Language Server Protocol over stdio: completion and hover from this page's own corpus, diagnostics from the engine's lowerer.</td></tr>\n <tr><td><code>texrs --dap</code></td><td>Speak the Debug Adapter Protocol over stdio: source-line breakpoints, stepping, and the count registers as the variables scope.</td></tr>
<tr><td><code>texrs --no-cache FILE</code></td><td>Compile this run rather than reading the bytecode cache. The result is identical either way.</td></tr>
<tr><td><code>texrs --cache-stats</code></td><td>Print where the bytecode cache is, how many documents it holds and how large it is.</td></tr>
<tr><td><code>texrs --cache-clear</code></td><td>Delete the bytecode cache. Every document compiles again on its next run.</td></tr>
<tr><td><code>texrs --help</code></td><td>Print the option grammar.</td></tr>
<tr><td><code>texrs --version</code></td><td>Print the version banner.</td></tr>
</tbody>
</table>
<p>Errors go to stderr as <code>! <reason>.</code>, the way tex writes them, and the exit status is 1. <code>TEXRS_CACHE=0</code> (or <code>false</code>, or <code>no</code>) turns the bytecode cache off for a run without deleting it.</p>
</section>
<section class=\"tutorial-section\">
<h2>Links</h2>
<ul>
<li><strong>Documentation</strong> — <a href=\"index.html\">index.html</a></li>
<li><strong>Engineering report</strong> — <a href=\"report.html\">report.html</a></li>
<li><strong>Source</strong> — <a href=\"https://github.com/MenkeTechnologies/texrs\">github.com/MenkeTechnologies/texrs</a></li>
</ul>
</section>
</main>
</div>
<script src=\"hud-theme.js\"></script>
</body>
</html>
";
/// The full `docs/reference.html` page.
pub fn reference_html() -> String {
format!(
"{head}{body}{foot}",
head = HEAD.replace("__TEXRS_VERSION__", env!("CARGO_PKG_VERSION")),
body = chapters(CORPUS),
foot = FOOT,
)
}
/// One `<section>` per chapter in `CHAPTERS` order, each holding one table row
/// per primitive: the name, what it does, and its syntax with an example.
fn chapters(corpus: &[Entry]) -> String {
let mut out = String::new();
for chapter in CHAPTERS {
let entries: Vec<&Entry> = corpus.iter().filter(|(_, c, ..)| c == chapter).collect();
if entries.is_empty() {
continue;
}
let _ = write!(
out,
" <section class=\"tutorial-section\" id=\"ch-{anchor}\">\n <h2>{chapter}</h2>\n <table class=\"file-table\">\n <thead><tr><th>Primitive</th><th>What it does</th><th>Syntax and example</th></tr></thead>\n <tbody>\n",
anchor = anchor(chapter),
);
for (name, _chapter, doc, example) in entries {
let _ = writeln!(
out,
" <tr><td><code>{name}</code></td><td>{doc}</td><td><pre>{example}</pre></td></tr>",
name = escape(name),
doc = markdown_code(doc),
example = escape(example),
);
}
out.push_str(" </tbody>\n </table>\n </section>\n\n");
}
out
}
/// `Category codes` -> `category-codes`, for a stable in-page anchor.
fn anchor(chapter: &str) -> String {
chapter
.chars()
.map(|c| match c.is_ascii_alphanumeric() {
true => c.to_ascii_lowercase(),
false => '-',
})
.collect()
}
/// The corpus doc lines are prose with `backticked` code spans; render those as
/// `<code>` and escape everything else.
fn markdown_code(doc: &str) -> String {
let mut out = String::new();
let mut in_code = false;
for part in doc.split('`') {
out.push_str(&match in_code {
true => format!("<code>{}</code>", escape(part)),
false => escape(part),
});
in_code = !in_code;
}
out
}
fn escape(s: &str) -> String {
s.replace('&', "&")
.replace('<', "<")
.replace('>', ">")
}
/// `editors/emacs/texrs-stdlib.el`: the primitive names and their one-line
/// documentation, as elisp.
///
/// Generated rather than written so the Emacs mode's completion list and its
/// eldoc strings are the corpus the engine answers from — a hand-kept copy
/// drifts the moment a primitive is added, and drifts silently, since nothing
/// in Emacs would notice.
pub fn emacs_stdlib_el() -> String {
let mut out = String::new();
out.push_str(
";;; texrs-stdlib.el --- Primitive table for texrs-mode -*- lexical-binding: t; -*-\n\
\n\
;; This file is GENERATED by `cargo run --bin gen-emacs-stdlib' from\n\
;; texrs's own primitive corpus (src/corpus.rs). Do not edit it by hand:\n\
;; `tests/emacs_stdlib.rs' fails when it is not what the generator prints.\n\
\n\
;;; Commentary:\n\
\n\
;; The names texrs resolves, with the one-line documentation the\n\
;; language server hovers with. A primitive is here only if the engine\n\
;; dispatches it, so completion cannot offer something that would fail.\n\
\n\
;;; Code:\n\n",
);
out.push_str("(defconst texrs-primitive-names\n '(");
for (i, (name, ..)) in crate::corpus::CORPUS.iter().enumerate() {
if i > 0 {
out.push_str("\n ");
}
out.push_str(&format!("{:?}", name));
}
out.push_str(")\n \"Every primitive texrs resolves, for completion at point.\")\n\n");
out.push_str("(defconst texrs-stdlib--docs\n (let ((table (make-hash-table :test 'equal)))\n");
for (name, chapter, doc, _example) in crate::corpus::CORPUS {
// One line each: eldoc shows a line, and a doc with a newline in it
// would push the rest of the echo area off screen.
let summary = doc.split(". ").next().unwrap_or(doc).replace('\n', " ");
let summary = summary.trim_end_matches('.');
out.push_str(&format!(
" (puthash {:?} {:?} table)\n",
name,
format!("{name} — {summary}. [{chapter}]"),
));
}
out.push_str(
" table)\n \"Primitive name to the line eldoc shows for it.\")\n\n\
(defun texrs-stdlib-signature (name)\n \
\"Return the eldoc line for primitive NAME, or nil.\"\n \
(and (stringp name) (gethash name texrs-stdlib--docs)))\n\n\
(provide 'texrs-stdlib)\n;;; texrs-stdlib.el ends here\n",
);
out
}