Use distance to original point rather than size of allowed region for

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

diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi
index ea38bd7847b140b85e018a1255bb87e1a1e0d6da..c05e013f5d79ff0a0968c81a51d84b4838ae2da8 100644 (file)
--- a/Documentation/included/compile.itexi
+++ b/Documentation/included/compile.itexi
@@ -7,17 +7,15 @@
 @c   @n ode Compiling from source
 @c   @s ection Compiling from source
 
 @c   @n ode Compiling from source
 @c   @s ection Compiling from source
 

-

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

-* Configuring @command{make}::
+* Configuring make::

 * Compiling LilyPond::
 * Post-compilation options::
 * Problems::
 * Concurrent stable and development versions::
 * Compiling LilyPond::
 * Post-compilation options::
 * Problems::
 * Concurrent stable and development versions::

-* Using a Virtual Machine to Compile LilyPond::

 * Build system::
 @end menu
 
 * Build system::
 @end menu
 


@@ -44,8 +42,8 @@ program.  For more information, see @ref{Building documentation
 without compiling}.
 
 Attempts to compile LilyPond natively on Windows have been
 without compiling}.
 
 Attempts to compile LilyPond natively on Windows have been

-unsuccessful, though a workaround is available (see @ref{Using a
-Virtual Machine to Compile LilyPond}).
+unsuccessful, though a workaround is available (see
+@rcontrib{Lilydev}).

 
 
 @node Requirements
 
 
 @node Requirements


