X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=7522cec85b74b3aca677cd51454e89a81e985751;hb=f7085cf9b2ff111b7d30c8a59e367c771a7e3c52;hp=03a822fd2b2ad409520068ceb60d2865a1b1feb7;hpb=aa8523e4fa16352a1708065e447aac65426d82a4;p=lilypond.git

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 03a822fd2b..7522cec85b 100644
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -4,10 +4,11 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.15.18"
 
 
 @node Running lilypond
@@ -16,12 +17,10 @@
 This chapter details the technicalities of running LilyPond.
 
 @menu
-* Normal usage::                
-* Command-line usage::          
-* Error messages::              
-* Common errors::               
-* Point and click::             
-* Text editor support::         
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Common errors::
 @end menu
 
 
@@ -29,7 +28,7 @@ This chapter details the technicalities of running LilyPond.
 @section Normal usage
 
 Most users run LilyPond through a GUI; if you have not done so
-already, read @rlearning{Introduction}.  If you use an alternate
+already, please read the @rlearning{Tutorial}.  If you use an alternate
 editor to write lilypond files, see the documentation for that
 program.
 
@@ -46,16 +45,18 @@ By @q{command-line}, we mean the command line in the operating system.
 Windows users might be more familiar with the terms @q{DOS shell} or
 @q{command shell}.  MacOS@tie{}X users might be more familiar with the terms
 @q{terminal} or @q{console}.  Some additional setup is required
-for MacOS@tie{}X users; please see @rgeneral{MacOS X}.
+for MacOS@tie{}X users; please see @rweb{MacOS X}.
 
 Describing how to use this part of an operating system is outside the
 scope of this manual; please consult other documentation on this topic
 if you are unfamiliar with the command-line.
 
 @menu
-* Invoking lilypond::           
-* Command line options for lilypond::  
-* Environment variables::       
+* Invoking lilypond::
+* Basic command line options for LilyPond::
+* Advanced command line options for LilyPond::
+* Environment variables::
+* LilyPond in chroot jail::
 @end menu
 
 @node Invoking lilypond
@@ -97,8 +98,32 @@ will output @var{base}@file{-violin.pdf} and
 @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}
@@ -109,9 +134,15 @@ The following options are supported:
 
 @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.
-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
@@ -131,268 +162,534 @@ on the command-line, and include
 @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{svg}, @code{ps}, @code{pdf}, and @code{png}.
+@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, encapulated
-@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
+@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
 
 
+@node Advanced command line options for LilyPond
+@unnumberedsubsec Advanced command line options for LilyPond
 
-@item -h,--help
-Show a summary of usage.
+@table @code
 
-@item -H,--header=@var{FIELD}
-Dump a header field to file @file{BASENAME.@var{FIELD}}.
+@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 --include, -I=@var{directory}
-Add @var{directory} to the search path for input files.
-@cindex file searching
-@cindex search path
+@cindex point and click, command line
 
-@item -i,--init=@var{file}
-Set init file to @var{file} (default: @file{init.ly}).
+@example
+-dpoint-and-click=#f
+@end example
 
-@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)
+@noindent
+is the same as
+@example
+-dno-point-and-click
+@end example
+@end table
 
-@cindex PostScript output
+@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
 
-@item --ps
-Generate PostScript.
+@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
 
-@cindex Portable Network Graphics (PNG) output
+@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
 
-@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
+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,
 
-@cindex Portable Document Format (PDF) output
+@quotation
+@verbatim
+#(system "rm -rf /")
+{
+  c4^$(ly:gulp-file "/etc/passwd")
+}
+@end verbatim
+@end quotation
 
-@item --pdf
-Generate PDF.  This implies @code{--ps}.
+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.
 
+@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.
 
-@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
-Run @command{lilypond} in a chroot jail.
+Safe mode will prevent many useful LilyPond snippets from being
+compiled.
 
-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}.
+The @option{--jail} is an even more secure alternative, but requires
+more work to set up. See @ref{Basic command line options for LilyPond}.
 
-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:
+@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}, ...
 
