Issue 4884: Remove DECLARE_* translator callback macros

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

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index 67fee8e2075d061321584beed35a317998145ae1..76bd48cd2f747821a5487f4ccb73a4c9f90775d9 100644 (file)
--- a/Documentation/included/compile.itexi
+++ b/Documentation/included/compile.itexi
@@ -8,7 +8,6 @@
 @c   @s ection Compiling from source
 
 @menu
 @c   @s ection Compiling from source
 
 @menu

-* Compiling with lilybuntu::

 * Overview of compiling::
 * Requirements::
 * Getting the source code::
 * Overview of compiling::
 * Requirements::
 * Getting the source code::


@@ -21,284 +20,617 @@
 @end menu
 
 
 @end menu
 
 

-@node Compiling with lilybuntu
-@section Compiling with lilybuntu
+@node Overview of compiling
+@section Overview of compiling
+
+Compiling LilyPond from source is an involved process, and is only
+recommended for developers and packagers.  Typical program users
+are instead encouraged to obtain the program from a package
+manager (on Unix) or by downloading a precompiled binary
+configured for a specific operating system.  Pre-compiled binaries
+are available on the @rweb{Download} page.
+
+Compiling LilyPond from source is necessary if you want to build,
+install, or test your own version of the program.

 
 

-Lilybuntu is our @q{remix} of Ubuntu which contains all the
-necessary dependencies to do lilypond development; for more
-information, see @rcontrib{Lilybuntu}.
+A successful compile can also be used to generate and install the
+documentation, incorporating any changes you may have made.
+However, a successful compile is not a requirement for generating
+the documentation.  The documentation can be built using a Git
+repository in conjunction with a locally installed copy of the
+program.  For more information, see @ref{Building documentation
+without compiling}.
+
+Attempts to compile LilyPond natively on Windows have been
+unsuccessful, though a workaround is available (see
+@rcontrib{LilyDev}).

 
 

-@subsubheading Preparing the build

 
 

-To prepare the build directory, enter (or copy&paste) the below
-text.  This should take less than a minute.
+@node Requirements
+@section Requirements
+
+
+@menu
+* Requirements for running LilyPond::
+* Requirements for compiling LilyPond::
+* Requirements for building documentation::
+@end menu
+
+
+@node Requirements for running LilyPond
+@subsection Requirements for running LilyPond
+
+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}
+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.ghostscript.com, Ghostscript}
+Use version 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.pango.org/, Pango}
+User version 1.12 or newer.
+
+@item
+@uref{http://www.python.org, Python}
+Use version 2.4 or newer.
+
+@item
+International fonts.  For example:
+
+Fedora:

 
 @example
 
 @example

-cd ~/lilypond-git/
-sh autogen.sh --noconfigure
-mkdir -p build/
-cd build/
-../configure
+fonts-arabic
+fonts-hebrew
+fonts-ja
+fonts-xorg-truetype
+taipeifonts
+ttfonts-ja
+ttfonts-zh_CN
+@end example
+
+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
 
 @end example
 

-@advanced{this is called an @qq{out-of-tree} build; we heavily
-recommend this build method.}
+These are normally installed by default and are required only to create
+music with international text or lyrics.

 
 

-@subsubheading Building @code{lilypond}
+@end itemize

 
 

-Compiling lilypond will likely take between 5 and 30 minutes,
-depending on your computer's speed and available RAM.  We
-recommend that you minimize the terminal window while it is
-building; this can have a non-negligible effect on compilation
-speed.
+
+@node Requirements for compiling LilyPond
+@subsection Requirements for compiling LilyPond
+
+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
 
 @example

-cd ~/lilypond-git/build/
+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
 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
 
 @end example
 

-You may run the compiled @code{lilypond} with:
+@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
 
 @example

-cd ~/lilypond-git/build/
-out/bin/lilypond my-file.ly
+sudo dnf install git

 @end example
 
 @end example
 

-@subsubheading Building the documentation
+Also see @ruser{Starting with Git}.

 
 

-Compiling the documentation is a much more involved process, and
-will likely take 45 minutes to 4 hours.
+@item
+To use the @code{lily-git.tcl} GUI;

 
 @example
 
 @example

-cd ~/lilypond-git/build/
-make doc
+sudo dnf install tk

 @end example
 
 @end example
 

-The documentation is put in @file{out-www/offline-root/}.  You may
-view the html files by entering the below text; we recommend that
-you bookmark the resulting page:
+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
 
 @example

-firefox ~/lilypond-git/build/out-www/offline-root/index.html
+sudo dnf install texlive-xetex

 @end example
 
 @end example
 

-@subsubheading Other options
+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.}

 
 

