Skip to documentation
BRL-CAD
DocumentationAll documentsEnglish

BRL-CAD AsciiDoc Documentation

On this page

Overview

This directory contains BRL-CAD documentation in AsciiDoc format. The .adoc files here are the authoritative documentation sources and are committed to version control. The one-time conversion from the original DocBook 5 XML sources is complete, and those legacy XML sources have been removed; edit the .adoc files directly.

The .adoc files are built into HTML and man-page outputs at compile time using asciiquack, BRL-CAD’s self-contained AsciiDoc processor.

Directory Structure

doc/asciidoc/
├── articles/          General articles
├── books/             Long-form books
├── devguides/         Developer guides
├── lessons/           Tutorial lessons
├── presentations/     Presentation slides
├── specifications/    Format specifications
└── system/
    ├── man1/          Section 1 man pages  (command-line tools)
    ├── man3/          Section 3 man pages  (C library functions)
    ├── man5/          Section 5 man pages  (file formats)
    └── mann/          Section n man pages  (MGED commands)

Build Outputs

When BRLCAD_EXTRADOCS=ON is set at CMake configuration time:

  • Man pages (system/man*/) are built by asciiquack with -b manpage and installed under ${MAN_DIR}/man*/.

  • Articles, books, and other prose (articles/, books/, etc.) are built with -b html5 and installed under ${DOC_DIR}/html/asciidoc/.

The build logic is in brlcad/misc/CMake/AsciiDoc.cmake.

Authoritative Sources

The .adoc files in this directory are the authoritative documentation sources. The one-time conversion from the retired DocBook 5 XML sources is complete, so there is no conversion step to re-run: make all documentation changes by editing the .adoc files directly.

Note

Documentation is built only when CMake is configured with BRLCAD_EXTRADOCS=ON. With the default configuration the documentation targets are skipped, so remember to enable this option when working on or verifying documentation.