The ucode manual

The sources of A comprehensive ucode programming manual — a book about ucode, the small ECMAScript-like scripting language for Linux systems.

The rendered book is published at https://ucode-lang.github.io/manual on every push to main: the book as a single self-contained page, together with a typeset PDF edition at ucode-manual.pdf.

Layout

Path	What it is
contents.md	The book outline: parts, chapters, appendices
chapters/	The chapters, one file each, in reading order
appendices/	The appendices
sources.json	The pinned revisions every quoted file is read at
render/	The HTML/PDF renderer

Building the book

python3 render/render.py            # writes dist/index.html and dist/ucode-manual.pdf
python3 render/render.py --no-pdf   # HTML only

Dependencies: pip install markdown-it-py pygments weasyprint (weasyprint needs the pango system libraries for the PDF; the HTML alone needs neither weasyprint nor pango).

The output is a single self-contained page: every chapter on one HTML page, syntax-highlighted code blocks with copy buttons, and //! authoring directives stripped from the rendered examples.

Run buttons

Every example that can run in the web interpreter gets a small Run button in its code bar, next to the Copy button. Clicking it opens the example in a new tab, already executed and left in the input box for tweaking:

• Plain ucode goes to the stateful REPL, try.ucode-lang.org/run/<code> (which redirects to /#code=<code>).
• Templates go to ucodepen, try.ucode-lang.org/pen/#p=<token>: the template blocks, the //! opts: -T blocks, and the cat > x.tpl / ucode -T x.tpl console transcripts are each packaged as a one-file pen (a .ut template, plus a main.uc script when the transcript passes -D name=value definitions).

Examples the WASM build cannot run get no button: ones marked //! skip or <!-- check: skip -->, and ones that import a module the browser build does not ship (ubus, uci, rtnl, nl80211, uloop, log, serial, ffi, debug). That list lives in render/render.py (UNAVAILABLE_MODULES); keep it in sync with the web-interpreter's WEB_MODULES when that build changes. The buttons are screen-only: the code bar is hidden in the PDF.

CI

.github/workflows/render.yml renders the book and publishes it to GitHub Pages on every push to main. The toolchain is two pip packages plus weasyprint's pango runtime libraries — a few tens of megabytes, no LaTeX.