-@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.
+@item @code{show-available-fonts}
+@tab @code{#f}
+@tab List available font names.
 
-@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{strict-infinity-checking}
+@tab @code{#f}
+@tab Force a crash on encountering @code{Inf} and @code{NaN} floating
+point exceptions.
 
-@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{strip-output-dir}
+@tab @code{#t}
+@tab Don't use directories from input files while constructing output
+file names.
 
-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{svg-woff}
+@tab @code{#f}
+@tab Use woff font files in SVG backend.
 
-@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{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 @code{trace-scheme-coverage}
+@tab @code{#f}
+@tab Record coverage of Scheme files in @code{FILE.cov}.
 
-@item -v,--version
-Show version information.
+@item @code{verbose}
+@tab @code{#f}
+@tab Verbose output, i.e. loglevel at DEBUG (read-only).
 
-@item -V,--verbose
-Be verbose: show full paths of all files read, and give timing
-information.
+@item @code{warning-as-error}
+@tab @code{#f}
+@tab Change all warning and @q{programming error} messages into errors.
+@end multitable
 
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
 
 @node Environment variables
 @unnumberedsubsec Environment variables
 
-
 @cindex LANG
 @cindex LILYPOND_DATADIR
 
@@ -406,15 +703,136 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 @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
-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
 
 
+@node LilyPond in chroot jail
+@unnumberedsubsec LilyPond in chroot jail
+
+Setting up the server to run LilyPond in a chroot jail is a complicated
+task.  The steps are listed below.  Examples in the steps are from
+Ubuntu Linux, and may require the use of @code{sudo} as appropriate.
+
+@itemize
+
+@item Install the necessary packages: LilyPond, GhostScript, and ImageMagick.
+
+@item Create a new user by the name of @code{lily}:
+
+@example
+adduser lily
+@end example
+
+@noindent
+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:
+
+@example
+dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
+@end example
+
+@noindent
+This example creates a 200MB file for use as the jail filesystem.
+
+@item Create a loop device, make a file system and mount it, then create
+a folder that can be written by the @code{lily} user:
+
+@example
+mkdir /mnt/lilyloop
+losetup /dev/loop0 /home/lily/loopfile
+mkfs -t ext3 /dev/loop0 200000
+mount -t ext3 /dev/loop0 /mnt/lilyloop
+mkdir /mnt/lilyloop/lilyhome
+chown lily /mnt/lilyloop/lilyhome
+@end example
+
+@item In the configuration of the servers, the JAIL will be @code{/mnt/lilyloop}
+and the DIR will be @code{/lilyhome}.
+
+@item Create a big directory tree in the jail by copying the necessary files, as
+shown in the sample script below.
+
+You can use @code{sed} to create the necessary copy commands for a given
+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
+@end example
+
+@end itemize
+
+@subheading Example script for 32-bit Ubuntu 8.04
+
+@example
+#!/bin/sh
+## defaults set here
+
+username=lily
+home=/home
+loopdevice=/dev/loop0
+jaildir=/mnt/lilyloop
+# the prefix (without the leading slash!)
+lilyprefix=usr/local
+# the directory where lilypond is installed on the system
+lilydir=/$lilyprefix/lilypond/
+
+userhome=$home/$username
+loopfile=$userhome/loopfile
+adduser $username
+dd if=/dev/zero of=$loopfile bs=1k count=200000
+mkdir $jaildir
+losetup $loopdevice $loopfile
+mkfs -t ext3 $loopdevice 200000
+mount -t ext3 $loopdevice $jaildir
+mkdir $jaildir/lilyhome
+chown $username $jaildir/lilyhome
+cd $jaildir
+
+mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
+chmod a+w tmp
+
+cp -r -L $lilydir $lilyprefix
+cp -L /bin/sh /bin/rm bin
+cp -L /usr/bin/convert /usr/bin/gs usr/bin
+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
+
+# 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
+      /$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
 
@@ -446,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
-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
@@ -465,9 +883,8 @@ send a bug-report.
 @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}
@@ -501,11 +918,12 @@ are easily handled.
 
 
 @menu
-* Music runs off the page::     
-* An extra staff appears::      
-* Apparent error in ../ly/init.ly::  
-* Error message Unbound variable %::  
-* Error message FT_Get_Glyph_Name::  
+* Music runs off the page::
+* An extra staff appears::
+* 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
@@ -537,17 +955,17 @@ line to break.  For details, see @ruser{Bar lines}.
 @node An extra staff appears
 @unnumberedsubsec An extra staff appears
 
-If contexts are not created explicitly with @code{\new} they will be
-silently created as soon as a command is encountered which cannot
-be applied to an existing context.  In simple scores the automatic
-creation of contexts is useful, and most of the examples in the
-LilyPond manuals take advantage of this simplification.  But
-occasionally the silent creation of contexts can give rise to
-unexpected new staves or scores.  For example, it might be expected
-that the following code would cause all note heads within the
-following staff to be colored red, but in fact it results in two
-staves with the note heads remaining the default black in the lower
-staff.
+If contexts are not created explicitly with @code{\new} or
+@code{\context}, they will be silently created as soon as a
+command is encountered which cannot be applied to an existing
+context.  In simple scores the automatic creation of contexts is
+useful, and most of the examples in the LilyPond manuals take
+advantage of this simplification.  But occasionally the silent
+creation of contexts can give rise to unexpected new staves or
+scores.  For example, it might be expected that the following code
+would cause all note heads within the following staff to be
+colored red, but in fact it results in two staves with the note
+heads remaining the default black in the lower staff.
 
 @lilypond[quote,verbatim,relative=2]
 \override Staff.NoteHead #'color = #red
@@ -568,23 +986,25 @@ correct code to color all note heads red is
 @end lilypond
 
 As a second example, if a @code{\relative} command is placed inside
-a @code{\repeat} command two staves result, the second offset from
+a @code{\repeat} command, two staves result, the second offset from
 the first, because the @code{\repeat} command generates two
 @code{\relative} blocks, which each implicitly create @code{Staff}
 and @code{Voice} blocks.
 
 @lilypond[quote,verbatim]
 \repeat unfold 2 {
-  \relative c' { c d e f }
+  \relative c' { c4 d e f }
 }
 @end lilypond
 
-The correct way is to reverse the @code{\repeat} and
-@code{\relative} commands, like this:
+Explicitly instantiating the @code{Voice} context fixes the
+problem:
 
 @lilypond[quote,verbatim]
-\relative c' {
-  \repeat unfold 2 { c d e f }
+\new Voice {
+  \repeat unfold 2 {
+    \relative c' { c4 d e f }
+  }
 }
 @end lilypond
 
@@ -593,7 +1013,7 @@ The correct way is to reverse the @code{\repeat} and
 @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.
 
@@ -609,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,
-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
@@ -621,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
-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.
 
@@ -637,176 +1057,18 @@ an input file contains a non-ASCII character and was not saved in
 UTF-8 encoding.  For details, see @ruser{Text encoding}.
 
 
-@node Point and click
-@section Point and click
-
-@cindex point and click
-
-Point and click lets you find notes in the input by clicking on them
-in the PDF viewer.  This makes it easier to find input that causes
-some error in the sheet music.
-
-When this functionality is active, LilyPond adds hyperlinks to the PDF
-file.  These hyperlinks are sent to the web-browser, which opens a
-text-editor with the cursor in the right place.
-
-To make this chain work, you should configure your PDF viewer to
-follow hyperlinks using the @file{lilypond-invoke-editor} script
-supplied with LilyPond.
-
-For Xpdf on UNIX, the following should be present in
-@file{xpdfrc}@footnote{On UNIX, this file is found either in
-@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
+@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
-urlCommand     "lilypond-invoke-editor %s"
-@end example
-
-The program @file{lilypond-invoke-editor} is a small helper
-program.  It will invoke an editor for the special @code{textedit}
-URIs, and run a web browser for others.  It tests the environment
-variable @code{EDITOR} for the following patterns,
-
-@table @code
-@item emacs
-  this will invoke
-@example
-emacsclient --no-wait +@var{line}:@var{column} @var{file}
-@end example
-@item vim
-  this will invoke
-@example
-gvim --remote +:@var{line}:norm@var{char} @var{file}
-@end example
-
-@item nedit
-this will invoke
-@example
-  nc -noask +@var{line} @var{file}'
-@end example
-@end table
-
-The environment variable @code{LYEDITOR} is used to override this.  It
-contains the command line to start the editor, where @code{%(file)s},
-@code{%(column)s}, @code{%(line)s} is replaced with the file, column
-and line respectively.  The  setting
-
-@example
-emacsclient --no-wait +%(line)s:%(column)s %(file)s
-@end example
-
-@noindent
-for @code{LYEDITOR} is equivalent to the standard emacsclient
-invocation.
-
-
-@cindex file size, output
-
-The point and click links enlarge the output files significantly.  For
-reducing the size of PDF and PS files, point and click may be switched
-off by issuing
-
-@example
-\pointAndClickOff
+\override VerticalAxisGroup #'staff-affinity = ##f
 @end example
 
 @noindent
-in a @file{.ly} file.  Point and click may be explicitly enabled with
-
-@example
-\pointAndClickOn
-@end example
-
-Alternately, you may disable point and click with a command-line
-option:
-
-@example
-lilypond -dno-point-and-click file.ly
-@end example
-
-@warning{You should always turn off point and click in any LilyPond
-files to be distributed to avoid including path information about
-your computer in the .pdf file, which can pose a security risk.}
-@node Text editor support
-@section Text editor support
-
-@cindex editors
-@cindex vim
-@cindex emacs
-@cindex modes, editor
-@cindex syntax coloring
-@cindex coloring, syntax
-
-There is support for different text editors for LilyPond.
-
-@menu
-* Emacs mode::                  
-* Vim mode::                    
-* Other editors::
-@end menu
-
-@node Emacs mode
-@unnumberedsubsec Emacs mode
-
-Emacs has a @file{lilypond-mode}, which provides keyword
-autocompletion, indentation, LilyPond specific parenthesis matching
-and syntax coloring, handy compile short-cuts and reading LilyPond
-manuals using Info.  If @file{lilypond-mode} is not installed on your
-platform, see below.
-
-An Emacs mode for entering music and running LilyPond is contained in
-the source archive in the @file{elisp} directory.  Do @command{make
-install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
-should be placed to @var{load-path}@file{/site-start.d/} or appended
-to your @file{~/.emacs} or @file{~/.emacs.el}.
-
-As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
-your @var{load-path} by appending the following line (as modified) to your
-@file{~/.emacs}
-
-@c any reason we do not advise:  (push "~/site-lisp" load-path)
-@example
-(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
-@end example
-
-
-@node Vim mode
-@unnumberedsubsec Vim mode
-
-For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
-along with syntax coloring tools.  A Vim mode for entering music and
-running LilyPond is contained in the source archive in @code{$VIM}
-directory.
-
-The LilyPond file type is detected if the file
-@file{~/.vim/filetype.vim} has the following content
-
-@example
-if exists("did_load_filetypes")
-  finish
-endif
-augroup filetypedetect
-  au! BufNewFile,BufRead *.ly,*.ily           setf lilypond
-augroup END
-@end example
-
-Please include this path by appending the following line to your
-@file{~/.vimrc}
-
-@example
-set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
-@end example
-
-@noindent
-where $@{LILYPOND_VERSION@} is your LilyPond version.  If LilyPond was not
-installed in @file{/usr/local/}, then change this path accordingly.
-
-
-@node Other editors
-@unnumberedsubsec Other editors
-
-Other editors (both text and graphical) support LilyPond, but
-their special configuration files are not distributed with
-LilyPond.  Consult their documentation for more information.  Such
-editors are listed in @rgeneral{Alternate editors}.
-
+at its start.  For details, see @qq{Spacing of non-staff lines} in
+@ruser{Flexible vertical spacing within systems}.