CG: add warnings for docs to Quick start.

diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi
index a8e4e0d6befb22b51e94068e4539e8041568aaed..e0ea3f6554590272b232c0d8fa35f1bb6199080d 100644 (file)
--- a/Documentation/contributor/quick-start.itexi
+++ b/Documentation/contributor/quick-start.itexi
@@ -449,13 +449,7 @@ you bookmark the resulting page:
 firefox ~/lilypond-git/build/out-www/offline-root/index.html
 @end example
 
-@subsubheading Other options
-
-To select different build options, or isolate certain parts of the
-build, or to use multiple CPUs while building, read the rest of
-this chapter.
-
-@subsubheading Installing LilyPond with lilydev
+@subsubheading Installing
 
 Don't.  There is no reason to install lilypond within lilydev.
 All development work can (and should) stay within the
@@ -463,6 +457,17 @@ All development work can (and should) stay within the
 or typesetting work should be done with an official GUB release.
 
 
+@subsubheading Problems and other options
+
+To select different build options, or isolate certain parts of the
+build, or to use multiple CPUs while building, read
+@ref{Compiling}.
+
+In particular, contributors working on the documentation should be
+aware of some bugs in the build system, and should read the
+workarounds in @ref{Generating documentation}.
+
+
 @node Now start work!
 @section Now start work!
 

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index 731aa58c0c288f09832a5d798aa7f52dfcd8bd37..c05e013f5d79ff0a0968c81a51d84b4838ae2da8 100644 (file)
--- a/Documentation/included/compile.itexi
+++ b/Documentation/included/compile.itexi
@@ -609,9 +609,14 @@ make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial bui
 @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