+ The first time you run `make doc', the process can easily take an
+hour or more. After that, `make doc' only makes changes to the
+pre-built documentation where needed, so it may only take a minute or
+two to test changes if the documentation is already built.
+
+ If `make doc' succeeds, the HTML documentation tree is available in
+`out-www/offline-root/', and can be browsed locally. Various portions
+of the documentation can be found by looking in `out/' and `out-www'
+subdirectories in other places in the source tree, but these are only
+_portions_ of the docs. Please do not complain about anything which is
+broken in those places; the only complete set of documentation is in
+`out-www/offline-root/' from the top of the source tree.
+
+ Compilation of documentation in Info format with images can be done
+separately by issuing:
+
+ make info
+
+
+Known issues and warnings
+.........................
+
+If source files have changed since the last documentation build, output
+files that need to be rebuilt are normally rebuilt, even if you do not
+run `make doc-clean' first. However, build dependencies in the
+documentation are so complex that some newly-edited files may not be
+rebuilt as they should be; a workaround is to `touch' the top source
+file for any manual you've edited. For example, if you make changes to
+a file in `notation/', do:
+
+ touch Documentation/notation.tely
+
+The top sources possibly affected by this are:
+
+ Documentation/extend.texi
+ Documentation/changes.tely
+ Documentation/contributor.texi
+ Documentation/essay.tely
+ Documentation/extending.tely
+ Documentation/learning.tely
+ Documentation/notation.tely
+ Documentation/snippets.tely
+ Documentation/usage.tely
+ Documentation/web.texi
+
+You can `touch' all of them at once with:
+
+ touch Documentation/*te??
+
+However, this will rebuild all of the manuals indiscriminately--it is
+more efficient to `touch' only the affected files.
+
+Saving time with `CPU_COUNT'
+............................
+
+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 the `-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 unless
+your system has enough RAM to run that many simultaneous LilyPond
+instances. Also, values for the `-j' option that pose problems with
+`make' are less likely to pose problems with `make doc' (this applies
+to both `-j' and `CPU_COUNT'). For example, with a quad-core processor,
+it is possible for `make -j5 CPU_COUNT=5 doc' to work consistently even
+if `make -j5' rarely succeeds.
+
+AJAX search
+...........
+
+To build the documentation with interactive searching, use:
projects / lilypond.git / blobdiff