Add support for QUIET_BUILD make variable

[lilypond.git] / Documentation / user / install.itely

diff --git a/Documentation/user/install.itely b/Documentation/user/install.itely
index 18c1c6fe1b4fd1fdbfd88d56407af7b2054e8de5..78079e595b61705a4e125e38b4b10a7ea504579e 100644 (file)
--- a/Documentation/user/install.itely
+++ b/Documentation/user/install.itely
@@ -7,20 +7,13 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.38"
+@c \version "2.11.51"
 
 @ifclear INSTALL
 @node Install
 @chapter Install
 @end ifclear
 
-@c  I don't know what this comment does.  Remove?  -gp
-@ignore
-@h tml
-<a name="download-source">
-@e nd html
-@end ignore
-
 There are two sets of releases for LilyPond: stable releases, and
 unstable development releases.  Stable versions have an even-numbered
 @q{minor} version number (i.e. 2.8, 2.10, 2.12, etc).  Development
@@ -39,7 +32,7 @@ recommend using the precompiled binaries.
 @node Precompiled binaries
 @section Precompiled binaries
 
-@subsection Downloading
+@unnumberedsubsec Downloading
 
 Check out @uref{http://lilypond.org/web/install/} for up to date
 information on binary packages for your platform.  If your operating
@@ -122,9 +115,15 @@ FOO-devel, libFOO-dev or FOO-dev package too.
 
 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
 
+@item MetaFont (mf-nowin, mf, mfw or mfont binaries), usually packaged with 
+a @LaTeX{} distribution like tetex or texlive.
+
+@item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
+(version 1.33 or newer recommended).
+
 @item New Century Schoolbook fonts, as PFB files.  These are shipped with
 X11 and Ghostscript, and are named @file{c059033l.pfb}
-@file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
+@file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
 
 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
 1.8.2 or newer).  If you are installing binary packages, you may need to
@@ -141,11 +140,11 @@ newer.  4.x is strongly recommended).
 
 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
 
-@item @uref{http://www.gnu.org/software/flex/,Flex} 
+@item @uref{http://www.gnu.org/software/flex/,Flex}.
 
-@item @uref{http://www.perl.org/,Perl} 
+@item @uref{http://www.perl.org/,Perl}.
 
-@item @uref{http://www.gnu.org/software/flex/,GNU Bison} 
+@item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
 
 @item All packages required for running, including development packages with
 header files and libraries.
@@ -255,6 +254,14 @@ mkdir lily-build && cd lily-build
 
 @end example
 
+
+@unnumberedsubsubsec Useful @command{make} variables
+
+If a less verbose build output if desired, the variable
+@code{QUIET_BUILD} may be set to @code{1} on @command{make} command
+line, or in @file{local.make} at top of the build tree.
+
+
 @node Building documentation
 @subsection Building documentation
 
@@ -285,6 +292,11 @@ path by issuing
 make web-install
 @end example
 
+@noindent
+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
 @file{out-www/online-root/}, with special processing, so it can be used
 on a website with content negotiation for automatic language selection;
@@ -315,6 +327,34 @@ documentation maintenance are available from @file{Documentation/};
 for more information, see @file{Documentation/user/README.txt} and
 @file{Documentation/TRANSLATION}.
 
+The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
+less verbose build output, just like for building the programs.
+
+@knownissues
+
+@code{-j} command-line option of @command{make} is unsupported for
+building the documentation.  As the most time consuming task is
+running LilyPond to build images of music, the makefile variable
+@code{CPU_COUNT} may be set in @file{local.make} or on the command line
+to the number of @code{.ly} files that LilyPond should process
+simultaneously, e.g. on a bi-processor or dual core machine
+
+@example
+make CPU_COUNT=2 web
+@end example
+
+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 @code{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.
+
+@example
+touch Documentation/user/*.itely
+touch input/lsr/*.ly
+@end example
+
 
 @node Building documentation without compiling LilyPond
 @unnumberedsubsubsec Building documentation without compiling LilyPond
@@ -335,13 +375,12 @@ 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
-@file{Documentation/user}, issue @code{make web}, which will build
-documentation in a subdirectory @file{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
+You may build the manual without building all the @file{input/*}
+stuff: change directory, for example to @file{Documentation/user},
+issue @code{make web}, which will build documentation in a
+subdirectory @file{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
 
 @example
 make out=www WWW-post