# Documentation build

The published HTML is rendered from the authoritative doc/asciidoc tree in
BRL-CAD. The repository URL, exact source revision, and renderer version are
pinned in tools/docs-source.json.

Install Ruby and Asciidoctor 2.0.26, then use a clean documentation source tree
at the pinned revision:

    ruby tools/build-docs.rb --source /path/to/brlcad
    node tools/build.mjs
    python3 tools/build-docs-check.py

Unrelated changes outside doc/asciidoc do not affect the build. Source
license texts and the supplemental legacy figure are read directly from
the pinned Git revision, not from potentially modified working files.
The builder never fetches, checks out, or modifies that source checkout.

All AsciiDoc documents, translations, images, and supporting assets are
published under docs/html. The source's installed layout is preserved:
toplevel navigation pages live at the HTML root, and system/manual pages
live under man1, man3, man5, and mann. Existing relative links are resolved
against that layout. The complete HTML catalog works without JavaScript.

The landing page's search data is generated as docs/search-index.json.
Both the corpus and search index are intentionally excluded from Git.
Publish them along with the tracked landing page, styles, and scripts.
No application server or external search service is needed.

Each build records its source revision, source date, source checksum,
document and asset counts, language counts, renderer version, and source
warnings in docs/html/build-manifest.json. No wall-clock build timestamp
is included. Original copyright notices are preserved and the source
license overview is included as docs/html/COPYING.txt. The complete BDL,
BSD, and LGPL texts are copied unchanged into docs/html/legal, along with
the renderer license for its shared stylesheet.

The builder applies limited presentation fixes in memory: it separates
author blocks from AsciiDoc headers, preserves literal include examples,
resolves actual includes inside the documentation source, treats Tcl
comment examples as literal text, and explicitly selects book/article
doctypes where needed. It never edits authoritative source documents.
Legacy fragment names are restored against their matching command terms,
headings, examples, and glossary labels. Retired STEP schema command links
resolve to the current step-g/g-step documentation, and remove resolves to
rm. Missing EPS placeholder figures are identified in the page instead of
displaying broken images; their filenames are recorded in the manifest.
Two retired remote logo examples in the article template use the site's
current local logo, so reading the documentation never loads remote images.

Generated pages reuse partials/header.html and the shared header CSS/JS.
Styles and scripts receive content-hash query strings so updates do not
depend on browser cache expiry.