Next: , Up: Building documentation


Commands for building documentation

The documentation is built by issuing

     make web

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

The HTML and PDF files can be installed into the standard documentation path by issuing

     make web-install

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

It is also 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 web

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

     make WEB_TARGETS="offline online" web

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 Documentation/user/README.txt and Documentation/TRANSLATION.

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 web

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 web-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