CG: Update info about make doc.

[lilypond.git] / Documentation / included / compile.itexi

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index 5c4db5807c9698f735200158d2cbf29828e4f1fc..c3aa45de1cffeaaae70ba9c589b04c9e68eec87c 100644 (file)
--- a/Documentation/included/compile.itexi
+++ b/Documentation/included/compile.itexi
@@ -7,7 +7,6 @@
 @c   @n ode Compiling from source
 @c   @s ection Compiling from source
 
 @c   @n ode Compiling from source
 @c   @s ection Compiling from source
 

-

 @menu
 * Overview of compiling::
 * Requirements::
 @menu
 * Overview of compiling::
 * Requirements::


@@ -44,7 +43,7 @@ without compiling}.
 
 Attempts to compile LilyPond natively on Windows have been
 unsuccessful, though a workaround is available (see
 
 Attempts to compile LilyPond natively on Windows have been
 unsuccessful, though a workaround is available (see

-@rcontrib{Lilybuntu}).
+@rcontrib{Lilydev}).

 
 
 @node Requirements
 
 
 @node Requirements


@@ -140,7 +139,9 @@ python@var{version}-dev
 @item @uref{http://flex.sourceforge.net/, Flex}
 
 @item @uref{http://fontforge.sf.net/, FontForge} (20060125 or
 @item @uref{http://flex.sourceforge.net/, Flex}
 
 @item @uref{http://fontforge.sf.net/, FontForge} (20060125 or

-newer)
+newer; 20100501 or newer is recommended; must be compiled
+with @option{--enable-double}.  Failure to do so can lead to
+poor intersection calculations and poorly-rendered glyphs.)

 
 @item @uref{http://www.gnu.org/software/bison/, GNU Bison}
 
 
 @item @uref{http://www.gnu.org/software/bison/, GNU Bison}
 


@@ -283,7 +284,7 @@ download and install the free-software
 
 @menu
 * Running ./autogen.sh::
 
 @menu
 * Running ./autogen.sh::

-* Running ./configure::
+* Running ../configure::

 @end menu
 
 
 @end menu
 
 


@@ -299,50 +300,65 @@ Next, you need to create the generated files; enter the following
 command from your top source directory:
 
 @example
 command from your top source directory:
 
 @example

-./autogen.sh
+./autogen.sh --noconfigure

 @end example
 
 @end example
 

-This will:
-
-@enumerate
-@item generate a number of files and directories to aid
+This will generate a number of files and directories to aid

 configuration, such as @file{configure}, @file{README.txt}, etc.
 
 configuration, such as @file{configure}, @file{README.txt}, etc.
 

-@item automatically run the @command{./configure} command.
-@end enumerate
+Next, create the build directory with:
+
+@example
+mkdir build/
+cd build/
+@end example
+
+We heavily recommend building lilypond inside a separate directory
+with this method.
+

 
 

+@node Running ../configure
+@subsection Running @command{../configure}

 
 

-@node Running ./configure
-@subsection Running @command{./configure}

 
 @menu
 * Configuration options::
 * Checking build dependencies::
 * Configuring target directories::
 
 @menu
 * Configuration options::
 * Checking build dependencies::
 * Configuring target directories::

-* Making an out-of-tree build::

 @end menu
 
 
 @node Configuration options
 @unnumberedsubsubsec Configuration options
 
 @end menu
 
 
 @node Configuration options
 @unnumberedsubsubsec Configuration options
 

-The @command{./configure} command (generated by
+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+
+The @command{../configure} command (generated by

 @command{./autogen.sh}) provides many options for configuring
 @command{make}.  To see them all, run:
 
 @example
 @command{./autogen.sh}) provides many options for configuring
 @command{make}.  To see them all, run:
 
 @example

-./configure --help
+../configure --help

 @end example
 
 
 @node Checking build dependencies
 @unnumberedsubsubsec Checking build dependencies
 
 @end example
 
 
 @node Checking build dependencies
 @unnumberedsubsubsec Checking build dependencies
 

-When @command{./configure} is run without any arguments, it will
+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+
+When @command{../configure} is run without any arguments, it will

 check to make sure your system has everything required for
 check to make sure your system has everything required for

-compilation.  This is done automatically when
-@command{./autogen.sh} is run.  If any build dependency is
-missing, @command{./configure} will return with:
+compilation:
+
+@example
+../configure
+@end example
+
+If any build dependency is missing, @command{../configure} will
+return with:

 
 @example
 ERROR: Please install required programs:  @var{foo}
 
 @example
 ERROR: Please install required programs:  @var{foo}


@@ -358,7 +374,7 @@ WARNING: Please consider installing optional programs:  @var{bar}
 If you intend to build the documentation locally, you will need to
 install or update these programs accordingly.
 
 If you intend to build the documentation locally, you will need to
 install or update these programs accordingly.
 

-@warning{@command{./configure} may fail to issue warnings for
+@warning{@command{../configure} may fail to issue warnings for

 certain documentation build requirements that are not met.  If you
 experience problems when building the documentation, you may need
 to do a manual check of @ref{Requirements for building
 certain documentation build requirements that are not met.  If you
 experience problems when building the documentation, you may need
 to do a manual check of @ref{Requirements for building


@@ -368,22 +384,25 @@ documentation}.}
 @node Configuring target directories
 @unnumberedsubsubsec Configuring target directories
 
 @node Configuring target directories
 @unnumberedsubsubsec Configuring target directories
 

+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+

 If you intend to use your local build to install a local copy of
 the program, you will probably want to configure the installation
 directory.  Here are the relevant lines taken from the output of
 If you intend to use your local build to install a local copy of
 the program, you will probably want to configure the installation
 directory.  Here are the relevant lines taken from the output of

-@command{./configure@tie{}--help}:
+@command{../configure@tie{}--help}:

 
 @quotation
 By default, `@command{make@tie{}install}' will install all the
 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc.  You
 can specify an installation prefix other than @file{/usr/local}
 
 @quotation
 By default, `@command{make@tie{}install}' will install all the
 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc.  You
 can specify an installation prefix other than @file{/usr/local}

-using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
+using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.

 @end quotation
 
 A typical installation prefix is @file{$HOME/usr}:
 
 @example
 @end quotation
 
 A typical installation prefix is @file{$HOME/usr}:
 
 @example

-./configure --prefix=$HOME/usr
+../configure --prefix=$HOME/usr

 @end example
 
 Note that if you plan to install a local build on a system where
 @end example
 
 Note that if you plan to install a local build on a system where


@@ -400,28 +419,11 @@ already included.
 
 It is also possible to specify separate installation directories
 for different types of program files.  See the full output of
 
 It is also possible to specify separate installation directories
 for different types of program files.  See the full output of

-@command{./configure@tie{}--help} for more information.
+@command{../configure@tie{}--help} for more information.

 
 If you encounter any problems, please see @ref{Problems}.
 
 
 
 If you encounter any problems, please see @ref{Problems}.
 
 

-@node Making an out-of-tree build
-@unnumberedsubsubsec Making an out-of-tree build
-
-It is possible to compile LilyPond in a build tree different from
-the source tree, using the @option{--srcdir} option of
-@command{configure}.  Note that in some cases you may need to
-remove the output of a previous @command{configure} command by
-running @command{make@tie{}distclean} in the main source directory
-before configuring the out-of-tree build:
-
-@example
-make distclean
-mkdir lily-build && cd lily-build
-@var{sourcedir}/configure --srcdir=@var{sourcedir}
-@end example
-
-

 @node Compiling LilyPond
 @section Compiling LilyPond
 
 @node Compiling LilyPond
 @section Compiling LilyPond
 


@@ -437,6 +439,9 @@ mkdir lily-build && cd lily-build
 @node Using make
 @subsection Using @command{make}
 
 @node Using make
 @subsection Using @command{make}
 

+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+

 LilyPond is compiled with the @command{make} command.  Assuming
 @command{make} is configured properly, you can simply run:
 
 LilyPond is compiled with the @command{make} command.  Assuming
 @command{make} is configured properly, you can simply run:
 


@@ -478,9 +483,9 @@ that case, running @samp{make} without the @option{-j} is advised.
 
 If you want to build multiple versions of LilyPond with different
 configuration settings, you can use the
 
 If you want to build multiple versions of LilyPond with different
 configuration settings, you can use the

-@code{--enable-config=@var{CONF}} option of @command{configure}.
-You should use @code{make@tie{}conf=@var{CONF}} to generate the
-output in @file{out-@var{CONF}}.  For example, suppose you want to
+@option{--enable-config=@var{conf}} option of @command{configure}.
+You should use @code{make@tie{}conf=@var{conf}} to generate the
+output in @file{out-@var{conf}}.  For example, suppose you want to

 build with and without profiling, then use the following for the
 normal build
 
 build with and without profiling, then use the following for the
 normal build
 


@@ -571,6 +576,7 @@ re-install.  See @ref{Configuring target directories}.
 @menu
 * Documentation editor's edit/compile cycle::
 * Building documentation::
 @menu
 * Documentation editor's edit/compile cycle::
 * Building documentation::

+* Building a single document::

 * Saving time with CPU_COUNT::
 * AJAX search::
 * Installing documentation::
 * Saving time with CPU_COUNT::
 * AJAX search::
 * Installing documentation::


@@ -599,16 +605,20 @@ Edit/compile cycle:
 make [-j@var{X}]                  @emph{## needed if editing outside}
                             @emph{##   Documentation/, but useful anyway}
                             @emph{##   for finding Texinfo errors.}
 make [-j@var{X}]                  @emph{## needed if editing outside}
                             @emph{##   Documentation/, but useful anyway}
                             @emph{##   for finding Texinfo errors.}

-touch Documentation/*te??   @emph{## bug workaround}

 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial build.}
 @end example
 
 @item
 Reset:
 
 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial build.}
 @end example
 
 @item
 Reset:
 

-@example
-make doc-clean              @emph{## use only as a last resort.}
-@end example
+In some cases, it is possible to clean the compiled documentation
+with @samp{make@tie{}doc-clean}, but this method is not guaranteed
+to fix everything.  Instead, we recommend that you delete your
+@file{build/} directory, and begin compiling from scratch.  Since
+the documentation compile takes much longer than the
+non-documentation compile, this does not increase the overall time
+by a great deal.
+

 @end itemize
 
 @node Building documentation
 @end itemize
 
 @node Building documentation


@@ -636,6 +646,25 @@ the docs.  Please do not complain about anything which is broken
 in those places; the only complete set of documentation is in
 @file{out-www/offline-root/} from the top of the source tree.
 
 in those places; the only complete set of documentation is in
 @file{out-www/offline-root/} from the top of the source tree.
 

+@code{make doc} compiles the documents for all languages.  To save
+some compile time, the English language documents can be compiled
+on their own with:
+
+@example
+make LANGS='' doc
+@end example
+
+@noindent Similarly, it is possible to compile a subset of the
+translated documentation by specifying their language codes on the
+command line.  For example, the French and German translations are
+compiled with:
+
+@example
+make LANGS='de fr' doc
+@end example
+
+@noindent Note that this will also compile the English version.
+

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


@@ -686,6 +715,33 @@ However, this will rebuild all of the manuals
 indiscriminately---it is more efficient to @command{touch} only
 the affected files.
 
 indiscriminately---it is more efficient to @command{touch} only
 the affected files.
 

+@noindent
+Another typical issue when switching branches between master and
+lilypond/translation is the appearance/disappearance of translated
+versions of some manuals.  If you see such a warning from make:
+
+@example
+No rule to make target `X', needed by `Y'
+@end example
+
+@noindent
+Your best bet is to delete the file Y.dep and to try again.
+
+@node Building a single document
+@unnumberedsubsubsec Building a single document
+It's possible to build a single document.  For example, to rebuild
+only @file{contributor.pdf}, do the following:
+
+@example
+cd build/
+cd Documentation/
+touch ../../Documentation/contributor.texi
+make out=www out-www/contributor.pdf
+@end example
+
+If you are only working on a single document, test-building it in
+this way can give substantial time savings - recreating
+@file{contributor.pdf}, for example, takes a matter of seconds.

 
 @node Saving time with CPU_COUNT
 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
 
 @node Saving time with CPU_COUNT
 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}