Function for overriding broken spanners

[lilypond.git] / Documentation / usage / running.itely

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index e6d83537d2c6bdada0d940697364b09d6b713181..7522cec85b74b3aca677cd51454e89a81e985751 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.12.0"
+@c \version "2.15.18"

 
 
 @node Running lilypond
 
 
 @node Running lilypond


@@ -53,7 +53,8 @@ if you are unfamiliar with the command-line.
 
 @menu
 * Invoking lilypond::
 
 @menu
 * Invoking lilypond::

-* Command line options for lilypond::
+* Basic command line options for LilyPond::
+* Advanced command line options for LilyPond::

 * Environment variables::
 * LilyPond in chroot jail::
 @end menu
 * Environment variables::
 * LilyPond in chroot jail::
 @end menu


@@ -97,8 +98,32 @@ will output @var{base}@file{-violin.pdf} and
 @var{base}@file{-cello-1.pdf}.
 
 
 @var{base}@file{-cello-1.pdf}.
 
 

-@node Command line options for lilypond
-@unnumberedsubsec Command line options for @command{lilypond}
+@unnumberedsubsubsec Standard shell commands
+
+If your shell (i.e. command window) supports normal redirects,
+then you might find it useful to use the following commands to
+redirect console output to a file:
+
+@itemize
+
+@item
+@code{lilypond file.ly 1>stdout.log} to redirect normal output
+
+@item
+@code{lilypond file.ly 2>stderr.log} to redirect error messages
+
+@item
+@code{lilypond file.ly &>all.log} to redirect all output
+
+@end itemize
+
+Consult the documentation for your shell to see if it supports these
+options, or if the syntax is different.  Note that these are shell
+commands and have nothing to do with lilypond.
+
+
+@node Basic command line options for LilyPond
+@unnumberedsubsec Basic command line options for LilyPond

 
 @cindex Invoking @command{lilypond}
 @cindex command line options for @command{lilypond}
 
 @cindex Invoking @command{lilypond}
 @cindex command line options for @command{lilypond}


@@ -109,9 +134,15 @@ The following options are supported:
 
 @table @code
 
 
 @table @code
 

+@item -d,--define-default=@var{var}=@var{val}
+See @ref{Advanced command line options for LilyPond}.
+
+@cindex Scheme, expression evaluation
+@cindex expression evaluation, Scheme
+

 @item -e,--evaluate=@var{expr}
 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
 @item -e,--evaluate=@var{expr}
 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.

-Multiple @code{-e} options may be given, they will be evaluated
+Multiple @option{-e} options may be given, they will be evaluated

 sequentially.
 
 The expression will be evaluated in the @code{guile-user} module, so
 sequentially.
 
 The expression will be evaluated in the @code{guile-user} module, so


@@ -131,273 +162,534 @@ on the command-line, and include
 @noindent
 at the top of the @code{.ly} file.
 
 @noindent
 at the top of the @code{.ly} file.
 

+@warning{Windows users must use double quotes instead of single quotes.}
+
+@cindex output, format
+@cindex format, output
+

 @item -f,--format=@var{format}
 which formats should be written.  Choices for @code{format} are
 @code{ps}, @code{pdf}, and @code{png}.
 
 Example: @code{lilypond -fpng @var{filename}.ly}
 
 @item -f,--format=@var{format}
 which formats should be written.  Choices for @code{format} are
 @code{ps}, @code{pdf}, and @code{png}.
 
 Example: @code{lilypond -fpng @var{filename}.ly}
 

+@item -h,--help
+Show a summary of usage.

 
 

+@item -H,--header=@var{FIELD}
+Dump a header field to file @file{BASENAME.@var{FIELD}}.

 
 

