CG: out-of-tree building in main compile chapter.

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index 683326dd903ea46da3a7ed9b8d9268603e01567f..731aa58c0c288f09832a5d798aa7f52dfcd8bd37 100644 (file)
--- a/Documentation/included/compile.itexi
+++ b/Documentation/included/compile.itexi
@@ -282,7 +282,7 @@ download and install the free-software
 
 @menu
 * Running ./autogen.sh::
-* Running ./configure::
+* Running ../configure::
 @end menu
 
 
@@ -298,50 +298,65 @@ Next, you need to create the generated files; enter the following
 command from your top source directory:
 
 @example
-./autogen.sh
+./autogen.sh --noconfigure
 @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.
 
-@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::
-* Making an out-of-tree build::
 @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
-./configure --help
+../configure --help
 @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
-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}
@@ -357,7 +372,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.
 
-@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
@@ -367,10 +382,13 @@ documentation}.}
 @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
-@command{./configure@tie{}--help}:
+@command{../configure@tie{}--help}:
 
 @quotation
 By default, `@command{make@tie{}install}' will install all the
@@ -382,7 +400,7 @@ using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
 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
@@ -399,28 +417,11 @@ already included.
 
 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}.
 
 
-@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
 
@@ -436,6 +437,9 @@ mkdir lily-build && cd lily-build
 @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: