GNU LilyPond program usage: 1.2.4 Building documentation

### 1.2.4 Building documentation

This requires a successful compile of LilyPond, or using an external LilyPond binary.

#### Commands for building documentation

The documentation is built by issuing

>     make doc

After compilation, the HTML documentation tree is available in ‘`out-www/offline-root/`’, and can be browsed locally.

The HTML, PDF and if available Info files can be installed into the standard documentation path by issuing

>     make install-doc

This also installs Info documentation with images if the installation prefix is properly set; otherwise, instructions to complete proper installation of Info documentation are printed on standard output.

Compilation of documentation in Info format with images can be done separately by issuing

>     make info

Separate installation of this documentation is done by issuing

>     make install-info

Note that to get the images in Info documentation, `install-doc` target creates symbolic links to HTML and PDF installed documentation tree in ‘`prefix/share/info`’, in order to save disk space, whereas `install-info` copies images in ‘`prefix/share/info`’ subdirectories.

It is possible to build a documentation tree in ‘`out-www/online-root/`’, with special processing, so it can be used on a website with content negotiation for automatic language selection; this can be achieved by issuing

>     make WEB_TARGETS=online doc

and both ‘offline’ and ‘online’ targets can be generated by issuing

>     make WEB_TARGETS="offline online" doc

Several targets are available to clean the documentation build and help with maintaining documentation; an overview of these targets is available with

>     make help

from every directory in the build tree. Most targets for documentation maintenance are available from ‘`Documentation/`’; for more information, see the Contributors’ Guide, section Documentation work.

The makefile variable `QUIET_BUILD` may be set to `1` for a less verbose build output, just like for building the programs.

#### Known issues and warnings

The most time consuming task for building the documentation is running LilyPond to build images of music, and there cannot be several simultaneously running `lilypond-book` instances, so `-j` `make` option does not significantly speed up the build process. To help speed it up, the makefile variable CPU_COUNT may be set in ‘`local.make`’ or on the command line to the number of `.ly` files that LilyPond should process simultaneously, e.g. on a bi-processor or dual core machine

>     make -j3 CPU_COUNT=3 doc

The recommended value of CPU_COUNT is one plus the number of cores or processors, but it is advisable to set it to a smaller value if your system has not enough RAM to run that many simultaneous LilyPond instances.

If source files have changed since last documentation build, output files that need to be rebuilt are normally rebuilt, even if you do not run `make doc-clean` first. However, building dependencies in the documentation are so complex that rebuilding of some targets may not be triggered as they should be; a workaround is to force rebuilding by touching appropriate files, e.g.

>     touch Documentation/user/*.itely
>     touch input/lsr/*.ly

#### Building documentation without compiling LilyPond

The documentation can be built locally without compiling LilyPond binary, if LilyPond is already installed on your system.

From a fresh Git checkout, do

>     ./autogen.sh   # ignore any warning messages
>     cp GNUmakefile.in GNUmakefile
>     make -C python
>     nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc

Please note that this may break sometimes – for example, if a new feature is added with a test file in input/regression, even the latest development release of LilyPond will fail to build the docs.

You may build the manual without building all the ‘`input/*`’ stuff: change directory, for example to ‘`Documentation/user`’, issue `make doc`, which will build documentation in a subdirectory ‘`out-www`’ from the source files in current directory. In this case, if you also want to browse the documentation in its post-processed form, change back to top directory and issue

>     make out=www WWW-post

#### Known issues and warnings

You may also need to create a script for `pngtopnm` and `pnmtopng`. On GNU/Linux, I use this:

    export LD_LIBRARY_PATH=/usr/lib
    exec /usr/bin/pngtopnm "$@"

On MacOS X, I use this:

    export DYLD_LIBRARY_PATH=/sw/lib
    exec /sw/bin/pngtopnm "$@"

#### Application Usage