Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add a little context around how / why to build docs locally.

...

For instructions to set up the doc build environment and produce HTML and PDF, see the docs/README.md file. Once the build environment is set up, you can do local builds of HTML, PDF, or both by issuing one of the following commands in the docs/ directory:

make html

make pdf

make all # Creates both HTML and PDF

Building either output format is a good way to check that all cross-references resolve properly, something that is not caught by file-at-a-time validation such as is done by xmllint. It is also useful to proofread content where the source is heavily tagged, or uses constructs like conref= that make it hard to reason about the exact text that appears in the output.

XML Source Conventions

Frequently Used Tags

...