+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 "$@"
+
+Testing LilyPond
+----------------
+
+LilyPond comes with an extensive suite that exercises the entire
+program. This suite can be used to automatically check the impact of a
+change. This is done as follows
+
+ make test-baseline
+ _## apply your changes, compile_
+ make check
+
+ This will leave an HTML page `out/test-results/index.html'. This
+page shows all the important differences that your change introduced,
+whether in the layout, MIDI, performance or error reporting.
+
+ To rerun tests, use
+
+ make test-redo _## redo files differing from baseline_
+ make test-clean _## remove all test results_
+
+and then run `make check' again.
+
+ For tracking memory usage as part of this test, you will need GUILE
+CVS; especially the following patch:
+`http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch'.
+
+ For checking the coverage of the test suite, do the following
+
+ ./scripts/auxiliar/build-coverage.sh
+ _# uncovered files, least covered first_
+ ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
+ _# consecutive uncovered lines, longest first_
+ ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
+
+Problems
+--------
+
+For help and questions use <lilypond-user@gnu.org>. Send bug reports
+to <bug-lilypond@gnu.org>.
+
+ Bugs that are not fault of LilyPond are documented here.
+
+Bison 1.875
+...........
+
+There is a bug in bison-1.875: compilation fails with "parse error
+before `goto'" in line 4922 due to a bug in bison. To fix, please
+recompile bison 1.875 with the following fix
+
+ $ cd lily; make out/parser.cc
+ $ vi +4919 out/parser.cc
+ # append a semicolon to the line containing "__attribute__ ((__unused__))
+ # save
+ $ make
+
+Solaris
+.......
+
+Solaris7, ./configure
+
+ `./configure' needs a POSIX compliant shell. On Solaris7, `/bin/sh'
+is not yet POSIX compliant, but `/bin/ksh' or bash is. Run configure
+like
+
+ CONFIG_SHELL=/bin/ksh ksh -c ./configure
+
+or
+
+ CONFIG_SHELL=/bin/bash bash -c ./configure
+
+FreeBSD
+.......
+
+To use system fonts, dejaview must be installed. With the default
+port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
+
+ Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
+following line just after the `<fontconfig>' line. (Adjust as necessary
+for your hierarchy.)
+
+ <dir>/usr/X11R6/lib/X11/fonts</dir>
+
+International fonts
+...................
+
+On MacOS X, all fonts are installed by default. However, finding all
+system fonts requires a bit of configuration; see this post
+(http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
+on the `lilypond-user' mailing list.
+
+ On Linux, international fonts are installed by different means on
+every distribution. We cannot list the exact commands or packages that
+are necessary, as each distribution is different, and the exact package
+names within each distribution changes. Here are some hints, though:
+
+Red Hat Fedora
+
+ taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
+ ttfonts-zh_CN fonts-ja fonts-hebrew
+
+Debian GNU/Linux
+
+ apt-get install emacs-intl-fonts xfonts-intl-.* \
+ ttf-kochi-gothic ttf-kochi-mincho \
+ xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi