Building only one section of the documentation

In order to save build time, a script is available to build and immediately display only one section of the documentation in English with a default HTML appearance.

Call the script as follows.

scripts/auxiliar/doc-section.sh manual section

section is the name of the file containing the section to be built, and manual is replaced by the name of the directory containing the section. So, for example, to build section 1.1 of the Notation Reference, use the command:

scripts/auxiliar/doc-section.sh notation pitches

You can then see the generated document for the section at

build/tempdocs/pitches/out/pitches.html

To make this actually work it is necessary to first configure and compile LilyPond. Furthermore, the script listens to some environment variables.

• The location of the top-level directory of LilyPond’s git repository can be set with the LILYPOND_GIT environment variable. If not specified, the script tries to auto-detect its location.
• The location of the compilation directory can be set with the LILYPOND_BUILD_DIR environment variable. If not specified, the build/ directory in the git repository’s top-level directory is tried.
• The location of the script’s output directory can be set with the LILYPOND_TEMPDOCS environment variable. If not specified, it uses the tempdocs/ subdirectory within the compilation directory.
• The used browser to display the final HTML page defaults to Firefox; this can be changed by setting the standard BROWSER environment variable (which you probably have already set in your environment).

If these variables are set up correctly, you can call the script from any directory on your computer. If you configure the build process as recommended (see Configuring make), i.e., building in the git repository’s top-level subdirectory called build/, you don’t even need to set any of those environment variables.

This script will not work for building sections of the Contributor’s Guide. To do that, use:

scripts/auxiliar/cg-section.sh section

where section is the name of the file containing the section(s) to be built. For example, to build chapter 5 of the Contributor’s Guide, use:

scripts/auxiliar/cg-section.sh doc-work

The cg-section.sh script uses the same environment variables and corresponding default values as doc-section.sh.