Thinko to Issue 2629: remove paragraph no longer needed in the CG

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

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index 9b99b766fa4a5d2399df781ec7b6ca918e3a3371..eb24c591807cdecbf7ab1df8e0d1a72ce6fa0bb3 100644 (file)
--- a/Documentation/included/compile.itexi
+++ b/Documentation/included/compile.itexi
@@ -458,6 +458,10 @@ make help
 
 TODO: Describe what @command{make} actually does.
 
+@seealso
+@ref{Generating documentation} provides more info on the @command{make} targets
+used to build the LilyPond documentation.
+
 
 @node Saving time with the -j option
 @subsection Saving time with the @option{-j} option
@@ -593,7 +597,8 @@ Initial documentation build:
 
 @example
 make [-j@var{X}]
-make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## can take an hour or more}
+make [-j@var{X} CPU_COUNT=@var{X}] doc          @emph{## can take an hour or more}
+make [-j@var{X} CPU_COUNT=@var{X}] doc-stage-1  @emph{## to build only PDF documentation}
 @end example
 
 @item
@@ -611,9 +616,11 @@ make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial bui
 @item
 Reset:
 
-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
+It is generally possible to remove the compiled documentation from
+your system
+with @samp{make@tie{}doc-clean}, but this method is not 100%
+guaranteed.  Instead, if you want to be sure you have a clean
+system, 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
@@ -631,11 +638,20 @@ documentation can be built by issuing:
 make doc
 @end example
 
-The first time you run @command{make@tie{}doc}, the process can
-easily take an hour or more.  After that, @command{make@tie{}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.
+or, to build only the PDF documentation and not the HTML,
+
+@example
+make doc-stage-1
+@end example
+
+@warning{The first time you run @command{make@tie{}doc}, the
+process can easily take an hour or more with not much output
+on the command line.}
+
+After this initial build, @command{make@tie{}doc} only makes
+changes to the documentation where needed, so it may only take
+a minute or two to test changes if the documentation is already
+built.
 
 If @command{make@tie{}doc} succeeds, the HTML documentation tree
 is available in @file{out-www/offline-root/}, and can be browsed
@@ -646,9 +662,20 @@ 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.
 
-@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:
+@command{make@tie{}doc} sends the output from most of the
+compilation to logfiles.  If the build fails for any reason, it
+should prompt you with the name of a logfile which will provide
+information to help you work out why the build failed.  These
+logfiles are not deleted with @command{make@tie{}doc-clean}.  To
+remove all the logfiles generated by the compilation process, use:
+
+@example
+make log-clean
+@end example
+
+@code{make@tie{}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