Weave highlighted, language-aware documentation by default#74
Open
dbosk wants to merge 13 commits into
Open
Conversation
The prose examples like [[<<module_name.py>>=]] made noweave parse the inner <<...>> as a real chunk reference: the raw underscore in the chunk name reached LaTeX unescaped (breaking compilation with "Missing $ inserted") and the reference linked to a never-defined chunk. Examples quoting the [[...]] notation itself, like [[[[...]]]], truncated at the first ]] and left stray bracket text in the PDF. Literal chunk syntax is now written with noweb's @<<...@>> escape inside [[...]], and literal double brackets with \texttt and split brackets, so the document compiles again and the examples render as intended. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
NOWEAVE.tex now weaves through noweb's autolang and tominted filters (dbosk noweb fork): each chunk is syntax-highlighted with minted using a per-chunk lexer, and -autodefs python3 fills the identifier index with -autolang gating the autodefs filters so chunks in other languages stay out of the index. The chunk-name-equals-filename convention our tangling rules already enforce is what drives the language inference. The bundled Pygments lexer keeps chunk references hyperlinked inside Python strings; noweb.mk provides a rule copying it from noweb's library directory (read from the LIB= line of the noweave script), and documents declare a dependency on it, as makefiles.pdf now does. Documents must load minted and compile with -shell-escape, which our own build already did. NOWEAVE.pdf keeps the classic rendering: its preamble is generated by noweave and cannot load minted. Everything is set with ?=, so projects without the fork override NOWEAVEFLAGS.tex. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The autodefs filters now index make targets such as upload and autocommit, which turns every [[...]] quote of those names into a hyperlinked identifier use --- including the ones in section headings, where hyperref cannot survive a link inside the moving argument (the PDF bookmark breaks with "Undefined control sequence \hyper@@link"). Headings now write \texttt where body prose keeps the quoted, linked form. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
noweb now ships autodefs filters for shell and make (and Haskell, Rust and Java), gated by the same @language annotations -autolang provides, so stacking them indexes every chunk by exactly the filter that understands it. The default stack --- Python, shell, make --- covers what our projects mix into one document: program modules, helper scripts and their build files; our own woven documentation now indexes its make variables and targets. The stack stays at three because noweave has seven filter slots and -autolang, each -autodefs and tominted occupy one each; the default leaves two slots free for project filters, and other languages remain a one-line NOWEAVEFLAGS.tex override. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The caution claimed the default stack leaves two of noweave's seven filter slots free. It missed that -index inserts two filters (finduses + noidx); with -autolang and tominted also taking one each, the three-autodefs default fills all seven exactly. Adding a fourth -autodefs or a project -filter overflows unless something is dropped. Prose-only change in a documentation chunk; the tangled noweb.mk is unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Replace the seven-filter-slot caution with the dbosk fork's unbounded
pipeline; keep the old ceiling only as a note for pre-fork noweave.
- Note that the preamble loads minted through the noweb package
(\usepackage[minted]{noweb}) rather than a hand-added \usepackage{minted}.
- Record that noweave -minted can load minted into the generated preamble,
so the standalone .pdf weave stays classic by choice, not necessity.
Documentation only; the tangled noweb.mk is unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the hand-added \usepackage{minted} (plus a separate
\usepackage{noweb}) with \usepackage[minted]{noweb}, so the minted
dependency rides the noweb package the way tominted weaves expect.
\setminted{autogobble} still applies, as minted is loaded (via
\AtEndOfPackage) before it runs.
Requires the noweb fork whose noweb.sty declares the minted option;
to pass minted options such as outputdir, load minted directly before
\usepackage{noweb} instead.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The dbosk fork's noweave, with -index, runs -autolang's inference as a pre-pass to discover which languages a document contains and stacks the matching autodefs filter for each. The default weave therefore no longer lists -autodefs python3/sh/make: discovery covers them, and an explicit -autodefs is still merged without duplication for chunks whose language the name does not reveal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Test chunks follow the convention <<test [[foo.py]]>>, labelling the file rather than being it, and autolang deliberately does not infer a language from such a labelled name. Left unclassified, a test chunk is scanned by every autodefs filter and salts the index with cross-language false matches. Add one -langrule per supported language (python, shell, make) so each test chunk is classified, and hence indexed, by the same filter as the module it exercises. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Makes
noweb.mk's default weave produce syntax-highlighted documentation with a language-aware identifier index, using the dbosk noweb fork'sautolang/tominted/autodefs filters.What's here
NOWEAVE.texdefault now weaves-autolang -autodefs python3 -autodefs sh -autodefs make -index -filter 'tominted -lexer noweb_lexer.py': each chunk syntax-highlighted with minted, the index gated by language so foreign chunks don't pollute it.noweb.mkprovides a rule copyingnoweb_lexer.pyfrom noweb's lib dir; documents declare a dependency on it (asmakefiles.pdfnow does).NOWEAVE.pdfstays classic (its generated preamble can't load minted).-indexconsumes two slots; the default fills all seven).Requires
The dbosk noweb fork (
autolang/tominted+ autodefs filters), minted, and a one-timelatexmintedwhitelist for the custom lexer. See the corresponding noweb PRs (dbosk/noweb#3, #4).🤖 Generated with Claude Code