X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fincluded%2Fcompile.itexi;h=76bd48cd2f747821a5487f4ccb73a4c9f90775d9;hb=a1267e20afa61258ce3031f07d916e0e66ac6582;hp=b2dcf7fdb737d5bd161173ebe9e670df1f083dba;hpb=7eb9c626943a47141ec2cc5fad7723f69e04bbd2;p=lilypond.git

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index b2dcf7fdb7..76bd48cd2f 100644
--- 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
 
-
 @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
-@rcontrib{Lilybuntu}).
+@rcontrib{LilyDev}).
 
 
 @node Requirements
@@ -61,165 +60,577 @@ unsuccessful, though a workaround is available (see
 @node Requirements for running LilyPond
 @subsection Requirements for running LilyPond
 
-Running LilyPond requires proper installation of the following
-software:
+This section contains the list of separate software packages that are
+required to run LilyPond.
 
 @itemize
-@item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} (normally
-installed by default)
 
-@item @uref{http://www.fontconfig.org/, FontConfig} (2.4.0 or newer)
+@item @uref{http://www.dejavu-fonts.org/, DejaVu fonts}
+These are normally installed by default.
+
+@item
+@uref{http://www.fontconfig.org/, FontConfig}
+Use version 2.4.0 or newer.
+
+@item
+@uref{http://www.freetype.org/, Freetype}
+Use version 2.1.10 or newer.
 
-@item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer)
+@item
+@uref{http://www.ghostscript.com, Ghostscript}
+Use version 8.60 or newer.
 
-@item @uref{http://www.ghostscript.com, Ghostscript} (8.60 or
-newer)
+@item
+@uref{http://www.gnu.org/software/guile/guile.html, Guile}
+Use version 1.8.8. Version 2.x of Guile is not currently supported.
 
-@item @uref{http://www.gnu.org/software/guile/guile.html, Guile}
-(1.8.2 or newer)
+@item
+@uref{http://www.pango.org/, Pango}
+User version 1.12 or newer.
 
-@item @uref{http://www.pango.org/, Pango} (1.12 or newer)
+@item
+@uref{http://www.python.org, Python}
+Use version 2.4 or newer.
 
-@item @uref{http://www.python.org, Python} (2.4 or newer)
-@end itemize
+@item
+International fonts.  For example:
+
+Fedora:
+
+@example
+fonts-arabic
+fonts-hebrew
+fonts-ja
+fonts-xorg-truetype
+taipeifonts
+ttfonts-ja
+ttfonts-zh_CN
+@end example
 
-International fonts are required to create music with
-international text or lyrics.
+Debian based distributions:
+
+@example
+emacs-intl-fonts
+fonts-ipafont-gothic
+fonts-ipafont-mincho
+xfonts-bolkhov-75dpi
+xfonts-cronyx-75dpi
+xfonts-cronyx-100dpi
+xfonts-intl-.*
+@end example
+
+These are normally installed by default and are required only to create
+music with international text or lyrics.
+
+@end itemize
 
 
 @node Requirements for compiling LilyPond
 @subsection Requirements for compiling LilyPond
 
-Below is a full list of packages needed to build LilyPond.
-However, for most common distributions there is an easy way of
-installing most all build dependencies in one go:
+This section contains instructions on how to quickly and easily get all
+the software packages required to build LilyPond.
+
+Most of the more popular Linux distributions only require a few simple
+commands to download all the software needed.  For others, there is an
+explicit list of all the individual packages (as well as where to get
+them from) for those that are not already included in your
+distributions' own repositories.
+
+@ignore
+I have tested all of the following four Linux Distributions listed here
+Using a simple virtual machine and the appropriate ISO image file
+downloaded from each distribution's own website.  The instructions
+documented were run immediately after the initial installation
+(without any further additional configuration to the OS) and I made sure
+that I was able to run the full set of make, make test-baseline, make
+check and a full make doc. - James
+@end ignore
+
+@menu
+* Fedora::
+* Linux Mint::
+* OpenSUSE::
+* Ubuntu::
+* Other::
+@end menu
+
+
+@node Fedora
+@unnumberedsubsubsec Fedora
+
+The following instructions were tested on @q{Fedora} versions 22 & 23
+and will download all the software required to both compile LilyPond and
+build the documentation.
+
+@itemize
+
+@item
+Download and install all the LilyPond build-dependencies (approximately
+700MB);
+
+@example
+sudo dnf builddep lilypond --nogpgcheck
+@end example
+
+@item
+Download and install additional @q{build} tools required for compiling;
+
+@example
+sudo dnf install autoconf gcc-c++
+@end example
+
+@item
+Download @code{texi2html 1.82} directly from:
+@uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
+
+@code{texi2html} is only required if you intend to compile LilyPond's
+own documentation (e.g. to help with any document writing).  The version
+available in the Fedora repositories is too new and will not work.
+Extract the files into an appropriate location and then run the
+commands;
+
+@example
+./configure
+make
+sudo make install
+@end example
+
+This should install @code{texi2html 1.82} into @code{/usr/local/bin},
+which will normally take priority over @code{/usr/bin} where the
+later, pre-installed versions gets put.  Now verify that your operating
+system is able to see the correct version of @code{texi2html}.
+
+@example
+texi2html --version
+@end example
+
+@item
+Although not @q{required} to compile LilyPond, if you intend to
+contribute to LilyPond (codebase or help improve the documentation) then
+it is recommended that you also need to install @code{git}.
+
+@example
+sudo dnf install git
+@end example
+
+Also see @ruser{Starting with Git}.
+
+@item
+To use the @code{lily-git.tcl} GUI;
+
+@example
+sudo dnf install tk
+@end example
+
+See @ruser{lily-git}.
+
+@end itemize
+
+@warning{By default, when building LilyPond's documentation,
+@code{pdfTeX} is be used.  However ligatures (fi, fl, ff etc.) may not
+be printed in the PDF output.  In this case XeTeX can be used instead.
+Download and install the @code{texlive-xetex} package.
+
+@example
+sudo dnf install texlive-xetex
+@end example
+
+The scripts used to build the LilyPond documentation will use
+@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
+it is available.  No additional configuration is required.}
+
+
+
+@node Linux Mint
+@unnumberedsubsubsec Linux Mint
+
+The following instructions were tested on @q{Linux Mint 17.1} and
+@q{LMDE - Betsy} and will download all the software required to both
+compile LilyPond and build the documentation..
+
+@itemize
+
+@item
+Enable the @emph{sources} repository;
+
+@enumerate
+
+@item
+Using the @emph{Software Sources} GUI (located under
+@emph{Administration}).
+
+@item
+Select @emph{Official Repositories}.
+
+@item
+Check the @emph{Enable source code repositories} box under the
+@emph{Source Code} section.
+
+@item
+Click the @emph{Update the cache} button and when it has completed,
+close the @emph{Software Sources} GUI.
+
+@end enumerate
+
+@item
+Download and install all the LilyPond build-dependencies (approximately
+200MB);
+
+@example
+sudo apt-get build-dep lilypond
+@end example
+
+@item
+Download and install additional @q{build} tools required for compiling;
+
+@example
+sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
+@end example
+
+@item
+Although not @q{required} to compile LilyPond, if you intend to
+contribute to LilyPond (codebase or help improve the documentation) then
+it is recommended that you also need to install @code{git}.
+
+@example
+sudo apt-get install git
+@end example
+
+Also see @ruser{Starting with Git}.
+
+@item
+To use the @code{lily-git.tcl} GUI;
+
+@example
+sudo apt-get install tk
+@end example
+
+Also see @ruser{lily-git}.
+
+@end itemize
+
+@warning{By default, when building LilyPond's documentation,
+@code{pdfTeX} is be used.  However ligatures (fi, fl, ff etc.) may not
+be printed in the PDF output.  In this case XeTeX can be used instead.
+Download and install the @code{texlive-xetex} package.
+
+@example
+sudo apt-get install texlive-xetex
+@end example
+
+The scripts used to build the LilyPond documentation will use
+@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
+it is available.  No additional configuration is required.}
+
+
+@node OpenSUSE
+@unnumberedsubsubsec OpenSUSE
+
+The following instructions were tested on @q{OpenSUSE 13.2} and will
+download all the software required to both compile LilyPond and build
+the documentation.
+
+@itemize
+
+@item
+Add the @emph{sources} repository;
+
+@smallexample
+sudo zypper addrepo -f \
+"http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
+@end smallexample
+
+@item
+Download and install all the LilyPond build-dependencies (approximately
+680MB);
+
+@example
+sudo zypper source-install lilypond
+@end example
+
+@item
+Download and install additional @q{build} tools required for compiling;
+
+@example
+sudo zypper install make
+@end example
+
+@item
+Although not @q{required} to compile LilyPond, if you intend to
+contribute to LilyPond (codebase or help improve the documentation) then
+it is recommended that you also need to install @code{git}.
+
+@example
+sudo zypper install git
+@end example
+
+Also see @ruser{Starting with Git}.
+
+@item
+To use the @code{lily-git.tcl} GUI;
 
-@multitable @columnfractions .5 .5
-@headitem Distribution @tab Command
-@item Debian, Ubuntu
-@tab @code{sudo apt-get build-dep lilypond}
+@example
+sudo zypper install tk
+@end example
 
-@item Fedora, RHEL
-@tab @code{sudo yum-builddep lilypond}
+Also see @ruser{lily-git}.
+
+@end itemize
 
-@item openSUSE, SLED
-@c sorry for the idiosyncratic command, I really asked and argued
-@c for "zypper build-dep" :-(
-@tab @code{sudo zypper --build-deps-only source-install lilypond}
-@end multitable
+@warning{By default, when building LilyPond's documentation,
+@code{pdfTeX} is be used.  However ligatures (fi, fl, ff etc.) may not
+be printed in the PDF output.  In this case XeTeX can be used instead.
+Download and install the @code{texlive-xetex} package.
+
+@example
+sudo zypper install texlive-xetex
+@end example
+
+The scripts used to build the LilyPond documentation will use
+@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
+it is available.  No additional configuration is required.}
+
+@node Ubuntu
+@unnumberedsubsubsec Ubuntu
+
+The following commands were tested on Ubuntu versions @code{14.04 LTS},
+@code{14.10} and @code{15.04} and will download all the software
+required to both compile LilyPond and build the documentation.
 
 @itemize
-@item Everything listed in @ref{Requirements for running
-LilyPond}
 
-@item Development packages for the above items (which should
-include header files and libraries).
+@item
+Download and install all the LilyPond build-dependencies (approximately
+200MB);
+
+@example
+sudo apt-get build-dep lilypond
+@end example
+
+@item
+Download and install additional @q{build} tools required for compiling;
+
+@example
+sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
+@end example
 
-Red Hat Fedora:
+@item
+Although not @q{required} to compile LilyPond, if you intend to
+contribute to LilyPond (codebase or help improve the documentation) then
+it is recommended that you also need to install @code{git}.
 
-@c ghostscript-devel-[version] isn't needed
 @example
-guile-devel-@var{version}
-fontconfig-devel-@var{version}
-freetype-devel-@var{version}
-pango-devel-@var{version}
-python-devel-@var{version}
+sudo apt-get install git
 @end example
 
-Debian GNU/Linux:
+Also see @ruser{Starting with Git}.
+
+@item
+To use the @code{lily-git.tcl} GUI;
 
-@c libgs-dev isn't needed
 @example
-guile-@var{version}-dev
-libfontconfig1-dev
-libfreetype6-dev
-libpango1.0-dev
-python@var{version}-dev
+sudo apt-get install tk
 @end example
 
-@item @uref{http://flex.sourceforge.net/, Flex}
+Also see @ruser{lily-git}.
+
+@end itemize
+
+@warning{By default, when building LilyPond's documentation,
+@code{pdfTeX} is be used.  However ligatures (fi, fl, ff etc.) may not
+be printed in the PDF output.  In this case XeTeX can be used instead.
+Download and install the @code{texlive-xetex} package.
+
+@example
+sudo apt-get install texlive-xetex
+@end example
+
+The scripts used to build the LilyPond documentation will use
+@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
+it is available.  No additional configuration is required.}
+
+
+@node Other
+@unnumberedsubsubsec Other
+
+The following individual software packages are required just to compile
+LilyPond.
 
-@item @uref{http://fontforge.sf.net/, FontForge} (20060125 or
-newer)
+@itemize
+
+@item
+@uref{http://www.gnu.org/software/autoconf, GNU Autoconf}
+
+@item
+@uref{http://www.gnu.org/software/bison/, GNU Bison}
 
-@item @uref{http://www.gnu.org/software/bison/, GNU Bison}
+Use version @code{2.0} or newer.
 
-@item @uref{http://gcc.gnu.org/, GNU Compiler Collection} (3.4 or
-newer, 4.@var{x} recommended)
+@item
+@uref{http://gcc.gnu.org/, GNU Compiler Collection}
+
+Use version @code{3.4} or newer (@code{4.x} recommended).
 
-@item @uref{http://www.gnu.org/software/gettext/gettext.html, GNU
-gettext} (0.17 or newer)
+@item
+@uref{http://flex.sourceforge.net/, Flex}
+
+@item
+@uref{http://fontforge.sf.net/, FontForge}
 
-@item @uref{http://www.gnu.org/software/make/, GNU Make} (3.78 or
-newer)
+Use version @code{20060125} or newer (we recommend using at least
+@code{20100501}); it must also be compiled with the
+@option{--enable-double} switch, else this can lead to inaccurate
+intersection calculations which end up with poorly-rendered glyphs in
+the output.
 
-@item @uref{http://metafont.tutorial.free.fr/, MetaFont}
-(mf-nowin, mf, mfw or mfont binaries), usually packaged with
+@item
+@uref{http://www.gnu.org/software/gettext/gettext.html, GNU gettext}
+
+Use version @code{0.17} or newer.
+
+@item
+@uref{http://www.gnu.org/software/make/, GNU Make}
+
+Use version @code{3.78} or newer.
+
+@item
+@uref{http://metafont.tutorial.free.fr/, MetaFont}
+
+The @code{mf-nowin}, @code{mf}, @code{mfw} or @code{mfont} binaries are
+usually packaged along with
 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
 
-@item @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,
-MetaPost} (mpost binary), usually packaged with
+@item
+@uref{http://cm.bell-labs.com/who/hobby/MetaPost.html, MetaPost}
+
+The @code{mpost} binary is also usually packaged with
 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
 
-@item @uref{http://www.perl.org/, Perl}
+@item
+@uref{http://www.perl.org/, Perl}
+
+@item
+@uref{http://www.gnu.org/software/texinfo/, Texinfo}
+
+Use version @code{4.11} or newer.
+
+@item
+@uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1 utilities}
+
+Use version @code{1.33} or newer.
+
+@item
+@uref{https://www.ctan.org/pkg/cyrillic?lang=en, Cyrillic fonts}
 
-@item @uref{http://www.gnu.org/software/texinfo/, Texinfo} (4.11
-or newer)
+Often packaged in repositories as @code{texlive-lang-cyrillic}.
+
+@item
+TeX Gyre @q{OTF} font packages.  As of LilyPond version @code{2.19.26},
+the previous default serif, san serif and monospace fonts now use Tex
+Gyre's @emph{Schola}, @emph{Heros} and @emph{Cursor} fonts respectively.
+Also See @ruser{Fonts}.
+
+Some distributions do not always provide @q{OTF} font files in the Tex
+Gyre packages from their repositories.  Use the command
+@code{fc-list | grep texgyre} to list the fonts available to your system
+and check that the appropriate @code{*.otf} files are reported.  If they
+are not then download and manually extract the @q{OTF} files to either
+your local  @code{~/.fonts/} directory or use the
+@code{configure} command and the
+@code{--with-texgyre-dir=/path_to_otf_files/} option.
+
+The following font families are required:
+
+@uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola, Schola},
+@uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros, Heros}
+and
+@uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor, Cursor}.
 
-@item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1
-utilities} (1.33 or newer recommended)
 @end itemize
 
 
+
 @node Requirements for building documentation
 @subsection Requirements for building documentation
 
-You can view the documentation online at
-@uref{http://www.lilypond.org/doc/}, but you can also build it
-locally.  This process requires some additional tools and
-packages:
+The entire set of documentation for the most current build of LilyPond
+is available online at
+@uref{http://lilypond.org/doc/v2.19/Documentation/web/development}, but
+you can also build them locally from the source code.  This process
+requires some additional tools and packages.
+
+@warning{If the instructions for one of the previously listed Linux
+in the previous section (@rcontrib{Requirements for compiling LilyPond})
+have been used, then the following can be ignored as the software should
+already be installed.}
 
 @itemize
-@item Everything listed in @ref{Requirements for compiling
-LilyPond}
 
-@item @uref{http://www.imagemagick.org/, ImageMagick}
+@item
+Everything listed in @ref{Requirements for compiling LilyPond}
 
-@item @uref{http://netpbm.sourceforge.net/, Netpbm}
+@item
+@uref{http://www.imagemagick.org/, ImageMagick}
 
-@item @uref{http://gzip.org/, gzip}
+@item
+@uref{http://netpbm.sourceforge.net/, Netpbm}
 
-@item @uref{http://rsync.samba.org/, rsync}
+@item
+@uref{http://gzip.org/, gzip}
 
-@item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82)
+@item
+@uref{http://rsync.samba.org/, rsync}
 
-@item International fonts
+@item
+@uref{http://www.nongnu.org/texi2html/, Texi2HTML}
+
+Use version @code{1.82}.  Later versions will not work.
+
+Download @code{texi2html 1.82} directly from:
+@uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
 
-Red Hat Fedora:
+Extract the files into an appropriate location and then run the
+commands;
 
 @example
-fonts-arabic
-fonts-hebrew
-fonts-ja
-fonts-xorg-truetype
-taipeifonts
-ttfonts-ja
-ttfonts-zh_CN
+./configure
+make
+sudo make install
 @end example
 
-Debian GNU/Linux:
+Now verify that your operating system is able to see the correct version
+of @code{texi2html}.
 
 @example
-emacs-intl-fonts
-ttf-kochi-gothic
-ttf-kochi-mincho
-xfonts-bolkhov-75dpi
-xfonts-cronyx-75dpi
-xfonts-cronyx-100dpi
-xfonts-intl-.*
+texi2html --version
+@end example
+
+@item
+Fonts required to build the documentation in addition to those required
+to run LilyPond:
+
+@example
+gsfonts
+fonts-linuxlibertine
+fonts-liberation
+fonts-dejavu
+fonts-freefont-otf
+ttf-bitstream-vera
+texlive-fonts-recommended
+ttf-xfree86-nonfree
 @end example
+
 @end itemize
 
+@warning{By default, when building LilyPond's documentation,
+@code{pdfTeX} is be used.  However ligatures (fi, fl, ff etc.) may not
+be printed in the PDF output.  In this case XeTeX can be used instead.
+Download and install the @code{texlive-xetex} package. The scripts used
+to build the LilyPond documentation will use @code{XeTex} instead of
+@code{pdfTex} to generate the PDF documents if it is available.  No
+additional configuration is required.}
+
 
 @node Getting the source code
 @section Getting the source code
@@ -253,12 +664,12 @@ here:
 @uref{http://download.linuxaudio.org/lilypond/source/}
 @end example
 
-Download the tarball to your @file{@/~/@/src/} directory, or some
+Download the tarball to your @file{~/src/} directory, or some
 other appropriate place.
 
 @warning{Be careful where you unpack the tarball!  Any
 subdirectories of the current folder named @file{lilypond/} or
-@file{lilypond@/-@var{x.y.z}/} (where @var{x.y.z} is the release
+@file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release
 number) will be overwritten if there is a name clash with the
 tarball.}
 
@@ -269,7 +680,7 @@ tar -xzf lilypond-@var{x.y.z}.tar.gz
 @end example
 
 This creates a subdirectory within the current directory called
-@file{lilypond@/-@var{x.y.z}/}.  Once unpacked, the source files
+@file{lilypond-@var{x.y.z}/}.  Once unpacked, the source files
 occupy about 40 MB of disk space.
 
 Windows users wanting to look at the source code may have to
@@ -283,7 +694,7 @@ download and install the free-software
 
 @menu
 * Running ./autogen.sh::
-* Running ./configure::
+* Running ../configure::
 @end menu
 
 
@@ -299,50 +710,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:
+This will generate a number of files and directories to aid
+configuration, such as @file{configure}, @file{README.txt}, etc.
 
-@enumerate
-@item generate a number of files and directories to aid
-configuration, such as @file{configure}, @file{README@/.txt}, etc.
+Next, create the build directory with:
 
-@item automatically run the @command{./configure} command.
-@end enumerate
+@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}
@@ -358,7 +784,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
@@ -368,22 +794,25 @@ 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
-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}'.
+files in @file{/usr/local/bin}, @file{/usr/local/lib} etc.  You
+can specify an installation prefix other than @file{/usr/local}
+using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.
 @end quotation
 
-A typical installation prefix is @file{$HOME/@/usr}:
+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
@@ -394,34 +823,17 @@ write permission (such as your home directory).  The installation
 directory will be automatically created if necessary.
 
 The location of the @command{lilypond} command installed by this
-process will be @file{@var{prefix}/@/bin/@/lilypond}; you may want to
-add @file{@var{prefix}/@/bin/} to your @code{$PATH} if it is not
+process will be @file{@var{prefix}/bin/lilypond}; you may want to
+add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
 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
 
@@ -437,6 +849,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:
 
@@ -453,6 +868,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
@@ -478,9 +897,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
-@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
 
@@ -515,7 +934,7 @@ make conf=prof install
 
 If a less verbose build output if desired, the variable
 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
-command line, or in @file{local@/.make} at top of the build tree.
+command line, or in @file{local.make} at top of the build tree.
 
 
 @node Post-compilation options
@@ -543,7 +962,7 @@ make install
 @end example
 
 If instead, your installation directory is not one that you can
-normally write to (such as the default @file{/@/usr/@/local/}, which
+normally write to (such as the default @file{/usr/local/}, which
 typically is only writeable by the superuser), you will need to
 temporarily become the superuser when running
 @command{make@tie{}install}:
@@ -553,7 +972,7 @@ sudo make install
 @end example
 
 @noindent
-or...
+or@dots{}
 
 @example
 su -c 'make install'
@@ -571,6 +990,7 @@ re-install.  See @ref{Configuring target directories}.
 @menu
 * Documentation editor's edit/compile cycle::
 * Building documentation::
+* Building a single document::
 * Saving time with CPU_COUNT::
 * AJAX search::
 * Installing documentation::
@@ -587,28 +1007,35 @@ 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
 Edit/compile cycle:
 
 @example
-@emph{## edit source files, then...}
+@emph{## edit source files, then@dots{}}
 
 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:
 
-@example
-make doc-clean              @emph{## use only as a last resort.}
-@end example
+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
+by a great deal.
+
 @end itemize
 
 @node Building documentation
@@ -621,71 +1048,94 @@ 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
+is available in @file{out-www/offline-root/}, and can be browsed
 locally.  Various portions of the documentation can be found by
-looking in @file{out/} and @file{out@/-www} subdirectories in other
+looking in @file{out/} and @file{out-www} subdirectories in other
 places in the source tree, but these are only @emph{portions} of
 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.
+@file{out-www/offline-root/} from the top of the source tree.
 
-Compilation of documentation in Info format with images can be
-done separately by issuing:
+@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 info
+make log-clean
 @end example
 
-@knownissues
+@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:
 
-If source files have changed since the last documentation build,
-output files that need to be rebuilt are normally rebuilt, even if
-you do not run @code{make@tie{}doc-clean} first.  However, build
-dependencies in the documentation are so complex that some
-newly-edited files may not be rebuilt as they should be; a
-workaround is to @command{touch} the top source file for any
-manual you've edited.  For example, if you make changes to a file
-in @file{notation/}, do:
+@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
-touch Documentation/notation.tely
+make LANGS='de fr' doc
 @end example
 
-@noindent
-The top sources possibly affected by this are:
+@noindent Note that this will also compile the English version.
+
+Compilation of documentation in Info format with images can be
+done separately by issuing:
 
 @example
-Documentation/extend.texi
-Documentation/changes.tely
-Documentation/contributor.texi
-Documentation/essay.tely
-Documentation/extending.tely
-Documentation/learning.tely
-Documentation/notation.tely
-Documentation/snippets.tely
-Documentation/usage.tely
-Documentation/web.texi
+make info
 @end example
 
 @noindent
-You can @command{touch} all of them at once with:
+An issue when switching branches between master and translation
+is the appearance/disappearance of translated versions of some manuals.
+If you see such a warning from make:
 
 @example
-touch Documentation/*te??
+No rule to make target `X', needed by `Y'
 @end example
 
 @noindent
-However, this will rebuild all of the manuals
-indiscriminately---it is more efficient to @command{touch} only
-the affected files.
+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}
@@ -695,7 +1145,7 @@ running LilyPond to build images of music, and there cannot be
 several simultaneously running @command{lilypond-book} instances,
 so the @option{-j} @command{make} option does not significantly
 speed up the build process.  To help speed it up, the makefile
-variable @option{CPU_COUNT} may be set in @file{local@/.make} or on
+variable @option{CPU_COUNT} may be set in @file{local.make} or on
 the command line to the number of @code{.ly} files that LilyPond
 should process simultaneously, e.g. on a bi-processor or dual core
 machine:
@@ -758,12 +1208,12 @@ make install-info
 @noindent
 Note that to get the images in Info documentation, @code{install-doc}
 target creates symbolic links to HTML and PDF installed documentation
-tree in @file{@var{prefix}/@/share/@/info}, in order to save disk space,
+tree in @file{@var{prefix}/share/info}, in order to save disk space,
 whereas @code{install-info} copies images in
-@file{@var{prefix}/@/share/@/info} subdirectories.
+@file{@var{prefix}/share/info} subdirectories.
 
 It is possible to build a documentation tree in
-@file{out@/-www/@/online@/-root/}, with special processing, so it can be
+@file{out-www/online-root/}, with special processing, so it can be
 used on a website with content negotiation for automatic language
 selection; this can be achieved by issuing
 
@@ -817,10 +1267,10 @@ Please note that this may break sometimes -- for example, if a new
 feature is added with a test file in input/regression, even the latest
 development release of LilyPond will fail to build the docs.
 
-You may build the manual without building all the @file{input/@/@/*} stuff
+You may build the manual without building all the @file{input/*} stuff
 (i.e. mostly regression tests): change directory, for example to
 @file{Documentation/}, issue @code{make doc}, which will build
-documentation in a subdirectory @file{out@/-www} from the source files in
+documentation in a subdirectory @file{out-www} from the source files in
 current directory.  In this case, if you also want to browse the
 documentation in its post-processed form, change back to top directory
 and issue
@@ -882,22 +1332,8 @@ bug reports to @email{bug-lilypond@@gnu.org}.
 
 Bugs that are not fault of LilyPond are documented here.
 
-@unnumberedsubsubsec Bison 1.875
-
-There is a bug in bison-1.875: compilation fails with "parse error
-before `goto'" in line 4922 due to a bug in bison.  To fix, please
-recompile bison 1.875 with the following fix
-
-@example
-$ cd lily; make out/parser.cc
-$ vi +4919 out/parser.cc
-# append a semicolon to the line containing "__attribute__ ((__unused__))
-# save
-$ make
-@end example
-
 
-@unnumberedsubsubsec Compiling on MacOS@tie{}X
+@unnumberedsubsec Compiling on MacOS@tie{}X
 
 Here are special instructions for compiling under MacOS@tie{}X.
 These instructions assume that dependencies are installed using
@@ -915,7 +1351,7 @@ export PATH=/opt/local/bin:/opt/local/sbin:$PATH
 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
 @end example
 
-Now you must edit the generated @file{config@/.make} file.  Change
+Now you must edit the generated @file{config.make} file.  Change
 
 @example
 FLEXLEXER_FILE = /usr/include/FlexLexer.h
@@ -945,16 +1381,16 @@ Now run the @code{./configure} script.  To avoid complications with
 automatic font detection, add
 
 @example
---with-ncsb-dir=/opt/local/share/ghostscript/fonts
+--with-fonts-dir=/opt/local/share/ghostscript/fonts
 @end example
 
 
-@unnumberedsubsubsec Solaris
+@unnumberedsubsec Solaris
 
 Solaris7, ./configure
 
-@file{@/./@/configure} needs a POSIX compliant shell.  On Solaris7,
-@file{/@/bin/@/sh} is not yet POSIX compliant, but @file{/@/bin/@/ksh} or bash
+@file{./configure} needs a POSIX compliant shell.  On Solaris7,
+@file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 is.  Run configure like
 
 @example
@@ -968,12 +1404,12 @@ or
 CONFIG_SHELL=/bin/bash bash -c ./configure
 @end example
 
-@unnumberedsubsubsec FreeBSD
+@unnumberedsubsec FreeBSD
 
 To use system fonts, dejaview must be installed.  With the default
-port, the fonts are installed in @file{usr/@/X11R6/@/lib/@/X11/@/fonts/@/dejavu}.
+port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 
-Open the file @file{$LILYPONDBASE/@/usr/@/etc/@/fonts/@/local@/.conf} and add the
+Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 for your hierarchy.)
 
@@ -982,7 +1418,7 @@ for your hierarchy.)
 @end example
 
 
-@unnumberedsubsubsec International fonts
+@unnumberedsubsec International fonts
 
 On Mac OS X, all fonts are installed by default.  However, finding all
 system fonts requires a bit of configuration; see
@@ -1004,17 +1440,17 @@ Red Hat Fedora
 Debian GNU/Linux
 
    apt-get install emacs-intl-fonts xfonts-intl-.* \
-        ttf-kochi-gothic ttf-kochi-mincho \
+        fonts-ipafont-gothic  fonts-ipafont-mincho \
         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 @end verbatim
 
 
-@unnumberedsubsubsec Using lilypond python libraries
+@unnumberedsubsec Using lilypond python libraries
 
 If you want to use lilypond's python libraries (either running
 certain build scripts manually, or using them in other programs),
-set @code{PYTHONPATH} to @file{python/@/out} in your build
-directory, or @file{@/.@/.@/./@/usr/@/lib/@/lilypond/@/current/@/python} in the
+set @code{PYTHONPATH} to @file{python/out} in your build
+directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the
 installation directory structure.
 
 
@@ -1083,7 +1519,7 @@ We currently use make and stepmake, which is complicated and only
 used by us.  Hopefully this will change in the future.
 
 
-@subsubheading Version-specific texinfo macros
+@subheading Version-specific texinfo macros
 
 @itemize
 
@@ -1093,7 +1529,7 @@ made with @command{scripts/build/create-version-itexi.py} and@*
 
 @item
 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
-website (made with @file{website@/.make}, used on lilypond.org)
+website (made with @file{website.make}, used on lilypond.org)
 
 @item
 not (?) used in the main docs?