-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.

 
 

-Lilybuntu users may now skip to the chapter which is aimed at
-their intended contributions:
+
+@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
 
 @itemize

-@item @rcontrib{Documentation work}
-@item @rcontrib{Translate the documentation}
-@item @rcontrib{Website work}
-@item @rcontrib{Regression tests}
-@item @rcontrib{Programming work}
-@end itemize

 
 

+@item
+Enable the @emph{sources} repository;

 
 

-@node Overview of compiling
-@section Overview of compiling
+@enumerate

 
 

-Compiling LilyPond from source is an involved process, and is only
-recommended for developers and packagers.  Typical program users
-are instead encouraged to obtain the program from a package
-manager (on Unix) or by downloading a precompiled binary
-configured for a specific operating system.  Pre-compiled binaries
-are available on the @rweb{Download} page.
+@item
+Using the @emph{Software Sources} GUI (located under
+@emph{Administration}).

 
 

-Compiling LilyPond from source is necessary if you want to build,
-install, or test your own version of the program.
+@item
+Select @emph{Official Repositories}.

 
 

-A successful compile can also be used to generate and install the
-documentation, incorporating any changes you may have made.
-However, a successful compile is not a requirement for generating
-the documentation.  The documentation can be built using a Git
-repository in conjunction with a locally installed copy of the
-program.  For more information, see @ref{Building documentation
-without compiling}.
+@item
+Check the @emph{Enable source code repositories} box under the
+@emph{Source Code} section.

 
 

-Attempts to compile LilyPond natively on Windows have been
-unsuccessful, though a workaround is available (see
-@rcontrib{Lilybuntu}).
+@item
+Click the @emph{Update the cache} button and when it has completed,
+close the @emph{Software Sources} GUI.

 
 

+@end enumerate

 
 

-@node Requirements
-@section Requirements
+@item
+Download and install all the LilyPond build-dependencies (approximately
+200MB);

 
 

+@example
+sudo apt-get build-dep lilypond
+@end example

 
 

-@menu
-* Requirements for running LilyPond::
-* Requirements for compiling LilyPond::
-* Requirements for building documentation::
-@end menu
+@item
+Download and install additional @q{build} tools required for compiling;

 
 

+@example
+sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
+@end example

 
 

-@node Requirements for running LilyPond
-@subsection Requirements for running LilyPond
+@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}.

 
 

-Running LilyPond requires proper installation of the following
-software:
+@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
 
 @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
+Add the @emph{sources} repository;

 
 

-@item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer)
+@smallexample
+sudo zypper addrepo -f \
+"http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
+@end smallexample

 
 

-@item @uref{http://www.ghostscript.com, Ghostscript} (8.60 or
-newer)
+@item
+Download and install all the LilyPond build-dependencies (approximately
+680MB);

 
 

