Nelson GitBook 📚

Welcome to the Nelson GitBook repository! This project hosts the official documentation for the Nelson array programming language.

Overview 🌟

This repository contains:

• HTML documentation — built by Nelson's buildhelpweb and published to nelson-lang.github.io/nelson-gitbook.
• Markdown sources — generated under markdown/ by buildhelpmd, for GitBook or offline reading.
• Typst sources — generated under typst/ by buildhelptypst; they are the single input of the PDF manuals.
• PDF builder — a Rust tool (nelson-pdf-builder) that embeds the Typst compiler and produces the printable manuals without any external program.

Supported languages: English (en) and French (fr).

Prerequisites 🛠️

Tool	Purpose
Nelson	Generate HTML, Markdown and Typst help files
Rust / Cargo	Build and run the PDF builder

Updating the Documentation ⚙️

Run the following script from inside Nelson to regenerate all HTML, Markdown and Typst files:

% From the nelson-gitbook root directory
run('./scripts/update_help.m');

This script:

1. Calls buildhelpweb to produce versioned and latest HTML output under docs/releases/.
2. Calls buildhelpmd to regenerate the Markdown sources under markdown/.
3. Calls buildhelptypst to regenerate the Typst sources under typst/. typst/<lang>/main.typ follows the order of the markdown manual: home page, getting started, one main.typ per module, changelogs, licenses, and the table of contents at the end. The hand-written markdown pages (home, getting started, changelogs, licenses) are converted to Typst by buildhelptypst itself.

After running, review and commit the modified files.

Building PDF Manuals 📄

Linux / macOS

./build-pdf.sh              # builds both en and fr
./build-pdf.sh en           # English only
./build-pdf.sh fr           # French only

Windows

build-pdf.bat               :: builds both en and fr
build-pdf.bat en            :: English only
build-pdf.bat fr            :: French only

The scripts compile the Rust PDF builder (cargo build --release) and run it: typst/<lang>/main.typ is compiled in-process into nelson-<lang>.pdf. A single document can also be compiled directly:

cargo run --release -- --typst-main typst/en/core/main.typ --output-file core.pdf

Notes on the PDF pipeline:

• No external tool is needed: the Typst compiler, its PDF exporter and the default fonts (Libertinus, New Computer Modern, DejaVu Sans Mono) are linked into the builder. The fonts of the manual (Noto Sans, Noto Sans Math, Noto Sans JP, Noto Emoji, JetBrains Mono, all under the SIL Open Font License) are vendored in theme/fonts/ (see its README), so the PDF is identical on every platform; system fonts remain available as a last resort.
• Typst packages are not downloaded by the builder: they are vendored under theme/typst-packages/<namespace>/<name>/<version>/ (the layout of the Typst package cache). @preview/mitex 0.2.7 is vendored there and renders the LaTeX fragments of the help pages; the typst CLI fetches it from Typst Universe by itself.
• The document style (Noto Sans body text, JetBrains Mono code, blue table headers, grey code boxes, Page X of Y footer) is the nelson-style show rule of nelson_help.typ, generated by Nelson and applied by typst/<lang>/main.typ.
• Cross-references between pages are labels (<module:page>) resolved by the nlink helper of nelson_help.typ: a link when the target page is part of the document, plain text otherwise.
• Block library icons (SVG exports under libraries/<lib>/exports/) are emitted as block-icon(image(...)): like the HTML help, the helper caps them at 12 × 9 em of the body text (the proportions of the 192 × 144 px cap of the HTML help for a 16 px text), never enlarges them, centers them and draws a thin border. The markdown emitter centers them too and sets the width attribute from the SVG's own width (read with document()), capped at 192 px, so small icons keep their size. Other images keep their natural size, limited to the text width.
• Some 3D plots are exported by Nelson as SVG files carrying several full-size PNG layers (about 1700 px wide), and screenshots are PNG files of 1000 to 1700 px. When Typst loads such a figure, the builder downscales the bitmaps to at most 800 px (MAX_EMBEDDED_BITMAP_WIDTH in src/typst_engine.rs); vector parts are untouched. Without this the English manual was a 157 MB PDF.
• The PDF is exported without the tagged-PDF structure tree (tagged: false): with 8,000 pages it added 500,000 structure objects and 100 MB. Bookmarks and the table of contents only list chapters and pages (buildhelptypst marks deeper headings as not outlined).
• Diagnostics are printed with file and line; warnings do not fail the build, errors do.
• The PDF metadata carries the creation date and the builder version as creator; datetime.today() is available to the Typst sources.
• The CI workflow builds en and fr in parallel jobs on Linux and uploads them as artifacts; on a v* tag, both PDFs are attached to the GitHub release.

Published Documentation 🌐

The latest documentation is available at: https://nelson-lang.github.io/nelson-gitbook/

Contributing 🤝

Contributions are welcome! Please open issues or submit pull requests for improvements, corrections, or new content.

License 📜

This project is licensed under the same license as Nelson. See the LICENSE file for details.

Contact 📧

Maintainer: Allan CORNET
Email: [email protected]