-@item -d,--define-default=@var{var}=@var{val}
-This sets the internal program option @var{var} to the Scheme value
-@var{val}.  If @var{val} is not supplied, then @var{#t} is used.  To
-switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
+@item -i,--init=@var{file}
+Set init file to @var{file} (default: @file{init.ly}).

 
 

-@cindex point and click, command line
+@cindex file searching
+@cindex search path

 
 

-@example
--dno-point-and-click
-@end example
+@item -I, --include=@var{directory}
+Add @var{directory} to the search path for input files.

 
 

-@noindent
-is the same as
-@example
--dpoint-and-click='#f'
-@end example
+Multiple -I options may be given.  The search will start in the first
+defined directory, and if the file to be included is not found the
+search will continue in subsequent directories.

 
 

-Here are a few interesting options.
+@cindex chroot jail, running inside

 
 

-@cindex help, command line
+@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+Run @command{lilypond} in a chroot jail.

 
 

-@table @samp
-@item help
-Running @code{lilypond -dhelp} will print all of the @code{-d} options
-available.
+The @option{--jail} option provides a more flexible alternative to
+@option{-dsafe}, when LilyPond formatting is being provided via a web
+server, or whenever LilyPond executes commands sent by external sources
+(see @ref{Advanced command line options for LilyPond}).
+
+It works by changing the root of @command{lilypond} to @var{jail} just
+before starting the actual compilation process.  The user and group are
+then changed to match those provided, and the current directory is
+changed to @var{dir}.  This setup guarantees that it is not possible (at
+least in theory) to escape from the jail.  Note that for @option{--jail}
+to work, @command{lilypond} must be run as root, which is usually
+accomplished in a safe way using @command{sudo}.

 
 

-@cindex paper-size, command line
+Setting up a jail can be a relatively complex matter, as we must be sure
+that LilyPond is able to find whatever it needs to compile the source
+@emph{inside} the jail itself.  A typical chroot jail will comprise the
+following steps:

 
 

-@item paper-size
-This option sets the default paper-size,
-@example
--dpaper-size=\"letter\"
-@end example
+@table @asis

 
 

-@noindent
-Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-@c Match " in previous line to help context-sensitive editors
+@item Setting up a separate filesystem
+A separate filesystem should be created for LilyPond, so that it can be
+mounted with safe options such as @code{noexec}, @code{nodev}, and
+@code{nosuid}.  In this way, it is impossible to run executables or to
+write directly to a device from LilyPond.  If you do not want to create a
+separate partition, just create a file of reasonable size and use it to
+mount a loop device.  A separate filesystem also guarantees that LilyPond
+cannot write more space than it is allowed.

 
 

-@cindex safe, command line
+@item Setting up a separate user
+A separate user and group (say, @code{lily}/@code{lily}) with low
+privileges should be used to run LilyPond inside the jail.  There should
+be a single directory writable by this user, which should be passed in
+@var{dir}.

 
 

-@item safe
-Do not trust the @code{.ly} input.
+@item Preparing the jail
+LilyPond needs to read a number of files while running.  All these files
+are to be copied into the jail, under the same path they appear in the
+real root filesystem.  The entire content of the LilyPond installation
+(e.g., @file{/usr/share/lilypond}) should be copied.

 
 

-When LilyPond formatting is available through a web server, either the
-@code{--safe} or the @code{--jail} option @b{MUST} be passed.  The
-@code{--safe} option will prevent inline Scheme code from wreaking
-havoc, for example
+If problems arise, the simplest way to trace them down is to run
+LilyPond using @command{strace}, which will allow you to determine which
+files are missing.

 
 

-@quotation
-@verbatim
-#(system "rm -rf /")
-{
-  c4^#(ly:export (ly:gulp-file "/etc/passwd"))
-}
-@end verbatim
-@end quotation
+@item Running LilyPond
+In a jail mounted with @code{noexec} it is impossible to execute any
+external program.  Therefore LilyPond must be run with a backend that
+does not require any such program.  As we have already mentioned, it
+must be run with superuser privileges (which, of course, it will lose
+immediately), possibly using @command{sudo}.  It is also good practice
+to limit the number of seconds of CPU time LilyPond can use (e.g., using
+@command{ulimit@tie{}-t}), and, if your operating system supports it,
+the amount of memory that can be allocated.  Also see
+@ref{LilyPond in chroot jail}.
+@end table

 
 

-The @code{-dsafe} option works by evaluating in-line Scheme
-expressions in a special safe module.  This safe module is derived from
-GUILE @file{safe-r5rs} module, but adds a number of functions of the
-LilyPond API.  These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
+@cindex loglevel
+@cindex output, verbosity

 
 

-In addition, safe mode disallows @code{\include} directives and
-disables the use of backslashes in @TeX{} strings.
+@item -l,--loglevel=@var{LEVEL}
+Set the verbosity of the console output to @var{LEVEL}. Possible values
+are:

 
 

-In safe mode, it is not possible to import LilyPond variables
-into Scheme.
+@table @code

 
 

-@code{-dsafe} does @emph{not} detect resource overuse.  It is still possible to
-make the program hang indefinitely, for example by feeding cyclic data
-structures into the backend.  Therefore, if using LilyPond on a
-publicly accessible webserver, the process should be limited in both
-CPU and memory usage.
+@item NONE
+No output at all, not even error messages.

 
 

-The safe mode will prevent many useful LilyPond snippets from being
-compiled.  The @code{--jail} is a more secure alternative, but
-requires more work to set up.
+@item ERROR
+Only error messages, no warnings or progress messages.

 
 

-@cindex output format, setting
-@item backend
-the output format to use for the back-end.  Choices for @code{format} are
-@table @code
-@item ps
-@cindex PostScript output
- for PostScript.
+@item WARN
+Warnings and error messages, no progress.

 
 

-  Postscript files include TTF, Type1 and OTF fonts.  No subsetting of
-  these fonts is done.  When using oriental character sets, this can
-  lead to huge files.
+@item BASIC_PROGRESS
+Basic progress messages (success), warnings and errors.

 
 

-@item eps
+@item PROGRESS
+All progress messages, warnings and errors.

 
 

-@cindex Postscript, encapsulated
-@cindex EPS (Encapsulated PostScript)
+@item INFO (default)
+Progress messages, warnings, errors and further execution information.

 
 

- for encapsulated PostScript.  This dumps every page (system) as a separate
-@file{EPS} file, without fonts, and as one collated @file{EPS} file with
-all pages (systems) including fonts.
+@item DEBUG
+All possible messages, including verbose debug output.

 
 

-This mode is used by default by @command{lilypond-book}.
+@end table

 
 

-@item svg
+@cindex directory, redirect output
+@cindex output, setting filename
+@cindex output, directory

 
 

-@cindex SVG (Scalable Vector Graphics)
+@item -o,--output=@var{FILE} or @var{FOLDER}
+Set the default output file to @var{FILE} or, if a folder with that name
+exists, direct the output to @var{FOLDER}, taking the file name from the
+input file.  The appropriate suffix will be added (e.g. @code{.pdf} for
+pdf) in both cases.

 
 

- for SVG (Scalable Vector Graphics).
+@cindex PS (Postscript), output
+@cindex Postscript (PS), output
+@cindex output, PS (Postscript)

 
 

- This creates a single SVG file, without embedded fonts, for every
- page of output.  It is recommended to install the Century
- Schoolbook fonts, included with your LilyPond installation, for
- optimal rendering.  Under UNIX, simply copy these fonts from the
- LilyPond directory (typically
- @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
- @file{~/.fonts/}.  The SVG output should be compatible with any
- SVG editor or user agent.
+@item --ps
+Generate PostScript.

 
 

-@item scm
+@cindex PNG (Portable Network Graphics), output
+@cindex output, PNG (Portable Network Graphics)

 
 

-@cindex Scheme dump
+@item --png
+Generate pictures of each page, in PNG format.  This implies
+@option{--ps}.  The resolution in DPI of the image may be set with
+@example
+-dresolution=110
+@end example

 
 

- for a dump of the raw, internal Scheme-based drawing commands.
+@cindex PDF (Portable Document Format), output
+@cindex output, PDF (Portable Document Format)

 
 

-@item null
- do not output a printed score; has the same effect as @code{-dno-print-pages}.
-@end table
+@item --pdf
+Generate PDF.  This implies @option{--ps}.

 
 

-Example: @code{lilypond -dbackend=svg @var{filename}.ly}
+@item -v,--version
+Show version information.

 
 

-@item preview
-@cindex preview, command line
-Generate an output file containing the titles and the first system
-of music.  If @code{\bookpart} blocks are used, the titles and
-first system of every @code{\bookpart} will appear in the output.
-The @code{ps}, @code{eps}, and @code{svg} backends support this
-option.
+@item -V,--verbose
+Be verbose: show full paths of all files read, and give timing
+information.

 
 

-@item print-pages
-Generate the full pages, the default.  @code{-dno-print-pages} is
-useful in combination with @code{-dpreview}.
+@item -w,--warranty
+Show the warranty with which GNU LilyPond comes.  (It comes with
+@strong{NO WARRANTY}!)

 
 @end table
 
 
 
 @end table
 
 

+@node Advanced command line options for LilyPond
+@unnumberedsubsec Advanced command line options for LilyPond

 
 

-@item -h,--help
-Show a summary of usage.
-
-@item -H,--header=@var{FIELD}
-Dump a header field to file @file{BASENAME.@var{FIELD}}.
+@table @code

 
 

-@item --include, -I=@var{directory}
-Add @var{directory} to the search path for input files.
-@cindex file searching
-@cindex search path
+@item -d@var{[option-name]}=@var{[value]},--define-default=@var{[option-name]}=@var{[value]}
+This sets the equivalent internal Scheme function to @var{value}.  If a
+@var{value} is not supplied, then the default value is used.  The prefix
+@code{no-} may be added to @var{option-name} to switch @q{off} an
+option, e.g.

 
 

-@item -i,--init=@var{file}
-Set init file to @var{file} (default: @file{init.ly}).
+@cindex point and click, command line

 
 

-@item -o,--output=@var{FILE}
-Set the default output file to @var{FILE}.  The appropriate
-suffix will be added (e.g. @code{.pdf} for pdf)
+@example
+-dpoint-and-click=#f
+@end example

 
 

-@cindex PostScript output
+@noindent
+is the same as
+@example
+-dno-point-and-click
+@end example
+@end table

 
 

-@item --ps
-Generate PostScript.
+@noindent The following are supported along with their respective
+default values:
+
+@multitable @columnfractions .33 .16 .51
+@item @strong{Symbol}
+@tab @strong{Value}
+@tab @strong{Explanation/Options}
+
+@item @code{anti-alias-factor}
+@tab @code{1}
+@tab Render at higher resolution (using given factor) and scale down
+result to prevent @q{jaggies} in @code{PNG} images.
+
+@item @code{aux-files}
+@tab @code{#t}
+@tab Create @code{.tex}, @code{.texi}, @code{.count} files in the
+@code{EPS} backend.
+
+@item @code{backend}
+@tab @code{'ps}
+@tab Select backend.  Postscript files (default) include @code{TTF},
+@code{Type1} and @code{OTF} fonts.  No subsetting of these fonts is
+done.  Using @q{oriental} character sets can lead to very large files.
+
+@item
+@tab @code{'eps}
+@tab Encapsulated PostScript.  This dumps every page (system) as a
+separate @file{EPS} file, without fonts, and as one collated @file{EPS}
+file with all pages (systems) including fonts.  Used as default by
+@command{lilypond-book}.
+
+@item
+@tab @code{'null}
+@tab Do not output a printed score; has the same effect as
+@code{-dno-print-pages}.
+
+@item
+@tab @code{'svg}
+@tab Scalable Vector Graphics.  This creates a single @code{SVG} file,
+without embedded fonts, for every page of output.  It is recommended to
+install the Century Schoolbook fonts, included with your LilyPond
+installation, for optimal rendering.  Under UNIX, simply copy these
+fonts from the LilyPond directory (typically
+@file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}.  The
+@code{SVG} output should be compatible with any SVG editor or user
+agent. There is also an option @code{svg-woff} (below) for use of woff
+font files in the SVG backend.
+
+@item
+@tab @code{'scm}
+@tab Dump of the raw, internal Scheme-based drawing commands.
+
+@item @code{check-internal-types}
+@tab @code{#f}
+@tab Check every property assignment for types.
+
+@item @code{clip-systems}
+@tab @code{#f}
+@tab Generate cut-out snippets of a score.
+
+@item @code{datadir}
+@tab
+@tab Prefix for data files (read-only).
+
+@item @code{debug-gc}
+@tab @code{#f}
+@tab Dump memory debugging statistics.
+
+@item @code{debug-gc-assert-parsed-dead}
+@tab @code{#f}
+@tab For memory debugging: Ensure that all references to parsed objects
+are dead. This is an internal option, and is switched on automatically
+for @code{`-ddebug-gc'}.
+
+@item @code{debug-lexer}
+@tab @code{#f}
+@tab Debug the flex lexer.
+
+@item @code{debug-page-breaking-scoring}
+@tab @code{#f}
+@tab Dump scores for many different page breaking configurations.
+
+@item @code{debug-parser}
+@tab @code{#f}
+@tab Debug the bison parser.
+
+@item @code{debug-property-callbacks}
+@tab @code{#f}
+@tab Debug cyclic callback chains.
+
+@item @code{debug-skylines}
+@tab @code{#f}
+@tab Debug skylines.
+
+@item @code{delete-intermediate-files}
+@tab @code{#t}
+@tab Delete the unusable, intermediate @code{.ps} files created during
+compilation.
+
+@item @code{dump-cpu-profile}
+@tab @code{#f}
+@tab Dump timing information (system-dependent).
+
+@item @code{dump-profile}
+@tab @code{#f}
+@tab Dump memory and time information for each file.
+
+@item @code{dump-signatures}
+@tab @code{#f}
+@tab Dump output signatures of each system. Used for regression testing.
+
+@item @code{eps-box-padding}
+@tab @code{#f}
+@tab Pad left edge of the output EPS bounding box by the given amount
+(in mm).
+
+@item @code{gs-load-fonts}
+@tab @code{#f}
+@tab Load fonts via Ghostscript.
+
+@item @code{gs-load-lily-fonts}
+@tab @code{#f}
+@tab Load only the LilyPond fonts via Ghostscript.
+
+@item @code{gui}
+@tab @code{#f}
+@tab Runs silently and redirect all output to a log file.
+@end multitable

 
 

-@cindex Portable Network Graphics (PNG) output
+@noindent
+@strong{Note to Windows users:} By default @code{lilypond.exe} outputs
+all progress information to the command window,
+@code{lilypond-windows.exe} does not and returns a prompt, with no
+progress information, immediately at the command line.  The
+@option{-dgui} option can be used in this case to redirect output to a
+log file.
+
+@multitable @columnfractions .33 .16 .51
+@item @code{help}
+@tab @code{#f}
+@tab Show this help.
+
+@item @code{include-book-title-preview}
+@tab @code{#t}
+@tab Include book titles in preview images.
+
+@item @code{include-eps-fonts}
+@tab @code{#t}
+@tab Include fonts in separate-system EPS files.
+
+@item @code{include-settings}
+@tab @code{#f}
+@tab Include file for global settings, this is included before the score
+is processed.
+
+@item @code{job-count}
+@tab @code{#f}
+@tab Process in parallel, using the given number of jobs.
+
+@item @code{log-file}
+@tab @code{#f [file]}
+@tab If string @code{FOO} is given as a second argument,
+redirect output to the log file @code{FOO.log}.
+
+@item @code{max-markup-depth}
+@tab @code{1024}
+@tab Maximum depth for the markup tree. If a markup has more levels,
+assume it will not terminate on its own, print a warning and return a
+null markup instead.
+
+@item @code{midi-extension}
+@tab @code{"midi"}
+@tab Set the default file extension for MIDI output file to given
+string.
+
+@item @code{music-strings-to-paths}
+@tab @code{#f}
+@tab Convert text strings to paths when glyphs belong to a music font.
+
+@item @code{old-relative}
+@tab @code{#f}
+@tab Make @code{\relative} mode for simultaneous music work similar to
+chord syntax.
+
+@item @code{paper-size}
+@tab @code{\"a4\"}
+@tab Set default paper size.  Note the string must be enclosed in
+escaped double quotes.
+
+@item @code{pixmap-format}
+@tab @code{png16m}
+@tab Set GhostScript's output format for pixel images.
+
+@item @code{point-and-click}
+@tab @code{#f}
+@tab Add @q{point & click} links to @code{PDF} output. See
+@ref{Point and click}.
+
+@item @code{preview}
+@tab @code{#f}
+@tab Create preview images in addition to normal output.
+@end multitable

 
 

-@item --png
-Generate pictures of each page, in PNG format.  This implies
-@code{--ps}.  The resolution in DPI of the image may be set with
-@example
--dresolution=110
-@end example
+@noindent
+This option is supported by all backends; @code{pdf}, @code{png},
+@code{ps}, @code{eps} and @code{svg}, but not @code{scm}.  It generates
+an output file, in the form @code{myFile.preview.extension}, containing
+the titles and the first system of music.  If @code{\book} or
+@code{\bookpart} blocks are used, the titles of @code{\book},
+@code{\bookpart} or @code{\score} will appear in the output, including
+the first system of every @code{\score} block if the @code{\paper}
+variable @code{print-all-headers} is set to @code{#t}.
+
+To suppress the usual output, use the @option{-dprint-pages} or
+@option{-dno-print-pages} options according to your requirements.
+
+@multitable @columnfractions .33 .16 .51
+@item @code{print-pages}
+@tab @code{#t}
+@tab Generate full pages, the default.  @option{-dno-print-pages} is
+useful in combination with @option{-dpreview}.
+
+@item @code{profile-property-accesses}
+@tab @code{#f}
+@tab Keep statistics of @code{get_property()} function calls.
+
+@item @code{protected-scheme-parsing}
+@tab @code{#t}
+@tab Continue when errors in inline scheme are caught in the parser. If
+set to @code{#f}, halt on errors and print a stack trace.
+
+@item @code{read-file-list}
+@tab @code{#f [file]}
+@tab Specify name of a file which contains a list of input files to be
+processed.
+
+@item @code{relative-includes}
+@tab @code{#f}
+@tab When processing an @code{\include} command, look for the included
+file relative to the current file (instead of the root file).
+
+@item @code{resolution}
+@tab @code{101}
+@tab Set resolution for generating @code{PNG} pixmaps to given value (in
+dpi).
+
+@item @code{safe}
+@tab @code{#f}
+@tab Do not trust the @code{.ly} input.
+@end multitable

 
 

-@cindex Portable Document Format (PDF) output
+@noindent
+When LilyPond formatting is available through a web server, either the
+@option{--safe} or the @option{--jail} option @b{MUST} be passed.  The
+@option{--safe} option will prevent inline Scheme code from wreaking
+havoc, e.g,

 
 

-@item --pdf
-Generate PDF.  This implies @code{--ps}.
+@quotation
+@verbatim
+#(system "rm -rf /")
+{
+  c4^$(ly:gulp-file "/etc/passwd")
+}
+@end verbatim
+@end quotation

 
 

+The @option{-dsafe} option works by evaluating in-line Scheme
+expressions in a special safe module.  This is derived from GUILE
+@file{safe-r5rs} module, but also adds a number of functions of the
+LilyPond API which are listed in @file{scm/safe-lily.scm}.

 
 

+In addition, safe mode disallows @code{\include} directives and
+disables the use of backslashes in @TeX{} strings.  It is also not
+possible to import LilyPond variables into Scheme while in safe mode.

 
 

-@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
-Run @command{lilypond} in a chroot jail.
+@option{-dsafe} does @emph{not} detect resource overuse, so it is still
+possible to make the program hang indefinitely, for example by feeding
+cyclic data structures into the backend.  Therefore, if using LilyPond
+on a publicly accessible webserver, the process should be limited in
+both CPU and memory usage.

 
 

-The @code{--jail} option provides a more flexible alternative to
-@code{--safe} when LilyPond formatting is available through a web
-server or whenever LilyPond executes externally provided
-sources.
-
-The @code{--jail} option works by changing the root of @command{lilypond} to
-@var{jail} just before starting the actual compilation process.  The user
-and group are then changed to match those provided, and the current
-directory is changed to @var{dir}.  This setup guarantees that it is not
-possible (at least in theory) to escape from the jail.  Note that for
-@code{--jail} to work @command{lilypond} must be run as root, which is usually
-accomplished in a safe way using @command{sudo}.
+Safe mode will prevent many useful LilyPond snippets from being
+compiled.

 
 

-Setting up a jail is a slightly delicate matter, as we must be sure that
-LilyPond is able to find whatever it needs to compile the source
-@emph{inside the jail}.  A typical setup comprises the following items:
+The @option{--jail} is an even more secure alternative, but requires
+more work to set up. See @ref{Basic command line options for LilyPond}.

 
 

-@table @asis
-@item Setting up a separate filesystem
-A separate filesystem should be created for LilyPond, so that it can be
-mounted with safe options such as @code{noexec}, @code{nodev}, and
-@code{nosuid}.  In this way, it is impossible to run executables or to
-write directly to a device from LilyPond.  If you do not want to create a
-separate partition, just create a file of reasonable size and use it to
-mount a loop device.  A separate filesystem also guarantees that LilyPond
-cannot write more space than it is allowed.
+@multitable @columnfractions .33 .16 .51
+@item @code{separate-log-files}
+@tab @code{#f}
+@tab For input files @code{FILE1.ly}, @code{FILE2.ly}, etc. output log
+data to files @code{FILE1.log}, @code{FILE2.log}, ...

 
 

-@item Setting up a separate user
-A separate user and group (say, @code{lily}/@code{lily}) with low
-privileges should be used to run LilyPond inside the jail.  There should
-be a single directory writable by this user, which should be passed in
-@var{dir}.
+@item @code{show-available-fonts}
+@tab @code{#f}
+@tab List available font names.

 
 

-@item Preparing the jail
-LilyPond needs to read a number of files while running.  All these files
-are to be copied into the jail, under the same path they appear in the
-real root filesystem.  The entire content of the LilyPond installation
-(e.g., @file{/usr/share/lilypond})
-should be copied.
+@item @code{strict-infinity-checking}
+@tab @code{#f}
+@tab Force a crash on encountering @code{Inf} and @code{NaN} floating
+point exceptions.

 
 

-If problems arise, the simplest way to trace them down is to run
-LilyPond using @command{strace}, which will allow you to determine which
-files are missing.
+@item @code{strip-output-dir}
+@tab @code{#t}
+@tab Don't use directories from input files while constructing output
+file names.

 
 

-@item Running LilyPond
-In a jail mounted with @code{noexec} it is impossible to execute any external
-program.  Therefore LilyPond must be run with a backend that does not
-require any such program.  As we already mentioned, it must be also run
-with superuser privileges (which, of course, it will lose immediately),
-possibly using @command{sudo}.  It is a good idea to limit the number of
-seconds of CPU time LilyPond can use (e.g., using @command{ulimit
--t}), and, if your operating system supports it, the amount of memory
-that can be allocated.
-@end table
+@item @code{svg-woff}
+@tab @code{#f}
+@tab Use woff font files in SVG backend.

 
 

+@item @code{trace-memory-frequency}
+@tab @code{#f}
+@tab Record Scheme cell usage this many times per second.  Dump the
+results to @code{FILE.stacks} and @code{FILE.graph}.

 
 

-@item -v,--version
-Show version information.
+@item @code{trace-scheme-coverage}
+@tab @code{#f}
+@tab Record coverage of Scheme files in @code{FILE.cov}.

 
 

-@item -V,--verbose
-Be verbose: show full paths of all files read, and give timing
-information.
+@item @code{verbose}
+@tab @code{#f}
+@tab Verbose output, i.e. loglevel at DEBUG (read-only).

 
 

-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
+@item @code{warning-as-error}
+@tab @code{#f}
+@tab Change all warning and @q{programming error} messages into errors.
+@end multitable

 
 
 @node Environment variables
 @unnumberedsubsec Environment variables
 
 
 
 @node Environment variables
 @unnumberedsubsec Environment variables
 

-

 @cindex LANG
 @cindex LILYPOND_DATADIR
 
 @cindex LANG
 @cindex LILYPOND_DATADIR
 


@@ -411,11 +703,15 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 @item LANG
 This selects the language for the warning messages.
 
 @item LANG
 This selects the language for the warning messages.
 

+@item LILYPOND_LOGLEVEL
+The default loglevel. If LilyPond is called without an explicit loglevel
+(i.e. no @option{--loglevel} command line option), this value is used.
+

 @item LILYPOND_GC_YIELD
 @item LILYPOND_GC_YIELD

-With this variable the memory footprint and performance can be
-adjusted.  It is a percentage tunes memory management behavior.  With
-higher values, the program uses more memory, with smaller values, it
-uses more CPU time.  The default value is @code{70}.
+A variable, as a percentage, that tunes memory management
+behavior.  A higher values means the program uses more memory, a
+smaller value means more CPU time is used.  The default value is
+@code{70}.

 
 @end table
 
 
 @end table
 


@@ -438,8 +734,8 @@ adduser lily
 @end example
 
 @noindent
 @end example
 
 @noindent

-This will create a new group for the @code{lily} user as well, and a home folder,
-@code{/home/lily}
+This will create a new group for the @code{lily} user as well, and a
+home folder, @code{/home/lily}

 
 @item In the home folder of the @code{lily} user create a file to use as a
 separate filesystem:
 
 @item In the home folder of the @code{lily} user create a file to use as a
 separate filesystem:


@@ -473,7 +769,10 @@ You can use @code{sed} to create the necessary copy commands for a given
 executable:
 
 @example
 executable:
 
 @example

-for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done
+for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
+  do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
+    cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
+      \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done

 @end example
 
 @end itemize
 @end example
 
 @end itemize


@@ -514,18 +813,25 @@ cp -L /usr/bin/convert /usr/bin/gs usr/bin
 cp -L /usr/share/fonts/truetype usr/share/fonts
 
 # Now the library copying magic
 cp -L /usr/share/fonts/truetype usr/share/fonts
 
 # Now the library copying magic

-for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done | sh -s
+for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
+  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
+    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
+      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
+        | sed '/.*=>.*/d'; done | sh -s

 
 # The shared files for ghostscript...
       cp -L -r /usr/share/ghostscript usr/share
 # The shared files for ImageMagick
       cp -L -r /usr/lib/ImageMagick* usr/lib
 
 
 # The shared files for ghostscript...
       cp -L -r /usr/share/ghostscript usr/share
 # The shared files for ImageMagick
       cp -L -r /usr/lib/ImageMagick* usr/lib
 

-### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome, you should be able to run:
-### Note that /$lilyprefix/bin/lilypond is a script, which sets the LD_LIBRARY_PATH - this is crucial
+### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
+### you should be able to run:
+### Note that /$lilyprefix/bin/lilypond is a script, which sets the
+### LD_LIBRARY_PATH - this is crucial

       /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
 @end example
 
       /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
 @end example
 

+@c " keep quote signs balanced for context-sensitive editors

 
 @node Error messages
 @section Error messages
 
 @node Error messages
 @section Error messages


@@ -558,8 +864,8 @@ happens rarely.  The most usual cause is misinstalled fonts.
 @cindex call trace
 @cindex Scheme error
 Errors that occur while executing Scheme code are caught by the Scheme
 @cindex call trace
 @cindex Scheme error
 Errors that occur while executing Scheme code are caught by the Scheme

-interpreter.  If running with the verbose option (@code{-V} or
-@code{--verbose}) then a call trace of the offending
+interpreter.  If running with the verbose option (@option{-V} or
+@option{--verbose}) then a call trace of the offending

 function call is printed.
 
 @item Programming error
 function call is printed.
 
 @item Programming error


@@ -577,9 +883,8 @@ send a bug-report.
 @end table
 
 @cindex errors, message format
 @end table
 
 @cindex errors, message format

-If warnings and errors can
-be linked to some part of the input file, then error messages have the
-following form
+If warnings and errors can be linked to some part of the input file,
+then error messages have the following form

 
 @example
 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
 
 @example
 @var{filename}:@var{lineno}:@var{columnno}: @var{message}


@@ -618,6 +923,7 @@ are easily handled.
 * Apparent error in ../ly/init.ly::
 * Error message Unbound variable %::
 * Error message FT_Get_Glyph_Name::
 * Apparent error in ../ly/init.ly::
 * Error message Unbound variable %::
 * Error message FT_Get_Glyph_Name::

+* Warning staff affinities should only decrease::

 @end menu
 
 @node Music runs off the page
 @end menu
 
 @node Music runs off the page


@@ -707,7 +1013,7 @@ problem:
 @unnumberedsubsec Apparent error in @code{../ly/init.ly}
 
 Various obscure error messages may appear about syntax errors in
 @unnumberedsubsec Apparent error in @code{../ly/init.ly}
 
 Various obscure error messages may appear about syntax errors in

-@code{../ly/init.ly} if the input file is not correctly formed,
+@file{../ly/init.ly} if the input file is not correctly formed,

 for example, if it does not contain correctly
 matched braces or quote signs.
 
 for example, if it does not contain correctly
 matched braces or quote signs.
 


@@ -723,7 +1029,7 @@ of a lyrics block and the terminating brace, (@code{@}}).  Without
 this separation the brace is taken to be part of the syllable.  It
 is always advisable to ensure there is white space before and after
 @emph{every} brace.  For the importance of this when using lyrics,
 this separation the brace is taken to be part of the syllable.  It
 is always advisable to ensure there is white space before and after
 @emph{every} brace.  For the importance of this when using lyrics,

-see @ruser{Lyrics explained}.
+see @ruser{Entering lyrics}.

 
 This error message can also appear if a terminating quote sign,
 (@code{"}), is omitted.  In this case an accompanying error message
 
 This error message can also appear if a terminating quote sign,
 (@code{"}), is omitted.  In this case an accompanying error message


@@ -735,7 +1041,7 @@ mismatched quote will usually be on the line one or two above.
 @unnumberedsubsec Error message Unbound variable %
 
 This error message will appear at the bottom of the console
 @unnumberedsubsec Error message Unbound variable %
 
 This error message will appear at the bottom of the console

-output or log file together with a @qq{GUILE signalled an error ...}
+output or log file together with a @qq{GUILE signalled an error @dots{}}

 message every time a Scheme routine is called which (invalidly)
 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
 
 message every time a Scheme routine is called which (invalidly)
 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
 


@@ -751,4 +1057,18 @@ an input file contains a non-ASCII character and was not saved in
 UTF-8 encoding.  For details, see @ruser{Text encoding}.
 
 
 UTF-8 encoding.  For details, see @ruser{Text encoding}.
 
 

+@node Warning staff affinities should only decrease
+@unnumberedsubsec Warning staff affinities should only decrease
+This warning can appear if there are no staves in the printed
+output, for example if there are just a @code{ChordName} context
+and a @code{Lyrics} context as in a lead sheet.  The warning
+messages can be avoided by making one of the contexts behave as a
+staff by inserting

 
 

+@example
+\override VerticalAxisGroup #'staff-affinity = ##f
+@end example
+
+@noindent
+at its start.  For details, see @qq{Spacing of non-staff lines} in
+@ruser{Flexible vertical spacing within systems}.