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

[percival . music . ca]

Reviewers: ,

Message:
Please review.

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

Please review this at http://codereview.appspot.com/3823045/

Affected files:
  M Documentation/included/compile.itexi


Index: Documentation/included/compile.itexi
diff --git a/Documentation/included/compile.itexi  
b/Documentation/included/compile.itexi
index  
683326dd903ea46da3a7ed9b8d9268603e01567f..731aa58c0c288f09832a5d798aa7f52dfcd8bd37  
100644
--- 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:
-
address@hidden
address@hidden 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.

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


address@hidden Running ./configure
address@hidden Running @command{./configure}
address@hidden Running ../configure
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden/autogen.sh} is run.  If any build dependency is
-missing, @command{./configure} will return with:
+compilation:
+
address@hidden
+../configure
address@hidden 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.

address@hidden@command{./configure} may fail to issue warnings for
address@hidden@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

address@hidden 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
address@hidden/address@hidden:
address@hidden/address@hidden:

 @quotation
 By default, address@hidden@tie{}install}' will install all the
@@ -382,7 +400,7 @@ using address@hidden', for instance  
address@hidden'.
 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
address@hidden/address@hidden for more information.
address@hidden/address@hidden for more information.

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


address@hidden Making an out-of-tree build
address@hidden 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
address@hidden  Note that in some cases you may need to
-remove the output of a previous @command{configure} command by
-running @address@hidden in the main source directory
-before configuring the out-of-tree build:
-
address@hidden
-make distclean
-mkdir lily-build && cd lily-build
address@hidden/configure address@hidden
address@hidden example
-
-
 @node Compiling LilyPond
 @section Compiling LilyPond

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

address@hidden 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: