Fix some minor errors and omissions in debian/copyright

[lilypond.git] / INSTALL.txt

diff --git a/INSTALL.txt b/INSTALL.txt
index 594698c1d8e161f3a2f341f5ff30036c45dd70e4..dedfe576024d83f81c2920ae40f5313c82877dd9 100644 (file)
--- a/INSTALL.txt
+++ b/INSTALL.txt
@@ -5,46 +5,51 @@ Table of Contents
 *****************
 
 INSTALL - compiling and installing GNU LilyPond
 *****************
 
 INSTALL - compiling and installing GNU LilyPond

-  Overview of compiling
-  Requirements
-    Requirements for running LilyPond
-    Requirements for compiling LilyPond
-    Requirements for building documentation
-  Getting the source code
-  Configuring `make'
-    Running `./autogen.sh'
-    Running `../configure'
+1 Compilation
+  1.1 Overview of compiling
+  1.2 Requirements
+    1.2.1 Requirements for running LilyPond
+    1.2.2 Requirements for compiling LilyPond
+    1.2.3 Requirements for building documentation
+  1.3 Getting the source code
+  1.4 Configuring `make'
+    1.4.1 Running `./autogen.sh'
+    1.4.2 Running `../configure'

       Configuration options
       Checking build dependencies
       Configuring target directories
       Configuration options
       Checking build dependencies
       Configuring target directories

-  Compiling LilyPond
-    Using `make'
-    Saving time with the `-j' option
-    Compiling for multiple platforms
-    Useful `make' variables
-  Post-compilation options
-    Installing LilyPond from a local build
-    Generating documentation
+  1.5 Compiling LilyPond
+    1.5.1 Using `make'
+    1.5.2 Saving time with the `-j' option
+    1.5.3 Compiling for multiple platforms
+    1.5.4 Useful `make' variables
+  1.6 Post-compilation options
+    1.6.1 Installing LilyPond from a local build
+    1.6.2 Generating documentation

       Documentation editor's edit/compile cycle
       Building documentation
       Documentation editor's edit/compile cycle
       Building documentation

+      Building a single document

       Saving time with `CPU_COUNT'
       AJAX search
       Installing documentation
       Building documentation without compiling
       Saving time with `CPU_COUNT'
       AJAX search
       Installing documentation
       Building documentation without compiling

-    Testing LilyPond binary
-  Problems
-      Bison 1.875
-      Compiling on MacOS X
-      Solaris
-      FreeBSD
-      International fonts
-      Using lilypond python libraries
-  Concurrent stable and development versions
-  Build system
+    1.6.3 Testing LilyPond binary
+  1.7 Problems
+    Bison 1.875
+    Compiling on MacOS X
+    Solaris
+    FreeBSD
+    International fonts
+    Using lilypond python libraries
+  1.8 Concurrent stable and development versions
+  1.9 Build system

 
 
 
 

-Overview of compiling
-=====================
+1 Compilation
+*************
+
+1.1 Overview of compiling
+=========================

 
 Compiling LilyPond from source is an involved process, and is only
 recommended for developers and packagers.  Typical program users are
 
 Compiling LilyPond from source is an involved process, and is only
 recommended for developers and packagers.  Typical program users are


@@ -64,14 +69,14 @@ in conjunction with a locally installed copy of the program.  For more
 information, see *note Building documentation without compiling::.
 
    Attempts to compile LilyPond natively on Windows have been
 information, see *note Building documentation without compiling::.
 
    Attempts to compile LilyPond natively on Windows have been

-unsuccessful, though a workaround is available (see *note Lilydev:
-(lilypond-contributor)Lilydev.).
+unsuccessful, though a workaround is available (see *note LilyDev:
+(lilypond-contributor)LilyDev.).

 
 

-Requirements
-============
+1.2 Requirements
+================

 
 

-Requirements for running LilyPond
----------------------------------
+1.2.1 Requirements for running LilyPond
+---------------------------------------

 
 Running LilyPond requires proper installation of the following software:
 
 
 Running LilyPond requires proper installation of the following software:
 


@@ -94,8 +99,8 @@ Running LilyPond requires proper installation of the following software:
    International fonts are required to create music with international
 text or lyrics.
 
    International fonts are required to create music with international
 text or lyrics.
 

-Requirements for compiling LilyPond
------------------------------------
+1.2.2 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
 
 Below is a full list of packages needed to build LilyPond.  However,
 for most common distributions there is an easy way of installing most


@@ -161,8 +166,8 @@ openSUSE, SLED                       `sudo zypper --build-deps-only
    * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
      (1.33 or newer recommended)
 
    * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
      (1.33 or newer recommended)
 

-Requirements for building documentation
----------------------------------------
+1.2.3 Requirements for building documentation
+---------------------------------------------

 
 You can view the documentation online at
 `http://www.lilypond.org/doc/', but you can also build it locally.
 
 You can view the documentation online at
 `http://www.lilypond.org/doc/', but you can also build it locally.


@@ -202,8 +207,8 @@ This process requires some additional tools and packages:
           xfonts-cronyx-100dpi
           xfonts-intl-.*
 
           xfonts-cronyx-100dpi
           xfonts-intl-.*
 

-Getting the source code
-=======================
+1.3 Getting the source code
+===========================

 
 Downloading the Git repository
 ------------------------------
 
 Downloading the Git repository
 ------------------------------


@@ -249,11 +254,11 @@ of disk space.
 download and install the free-software 7zip archiver
 (http://www.7-zip.org) to extract the tarball.
 
 download and install the free-software 7zip archiver
 (http://www.7-zip.org) to extract the tarball.
 

-Configuring `make'
-==================
+1.4 Configuring `make'
+======================

 
 

-Running `./autogen.sh'
-----------------------
+1.4.1 Running `./autogen.sh'
+----------------------------

 
 After you unpack the tarball (or download the Git repository), the
 contents of your top source directory should be similar to the current
 
 After you unpack the tarball (or download the Git repository), the
 contents of your top source directory should be similar to the current


@@ -276,8 +281,8 @@ configuration, such as `configure', `README.txt', etc.
    We heavily recommend building lilypond inside a separate directory
 with this method.
 
    We heavily recommend building lilypond inside a separate directory
 with this method.
 

-Running `../configure'
-----------------------
+1.4.2 Running `../configure'
+----------------------------

 
 Configuration options
 .....................
 
 Configuration options
 .....................


@@ -356,11 +361,11 @@ different types of program files.  See the full output of
 
    If you encounter any problems, please see *note Problems::.
 
 
    If you encounter any problems, please see *note Problems::.
 

-Compiling LilyPond
-==================
+1.5 Compiling LilyPond
+======================

 
 

-Using `make'
-------------
+1.5.1 Using `make'
+------------------

 
           Note: make sure that you are in the `build/' subdirectory of
           your source tree.
 
           Note: make sure that you are in the `build/' subdirectory of
           your source tree.


@@ -377,8 +382,18 @@ run:
 
    TODO: Describe what `make' actually does.
 
 
    TODO: Describe what `make' actually does.
 

-Saving time with the `-j' option
---------------------------------
+
+
+See also
+........
+
+
+
+   *note Generating documentation:: provides more info on the `make'
+targets used to build the LilyPond documentation.
+
+1.5.2 Saving time with the `-j' option
+--------------------------------------

 
 If your system has multiple CPUs, you can speed up compilation by
 adding `-jX' to the `make' command, where `X' is one more than the
 
 If your system has multiple CPUs, you can speed up compilation by
 adding `-jX' to the `make' command, where `X' is one more than the


@@ -394,8 +409,8 @@ it, try lowering the `X' value.
 difficult to determine the source of an error when one occurs.  In that
 case, running `make' without the `-j' is advised.
 
 difficult to determine the source of an error when one occurs.  In that
 case, running `make' without the `-j' is advised.
 

-Compiling for multiple platforms
---------------------------------
+1.5.3 Compiling for multiple platforms
+--------------------------------------

 
 If you want to build multiple versions of LilyPond with different
 configuration settings, you can use the `--enable-config=CONF' option
 
 If you want to build multiple versions of LilyPond with different
 configuration settings, you can use the `--enable-config=CONF' option


@@ -425,18 +440,18 @@ See also
 
    *note Installing LilyPond from a local build::
 
 
    *note Installing LilyPond from a local build::
 

-Useful `make' variables
------------------------
+1.5.4 Useful `make' variables
+-----------------------------

 
 If a less verbose build output if desired, the variable `QUIET_BUILD'
 may be set to `1' on `make' command line, or in `local.make' at top of
 the build tree.
 
 
 If a less verbose build output if desired, the variable `QUIET_BUILD'
 may be set to `1' on `make' command line, or in `local.make' at top of
 the build tree.
 

-Post-compilation options
-========================
+1.6 Post-compilation options
+============================

 
 

-Installing LilyPond from a local build
---------------------------------------
+1.6.1 Installing LilyPond from a local build
+--------------------------------------------

 
 If you configured `make' to install your local build in a directory
 where you normally have write permission (such as your home directory),
 
 If you configured `make' to install your local build in a directory
 where you normally have write permission (such as your home directory),


@@ -460,8 +475,8 @@ or...
 the installation directory to one that you can write to, and then
 re-install.  See *note Configuring target directories::.
 
 the installation directory to one that you can write to, and then
 re-install.  See *note Configuring target directories::.
 

-Generating documentation
-------------------------
+1.6.2 Generating documentation
+------------------------------

 
 Documentation editor's edit/compile cycle
 .........................................
 
 Documentation editor's edit/compile cycle
 .........................................


@@ -469,7 +484,8 @@ Documentation editor's edit/compile cycle
    * Initial documentation build:
 
           make [-jX]
    * Initial documentation build:
 
           make [-jX]

-          make [-jX CPU_COUNT=X] doc  _## can take an hour or more_
+          make [-jX CPU_COUNT=X] doc          _## can take an hour or more_
+          make [-jX CPU_COUNT=X] doc-stage-1  _## to build only PDF documentation_

 
    * Edit/compile cycle:
 
 
    * Edit/compile cycle:
 


@@ -478,17 +494,17 @@ Documentation editor's edit/compile cycle
           make [-jX]                  _## needed if editing outside_
                                       _##   Documentation/, but useful anyway_
                                       _##   for finding Texinfo errors._
           make [-jX]                  _## needed if editing outside_
                                       _##   Documentation/, but useful anyway_
                                       _##   for finding Texinfo errors._

-          touch Documentation/*te??   _## bug workaround_

           make [-jX CPU_COUNT=X] doc  _## usually faster than initial build._
 
    * Reset:
 
           make [-jX CPU_COUNT=X] doc  _## usually faster than initial build._
 
    * Reset:
 

-     In some cases, it is possible to clean the compiled documentation
-     with `make doc-clean', but this method is not guaranteed to fix
-     everything.  Instead, we recommend that you delete your `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.
+     It is generally possible to remove the compiled documentation from
+     your system with `make 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 `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.

 
 
 Building documentation
 
 
 Building documentation


@@ -499,10 +515,17 @@ built by issuing:
 
      make doc
 
 
      make doc
 

-   The first time you run `make doc', the process can easily take an
-hour or more.  After that, `make 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,
+
+     make doc-stage-1
+
+          Note: The first time you run `make doc', the process can
+          easily take an hour or more with not much output on the
+          command line.
+
+   After this initial build, `make 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 `make doc' succeeds, the HTML documentation tree is available in
 `out-www/offline-root/', and can be browsed locally.  Various portions
 
    If `make doc' succeeds, the HTML documentation tree is available in
 `out-www/offline-root/', and can be browsed locally.  Various portions


@@ -512,44 +535,56 @@ _portions_ of the docs.  Please do not complain about anything which is
 broken in those places; the only complete set of documentation is in
 `out-www/offline-root/' from the top of the source tree.
 
 broken in those places; the only complete set of documentation is in
 `out-www/offline-root/' from the top of the source tree.
 

+   `make 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
+`make doc-clean'.  To remove all the logfiles generated by the
+compilation process, use:
+
+     make log-clean
+
+   `make doc' compiles the documents for all languages.  To save some
+compile time, the English language documents can be compiled on their
+own with:
+
+     make LANGS='' doc
+
+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:
+
+     make LANGS='de fr' doc
+
+Note that this will also compile the English version.
+

    Compilation of documentation in Info format with images can be done
 separately by issuing:
 
      make info
 
    Compilation of documentation in Info format with images can be done
 separately by issuing:
 
      make info
 

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

 
 

-Known issues and warnings
-.........................
-
-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 `make 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 `touch' the top source
-file for any manual you've edited.  For example, if you make changes to
-a file in `notation/', do:
-
-     touch Documentation/notation.tely
+     No rule to make target `X', needed by `Y'

 
 

-The top sources possibly affected by this are:
+Your best bet is to delete the file Y.dep and to try again.

 
 

-     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
+Building a single document
+..........................

 
 

-You can `touch' all of them at once with:
+It's possible to build a single document.  For example, to rebuild only
+`contributor.pdf', do the following:

 
 

-     touch Documentation/*te??
+     cd build/
+     cd Documentation/
+     touch ../../Documentation/contributor.texi
+     make out=www out-www/contributor.pdf

 
 

-However, this will rebuild all of the manuals indiscriminately--it is
-more efficient to `touch' only the affected files.
+   If you are only working on a single document, test-building it in
+this way can give substantial time savings - recreating
+`contributor.pdf', for example, takes a matter of seconds.

 
 Saving time with `CPU_COUNT'
 ............................
 
 Saving time with `CPU_COUNT'
 ............................


@@ -679,8 +714,8 @@ exec /sw/bin/pngtopnm "$@"
 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
 exec /opt/local/bin/pngtopnm "$@"
 
 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
 exec /opt/local/bin/pngtopnm "$@"
 

-Testing LilyPond binary
------------------------
+1.6.3 Testing LilyPond binary
+-----------------------------

 
 LilyPond comes with an extensive suite that exercises the entire
 program.  This suite can be used to test that the binary has been built
 
 LilyPond comes with an extensive suite that exercises the entire
 program.  This suite can be used to test that the binary has been built


@@ -696,8 +731,8 @@ been verified.
    More information on the regression test suite is found at *note
 Regression tests: (lilypond-contributor)Regression tests.
 
    More information on the regression test suite is found at *note
 Regression tests: (lilypond-contributor)Regression tests.
 

-Problems
-========
+1.7 Problems
+============

 
 For help and questions use <lilypond-user@gnu.org>.  Send bug reports
 to <bug-lilypond@gnu.org>.
 
 For help and questions use <lilypond-user@gnu.org>.  Send bug reports
 to <bug-lilypond@gnu.org>.


@@ -705,7 +740,7 @@ to <bug-lilypond@gnu.org>.
    Bugs that are not fault of LilyPond are documented here.
 
 Bison 1.875
    Bugs that are not fault of LilyPond are documented here.
 
 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
 
 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


@@ -718,7 +753,7 @@ recompile bison 1.875 with the following fix
      $ make
 
 Compiling on MacOS X
      $ make
 
 Compiling on MacOS X

-....................
+--------------------

 
 Here are special instructions for compiling under MacOS X.  These
 instructions assume that dependencies are installed using MacPorts.
 
 Here are special instructions for compiling under MacOS X.  These
 instructions assume that dependencies are installed using MacPorts.


@@ -759,7 +794,7 @@ automatic font detection, add
      --with-ncsb-dir=/opt/local/share/ghostscript/fonts
 
 Solaris
      --with-ncsb-dir=/opt/local/share/ghostscript/fonts
 
 Solaris

-.......
+-------

 
 Solaris7, ./configure
 
 
 Solaris7, ./configure
 


@@ -774,7 +809,7 @@ or
      CONFIG_SHELL=/bin/bash bash -c ./configure
 
 FreeBSD
      CONFIG_SHELL=/bin/bash bash -c ./configure
 
 FreeBSD

-.......
+-------

 
 To use system fonts, dejaview must be installed.  With the default
 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
 
 To use system fonts, dejaview must be installed.  With the default
 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.


@@ -786,7 +821,7 @@ for your hierarchy.)
      <dir>/usr/X11R6/lib/X11/fonts</dir>
 
 International fonts
      <dir>/usr/X11R6/lib/X11/fonts</dir>
 
 International fonts

-...................
+-------------------

 
 On Mac OS X, all fonts are installed by default.  However, finding all
 system fonts requires a bit of configuration; see this post
 
 On Mac OS X, all fonts are installed by default.  However, finding all
 system fonts requires a bit of configuration; see this post


@@ -810,7 +845,7 @@ Debian GNU/Linux
         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 
 Using lilypond python libraries
         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 
 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
 
 If you want to use lilypond's python libraries (either running certain
 build scripts manually, or using them in other programs), set


@@ -818,8 +853,8 @@ build scripts manually, or using them in other programs), set
 `.../usr/lib/lilypond/current/python' in the installation directory
 structure.
 
 `.../usr/lib/lilypond/current/python' in the installation directory
 structure.
 

-Concurrent stable and development versions
-==========================================
+1.8 Concurrent stable and development versions
+==============================================

 
 It can be useful to have both the stable and the development versions
 of Lilypond available at once.  One way to do this on GNU/Linux is to
 
 It can be useful to have both the stable and the development versions
 of Lilypond available at once.  One way to do this on GNU/Linux is to


@@ -859,14 +894,14 @@ stable `lilypond'), and make it executable:
 
    - other compilation tricks for developers
 
 
    - other compilation tricks for developers
 

-Build system
-============
+1.9 Build system
+================

 
 We currently use make and stepmake, which is complicated and only used
 by us.  Hopefully this will change in the future.
 
 Version-specific texinfo macros
 
 We currently use make and stepmake, which is complicated and only used
 by us.  Hopefully this will change in the future.
 
 Version-specific texinfo macros

-...............................
+-------------------------------

 
    * made with `scripts/build/create-version-itexi.py' and
      `scripts/build/create-weblinks-itexi.py'
 
    * made with `scripts/build/create-version-itexi.py' and
      `scripts/build/create-weblinks-itexi.py'