-@item @uref{http://www.gnu.org/software/guile/guile.html, Guile}
-(1.8.2 or newer)
+@example
+sudo zypper source-install lilypond
+@end example

 
 

-@item @uref{http://www.pango.org/, Pango} (1.12 or newer)
+@item
+Download and install additional @q{build} tools required for compiling;

 
 

-@item @uref{http://www.python.org, Python} (2.4 or newer)
-@end itemize
+@example
+sudo zypper install make
+@end example

 
 

-International fonts are required to create music with
-international text or lyrics.
+@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

 
 

-@node Requirements for compiling LilyPond
-@subsection Requirements for compiling LilyPond
+Also see @ruser{Starting with Git}.
+
+@item
+To use the @code{lily-git.tcl} GUI;
+
+@example
+sudo zypper install tk
+@end example
+
+Also see @ruser{lily-git}.
+
+@end itemize

 
 

-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:
+@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.

 
 

-@multitable @columnfractions .5 .5
-@headitem Distribution @tab Command
-@item Debian, Ubuntu
-@tab @code{sudo apt-get build-dep lilypond}
+@example
+sudo zypper install texlive-xetex
+@end example

 
 

-@item Fedora, RHEL
-@tab @code{sudo yum-builddep lilypond}
+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.}

 
 

-@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
+@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
 
 @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
+
+@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}.

 
 

-Red Hat Fedora:
+@item
+To use the @code{lily-git.tcl} GUI;

 
 

-@c ghostscript-devel-[version] isn't needed

 @example
 @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 tk

 @end example
 
 @end example
 

-Debian GNU/Linux:
+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.

 
 

-@c libgs-dev isn't needed

 @example
 @example

-guile-@var{version}-dev
-libfontconfig1-dev
-libfreetype6-dev
-libpango1.0-dev
-python@var{version}-dev
+sudo apt-get install texlive-xetex

 @end example
 
 @end example
 

-@item @uref{http://flex.sourceforge.net/, Flex}
+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.
+
+@itemize
+
+@item
+@uref{http://www.gnu.org/software/autoconf, GNU Autoconf}
+
+@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}
+
+Use version @code{3.4} or newer (@code{4.x} recommended).
+
+@item
+@uref{http://flex.sourceforge.net/, Flex}
+
+@item
+@uref{http://fontforge.sf.net/, FontForge}
+
+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://fontforge.sf.net/, FontForge} (20060125 or
-newer)
+@item
+@uref{http://www.gnu.org/software/gettext/gettext.html, GNU gettext}

 
 

-@item @uref{http://www.gnu.org/software/bison/, GNU Bison}
+Use version @code{0.17} or newer.

 
 

-@item @uref{http://gcc.gnu.org/, GNU Compiler Collection} (3.4 or
-newer, 4.@var{x} recommended)
+@item
+@uref{http://www.gnu.org/software/make/, GNU Make}

 
 

-@item @uref{http://www.gnu.org/software/gettext/gettext.html, GNU
-gettext} (0.17 or newer)
+Use version @code{3.78} or newer.

 
 

-@item @uref{http://www.gnu.org/software/make/, GNU Make} (3.78 or
-newer)
+@item
+@uref{http://metafont.tutorial.free.fr/, MetaFont}

 
 

-@item @uref{http://metafont.tutorial.free.fr/, MetaFont}
-(mf-nowin, mf, mfw or mfont binaries), usually packaged with
+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{}}.
 
 @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{}}.
 
 @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} (4.11
-or newer)
+@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}
+
+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
 
 
 @end itemize
 
 

+

 @node Requirements for building documentation
 @subsection Requirements for building documentation
 
 @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
 
 @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://www.imagemagick.org/, ImageMagick}

 
 

-@item @uref{http://netpbm.sourceforge.net/, Netpbm}
+@item
+@uref{http://netpbm.sourceforge.net/, Netpbm}

 
 

-@item @uref{http://gzip.org/, gzip}
+@item
+@uref{http://gzip.org/, gzip}

 
 

-@item @uref{http://rsync.samba.org/, rsync}
+@item
+@uref{http://rsync.samba.org/, rsync}

 
 

-@item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82)
+@item
+@uref{http://www.nongnu.org/texi2html/, Texi2HTML}

 
 

-@item International fonts
+Use version @code{1.82}.  Later versions will not work.

 
 

-Red Hat Fedora:
+Download @code{texi2html 1.82} directly from:
+@uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
+
+Extract the files into an appropriate location and then run the
+commands;

 
 @example
 
 @example

-fonts-arabic
-fonts-hebrew
-fonts-ja
-fonts-xorg-truetype
-taipeifonts
-ttfonts-ja
-ttfonts-zh_CN
+./configure
+make
+sudo make install

 @end example
 
 @end example
 

-Debian GNU/Linux:
+Now verify that your operating system is able to see the correct version
+of @code{texi2html}.

 
 @example
 
 @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
 @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
 
 @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
 
 @node Getting the source code
 @section Getting the source code


@@ -362,7 +694,7 @@ download and install the free-software
 
 @menu
 * Running ./autogen.sh::
 
 @menu
 * Running ./autogen.sh::

-* Running ./configure::
+* Running ../configure::

 @end menu
 
 
 @end menu
 
 


@@ -378,50 +710,65 @@ Next, you need to create the generated files; enter the following
 command from your top source directory:
 
 @example
 command from your top source directory:
 
 @example

-./autogen.sh
+./autogen.sh --noconfigure

 @end example
 
 @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.
 
 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::
 
 @menu
 * Configuration options::
 * Checking build dependencies::
 * Configuring target directories::

-* Making an out-of-tree build::

 @end menu
 
 
 @node Configuration options
 @unnumberedsubsubsec Configuration options
 
 @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
 @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
 
 @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
 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}
 
 @example
 ERROR: Please install required programs:  @var{foo}


@@ -437,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.
 
 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
 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


@@ -447,22 +794,25 @@ documentation}.}
 @node Configuring target directories
 @unnumberedsubsubsec Configuring target directories
 
 @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
 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}
 
 @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}'.
+using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.

 @end quotation
 
 A typical installation prefix is @file{$HOME/usr}:
 
 @example
 @end quotation
 
 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
 @end example
 
 Note that if you plan to install a local build on a system where


@@ -479,28 +829,11 @@ already included.
 
 It is also possible to specify separate installation directories
 for different types of program files.  See the full output of
 
 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}.
 
 
 
 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
 
 @node Compiling LilyPond
 @section Compiling LilyPond
 


@@ -516,6 +849,9 @@ mkdir lily-build && cd lily-build
 @node Using make
 @subsection Using @command{make}
 
 @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:
 
 LilyPond is compiled with the @command{make} command.  Assuming
 @command{make} is configured properly, you can simply run:
 


@@ -532,6 +868,10 @@ make help
 
 TODO: Describe what @command{make} actually does.
 
 
 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
 
 @node Saving time with the -j option
 @subsection Saving time with the @option{-j} option


@@ -557,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
 
 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
 
 build with and without profiling, then use the following for the
 normal build
 


@@ -632,7 +972,7 @@ sudo make install
 @end example
 
 @noindent
 @end example
 
 @noindent

-or...
+or@dots{}

 
 @example
 su -c 'make install'
 
 @example
 su -c 'make install'


@@ -650,6 +990,7 @@ re-install.  See @ref{Configuring target directories}.
 @menu
 * Documentation editor's edit/compile cycle::
 * Building documentation::
 @menu
 * Documentation editor's edit/compile cycle::
 * Building documentation::

+* Building a single document::

 * Saving time with CPU_COUNT::
 * AJAX search::
 * Installing documentation::
 * Saving time with CPU_COUNT::
 * AJAX search::
 * Installing documentation::


@@ -666,28 +1007,35 @@ Initial documentation build:
 
 @example
 make [-j@var{X}]
 
 @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
 @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.}
 
 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:
 
 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
 @end itemize
 
 @node Building documentation


@@ -700,11 +1048,20 @@ documentation can be built by issuing:
 make doc
 @end example
 
 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
 
 If @command{make@tie{}doc} succeeds, the HTML documentation tree
 is available in @file{out-www/offline-root/}, and can be browsed


@@ -715,56 +1072,70 @@ 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.
 
 in those places; the only complete set of documentation is in
 @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
 
 @example

-make info
+make log-clean

 @end example
 
 @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:
+
+@example
+make LANGS='' doc
+@end example

 
 

-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:
+@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
 
 @example

-touch Documentation/notation.tely
+make LANGS='de fr' doc

 @end example
 
 @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
 
 @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
 @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
 
 @example

-touch Documentation/*te??
+No rule to make target `X', needed by `Y'

 @end example
 
 @noindent
 @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}
 
 @node Saving time with CPU_COUNT
 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}


@@ -961,22 +1332,8 @@ bug reports to @email{bug-lilypond@@gnu.org}.
 
 Bugs that are not fault of LilyPond are documented here.
 
 
 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
 
 Here are special instructions for compiling under MacOS@tie{}X.
 These instructions assume that dependencies are installed using


@@ -1024,11 +1381,11 @@ Now run the @code{./configure} script.  To avoid complications with
 automatic font detection, add
 
 @example
 automatic font detection, add
 
 @example

---with-ncsb-dir=/opt/local/share/ghostscript/fonts
+--with-fonts-dir=/opt/local/share/ghostscript/fonts

 @end example
 
 
 @end example
 
 

-@unnumberedsubsubsec Solaris
+@unnumberedsubsec Solaris

 
 Solaris7, ./configure
 
 
 Solaris7, ./configure
 


@@ -1047,7 +1404,7 @@ or
 CONFIG_SHELL=/bin/bash bash -c ./configure
 @end example
 
 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}.
 
 To use system fonts, dejaview must be installed.  With the default
 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.


@@ -1061,7 +1418,7 @@ for your hierarchy.)
 @end example
 
 
 @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
 
 On Mac OS X, all fonts are installed by default.  However, finding all
 system fonts requires a bit of configuration; see


@@ -1083,17 +1440,17 @@ Red Hat Fedora
 Debian GNU/Linux
 
    apt-get install emacs-intl-fonts xfonts-intl-.* \
 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
 
 
         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
 
 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
+directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the

 installation directory structure.
 
 
 installation directory structure.
 
 


@@ -1162,7 +1519,7 @@ We currently use make and stepmake, which is complicated and only
 used by us.  Hopefully this will change in the future.
 
 
 used by us.  Hopefully this will change in the future.
 
 

-@subsubheading Version-specific texinfo macros
+@subheading Version-specific texinfo macros

 
 @itemize
 
 
 @itemize