@@ -188,6 +186,8 @@ LilyPond}
 
 @item @uref{http://netpbm.sourceforge.net/, Netpbm}
 
 
 @item @uref{http://netpbm.sourceforge.net/, Netpbm}
 

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

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


@@ -276,17 +276,17 @@ download and install the free-software
 @uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
 
 
 @uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
 
 

-@node Configuring @command{make}
+@node Configuring make

 @section Configuring @command{make}
 
 
 @menu
 @section Configuring @command{make}
 
 
 @menu

-* Running @command{./autogen.sh}::
-* Running @command{./configure}::
+* Running ./autogen.sh::
+* Running ../configure::

 @end menu
 
 
 @end menu
 
 

-@node Running @command{./autogen.sh}
+@node Running ./autogen.sh

 @subsection Running @command{./autogen.sh}
 
 After you unpack the tarball (or download the Git repository), the
 @subsection Running @command{./autogen.sh}
 
 After you unpack the tarball (or download the Git repository), the


@@ -298,50 +298,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 @command{./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}


@@ -357,7 +372,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


@@ -367,10 +382,13 @@ 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
 
 @quotation
 By default, `@command{make@tie{}install}' will install all the


@@ -382,7 +400,7 @@ using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
 A typical installation prefix is @file{$HOME/usr}:
 
 @example
 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


@@ -399,43 +417,29 @@ 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
 
 
 @menu
 @node Compiling LilyPond
 @section Compiling LilyPond
 
 
 @menu

-* Using @command{make}::
-* Saving time with the @option{-j} option::
+* Using make::
+* Saving time with the -j option::

 * Compiling for multiple platforms::
 * Compiling for multiple platforms::

-* Useful @command{make} variables::
+* Useful make variables::

 @end menu
 
 
 @end menu
 
 

-@node Using @command{make}
+@node Using make

 @subsection Using @command{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:
 


@@ -453,7 +457,7 @@ make help
 TODO: Describe what @command{make} actually does.
 
 
 TODO: Describe what @command{make} actually does.
 
 

-@node Saving time with the @option{-j} option
+@node Saving time with the -j option

 @subsection Saving time with the @option{-j} option
 
 If your system has multiple CPUs, you can speed up compilation by
 @subsection Saving time with the @option{-j} option
 
 If your system has multiple CPUs, you can speed up compilation by


@@ -468,6 +472,9 @@ make -j3
 If you get errors using the @option{-j} option, and @samp{make}
 succeeds without it, try lowering the @code{@var{X}} value.
 
 If you get errors using the @option{-j} option, and @samp{make}
 succeeds without it, try lowering the @code{@var{X}} value.
 

+Because multiple jobs run in parallel when @option{-j} is used, it can
+be difficult to determine the source of an error when one occurs.  In
+that case, running @samp{make} without the @option{-j} is advised.

 
 @node Compiling for multiple platforms
 @subsection Compiling for multiple platforms
 
 @node Compiling for multiple platforms
 @subsection Compiling for multiple platforms


@@ -506,7 +513,7 @@ make conf=prof install
 @ref{Installing LilyPond from a local build}
 
 
 @ref{Installing LilyPond from a local build}
 
 

-@node Useful @command{make} variables
+@node Useful make variables

 @subsection Useful @command{make} variables
 
 If a less verbose build output if desired, the variable
 @subsection Useful @command{make} variables
 
 If a less verbose build output if desired, the variable


@@ -521,7 +528,7 @@ command line, or in @file{local.make} at top of the build tree.
 @menu
 * Installing LilyPond from a local build::
 * Generating documentation::
 @menu
 * Installing LilyPond from a local build::
 * Generating documentation::

-* Testing LilyPond::
+* Testing LilyPond binary::

 @end menu
 
 
 @end menu
 
 


@@ -567,7 +574,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::

-* Saving time with @code{CPU_COUNT}::
+* Saving time with CPU_COUNT::

 * AJAX search::
 * Installing documentation::
 * Building documentation without compiling::
 * AJAX search::
 * Installing documentation::
 * Building documentation without compiling::


@@ -602,9 +609,14 @@ make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial bui
 @item
 Reset:
 
 @item
 Reset:
 

-@example
-make doc-clean              @emph{## use only as a last resort.}
-@end example
+In some cases, it is possible to clean the compiled documentation
+with @samp{make@tie{}doc-clean}, but this method is not guaranteed
+to fix everything.  Instead, we recommend that you delete your
+@file{build/} directory, and begin compiling from scratch.  Since
+the documentation compile takes much longer than the
+non-documentation compile, this does not increase the overall time
+by a great deal.
+

 @end itemize
 
 @node Building documentation
 @end itemize
 
 @node Building documentation


@@ -683,7 +695,7 @@ indiscriminately---it is more efficient to @command{touch} only
 the affected files.
 
 
 the affected files.
 
 

-@node Saving time with @code{CPU_COUNT}
+@node Saving time with CPU_COUNT

 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
 
 The most time consuming task for building the documentation is
 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
 
 The most time consuming task for building the documentation is


@@ -850,93 +862,25 @@ exec /opt/local/bin/pngtopnm "$@"
 @end verbatim
 
 
 @end verbatim
 
 

-@node Testing LilyPond
-@subsection Testing LilyPond
+@node Testing LilyPond binary
+@subsection Testing LilyPond binary

 
 
 LilyPond comes with an extensive suite that exercises the entire
 
 
 LilyPond comes with an extensive suite that exercises the entire

-program. This suite can be used to automatically check the impact
-of a change.
-
-@menu
-* Developer's edit/compile/test cycle::
-* Other tests::
-@end menu
-
-@node Developer's edit/compile/test cycle
-@unnumberedsubsubsec Developer's edit/compile/test cycle
-
-TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for
-@code{test-baseline}, @code{check}, @code{clean},
-@code{test-redo}?
-
-@itemize
-@item
-Initial test:
-
-@example
-make [-j@var{X}]
-make test-baseline
-make [-j@var{X} CPU_COUNT=@var{X}] check
-@end example
-
-@item
-Edit/compile/test cycle:
-
-@example
-@emph{## edit source files, then...}
-
-make clean                    @emph{## only if needed (see below)}
-make [-j@var{X}]                    @emph{## only if needed (see below)}
-make test-redo                @emph{## redo files differing from baseline}
-make [-j@var{X} CPU_COUNT=@var{X}] check  @emph{## CPU_COUNT here?}
-@end example
-
-@item
-Reset:
-
-@example
-make test-clean
-@end example
-@end itemize
-
-If you modify any source files that have to be compiled (such as
-@file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}),
-then you must run @command{make} before @command{make test-redo},
-so @command{make} can compile the modified files and relink all
-the object files.  If you only modify files which are interpreted,
-like those in the @file{scm/} and @file{ly/} directories, then
-@command{make} is not needed before @command{make test-redo}.
-
-Also, if you modify any font definitions in the @file{mf/}
-directory then you must run @command{make clean} and
-@command{make} before running @command{make test-redo}.  This will
-recompile everything, whether modified or not, and takes a lot
-longer.
-
-Running @command{make@tie{}check} will leave an HTML page
-@file{out/test-results/index.html}.  This page shows all the
-important differences that your change introduced, whether in the
-layout, MIDI, performance or error reporting.
+program.  This suite can be used to test that the binary has
+been built correctly.

 
 

+The test suite can be executed with:

 
 

-@node Other tests
-@unnumberedsubsubsec Other tests
-
-For tracking memory usage as part of this test, you will need
-GUILE CVS; especially the following patch:
-@uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
-
-For checking the coverage of the test suite, do the following
+@verbatim
+make test
+@end verbatim

 
 

-@example
-./scripts/auxiliar/build-coverage.sh
-@emph{# uncovered files, least covered first}
-./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
-@emph{# consecutive uncovered lines, longest first}
-./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
-@end example
+If the test suite completes successfully, the LilyPond binary
+has been verified.

 
 

+More information on the regression test suite is found at
+@rcontrib{Regression tests}.

 
 @node Problems
 @section Problems
 
 @node Problems
 @section Problems


@@ -971,7 +915,7 @@ been tested using OS X 10.5 (Leopard).
 First, install the relevant dependencies using MacPorts.
 
 Next, add the following to your relevant shell initialization
 First, install the relevant dependencies using MacPorts.
 
 Next, add the following to your relevant shell initialization

-files. This is @code{~/.profile} by default. You should create
+files.  This is @code{~/.profile} by default.  You should create

 this file if it does not exist.
 
 @example
 this file if it does not exist.
 
 @example


@@ -979,7 +923,7 @@ export PATH=/opt/local/bin:/opt/local/sbin:$PATH
 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
 @end example
 
 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
 @end example
 

-Now you must edit the generated @code{config.make} file.  Change
+Now you must edit the generated @file{config.make} file.  Change

 
 @example
 FLEXLEXER_FILE = /usr/include/FlexLexer.h
 
 @example
 FLEXLEXER_FILE = /usr/include/FlexLexer.h


@@ -993,7 +937,7 @@ FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
 @end example
 
 At this point, you should verify that you have the appropriate
 @end example
 
 At this point, you should verify that you have the appropriate

-fonts installed with your ghostscript installation. Check @code{ls
+fonts installed with your ghostscript installation.  Check @code{ls

 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
 .pfb and .afm).  If you don't have them, run the following
 commands to grab them from the ghostscript SVN server and install
 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
 .pfb and .afm).  If you don't have them, run the following
 commands to grab them from the ghostscript SVN server and install


@@ -1005,7 +949,7 @@ sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
 rm -rf urw-fonts-1.07pre44
 @end example
 
 rm -rf urw-fonts-1.07pre44
 @end example
 

-Now run the @code{./configure} script. To avoid complications with
+Now run the @code{./configure} script.  To avoid complications with

 automatic font detection, add
 
 @example
 automatic font detection, add
 
 @example


@@ -1089,9 +1033,9 @@ installation directory structure.
 
 
 It can be useful to have both the stable and the 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
+of Lilypond available at once.  One way to do this on GNU/Linux is to

 install the stable version using the precompiled binary, and run the
 install the stable version using the precompiled binary, and run the

-development version from the source tree. After running @command{make
+development version from the source tree.  After running @command{make

 all} from the top directory of the Lilypond source files, there will
 be a binary called @code{lilypond} in the @code{out} directory:
 
 all} from the top directory of the Lilypond source files, there will
 be a binary called @code{lilypond} in the @code{out} directory:
 


@@ -1100,7 +1044,7 @@ be a binary called @code{lilypond} in the @code{out} directory:
 @end example
 
 This binary can be run without actually doing the @code{make
 @end example
 
 This binary can be run without actually doing the @code{make

-install} command. The advantage to this is that you can have all
+install} command.  The advantage to this is that you can have all

 of the latest changes available after pulling from git and running
 @code{make all}, without having to uninstall the old version and
 reinstall the new.
 of the latest changes available after pulling from git and running
 @code{make all}, without having to uninstall the old version and
 reinstall the new.


@@ -1139,119 +1083,6 @@ TODO: ADD
 - other compilation tricks for developers
 
 
 - other compilation tricks for developers
 
 

-@node Using a Virtual Machine to Compile LilyPond
-@section Using a Virtual Machine to Compile LilyPond
-
-
-TODO: rewrite for lily-git.tcl !!!  do before GOP!  -gp
-
-Since it is not possible to compile Lilypond on Windows, some
-developers may find it useful to install a GNU/Linux virtual
-machine. A disk image with a special remix of @strong{Ubuntu}
-has been created for this purpose. It has all of the Lilypond
-build dependencies in place, so that once installed, it is
-ready to compile both Lilypond and the Documentation.
-The @code{lilybuntu} remix is available for download here:
-
-@example
-@uref{http://@/files.lilynet.net/@/lilybuntu.iso}
-@end example
-
-We do not necessarily recommend any one virtualization tool,
-however the @code{lilybuntu} remix is known to work well on
-@uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
-which is a free download. Consult your virtualization software's
-documentation for instructions on setting up the software and
-for general instructions on installing a virtual machine.
-
-Steps to setting up @code{lilybuntu} in a virtual machine:
-
-@enumerate
-@item Download the @code{lilybuntu} disk image.
-
-@item Install @code{lilybuntu}. You will use the @code{.iso}
-file as the boot disk. It should not be necessary to burn it
-to a DVD, but consult the documentation for your virtualization
-software for specific instructions. If possible, use at least
-the recommended amount of RAM for the virtual machine (384 MB on
-VirtualBox), and use a dynamically expanding virtual hard drive.
-A virtual hard drive with 6 GB will be enough to compile LilyPond,
-but if you intend to build the docs and run the regression tests
-the virtual hard drive should be at least 10 GB.
-The Ubuntu installation should be straightforward, although in the
-partitioning stage do not be afraid to select @qq{use entire disk,}
-since this is only your @strong{virtual disk} and not your
-machine's actual hard drive.
-
-@item After installation is complete, restart the virtual
-machine.  If you are using @strong{VirtualBox}, you may wish
-to install the @qq{Guest Additions}, which while not essential for
-compiling @code{Lilypond} will allow you to use the virtual machine
-in full screen, Seamless mode (also known as Unity mode on other
-virtualization platforms) and allow you to share clipboards between
-the physical and virtual machine.  From the @code{Devices} menu select
-@code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
-will appear on the desktop.  Open a @strong{terminal} session.
-(@code{Applications > Accessories > Terminal}) and @code{cd} to the
-top level of the CDROM.  Run the @code{autorun.sh} script as superuser
-(@code{sudo ./autorun.sh }), a console window will open while the
-@qq{Guest Additions} are being installed.  Once the script has
-been finished, reboot your Virtual Machine to complete the installation
-of the @qq{Guest Additions}.
-
-@item Open a @strong{terminal} session.
-(@code{Applications > Accessories > Terminal})
-
-@item Open @strong{Firefox} (there's an icon for it on the
-panel at the top of the screen) and go to the online Lilypond
-@uref{http://lilypond.org/doc/latest/Documentation/contributor/,
-Contributor's Guide}.
-
-@item To retrieve the Lilypond source code from @code{git},
-copy-and-paste each command from the CG @qq{Main source code}
-section into the terminal. (paste into the terminal with keystroke
-@code{CTRL+SHIFT+V})
-
-@item Prepare to build Lilypond by running the configuration script.
-Type
-
-@example
-./autogen.sh
-@end example
-
-When it is finished you should be presented
-with the three most common @code{make} options:
-
-@example
-Type:
-    make all       to build LilyPond
-    make install   to install LilyPond
-    make help      to see all possible targets
-
-Edit local.make for local Makefile overrides.
-@end example
-
-@item First type @code{make all} to build Lilypond. This will take
-a while.
-
-@item When Lilypond is finished building, build the documentation
-by typing
-
-@example
-make doc
-@end example
-
-Depending on your system specs it could take from 30-60 minutes
-to finish.
-
-@end enumerate
-
-At this point everything has been compiled.
-You may install Lilypond using @code{make install}, or you may wish
-to set up your system with concurrent stable and development
-versions as described in the previous section.
-
-

 @node Build system
 @section Build system
 
 @node Build system
 @section Build system
 


@@ -1260,7 +1091,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 macors
+@subsubheading Version-specific texinfo macros

 
 @itemize
 
 
 @itemize
 


@@ -1270,7 +1101,7 @@ made with @command{scripts/build/create-version-itexi.py} and@*
 
 @item
 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
 
 @item
 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the

-website (made with website.make, used on lilypond.org)
+website (made with @file{website.make}, used on lilypond.org)

 
 @item
 not (?) used in the main docs?
 
 @item
 not (?) used in the main docs?