Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.18"
+@c \version "2.17.6"
@node Running lilypond
if you are unfamiliar with the command-line.
@menu
-* Invoking lilypond::
-* Command line options for lilypond::
+* 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
+@node Invoking LilyPond
@unnumberedsubsec Invoking @command{lilypond}
The @command{lilypond} executable may be called as follows from
lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example
-
When invoked with a filename that has no extension, the @file{.ly}
extension is tried first. To read input from stdin, use a
dash (@code{-}) for @var{file}.
@var{base}@file{-cello-1.pdf}.
-@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:
+@unnumberedsubsubsec Using LilyPond with standard shell features
-@itemize
+Since LilyPond is a command line application, features of the @q{shell}
+used for calling LilyPond can also be put to good use.
-@item
-@code{lilypond file.ly 1>stdout.log} to redirect normal output
+For example:
-@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.
+@example
+lilypond *.ly
+@end example
+@noindent
+will process all LilyPond files in the current directory.
-@node Command line options for lilypond
-@unnumberedsubsec Command line options for @command{lilypond}
+Redirecting the console output (e.g. to a file) may also be useful:
-@cindex Invoking @command{lilypond}
-@cindex command line options for @command{lilypond}
-@cindex options, command line
-@cindex switches
+@example
+lilypond file.ly 1> stdout.txt
-The following options are supported:
+lilypond file.ly 2> stderr.txt
-@table @code
+lilypond file.ly &> all.txt
+@end example
-@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.
+@noindent
+Redirects @q{normal} output, @q{errors} only or @q{everything},
+respectively, to a text file. Consult the documentation for your
+particular shell, Command (Windows), Terminal or Console
+applications (MacOS X) to see if output redirection is supported or if
+the syntax is different.
-@cindex point and click, command line
+The following example searches and processes all input files in the
+current directory and all directories below it recursively. The output
+files will be located in the same directory that the command was run in,
+rather than in the same directories as the original input files.
@example
--dno-point-and-click
+find . -name '*.ly' -exec lilypond '@{@}' \;
@end example
@noindent
-is the same as
-@example
--dpoint-and-click=#f
-@end example
-
-The following options are supported:
-
-@cindex help, command line
-
-@table @code
+This should also work for MacOS@tie{}X users.
-@item help
-Running @code{lilypond -dhelp} will print all of the @option{-d} options
-available.
+A Windows user would run;
-@cindex paper-size, command line
-
-@item paper-size
-This option sets the default paper-size,
@example
--dpaper-size=\"letter\"
+forfiles /s /M *.ly /c "cmd /c lilypond @@file"
@end example
@noindent
-Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-@c Match " in previous line to help context-sensitive editors
-
-@cindex safe, command line
-
-@item safe
-Do not trust the @code{.ly} input.
-
-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, for example
+entering these commands in a @code{command prompt} usually found under
+@code{Start > Accessories > Command Prompt} or for version 8 users,
+by typing in the search window @q{command prompt}.
-@quotation
-@verbatim
-#(system "rm -rf /")
-{
- c4^$(ly:gulp-file "/etc/passwd")
-}
-@end verbatim
-@end quotation
+Alternatively, an explicit path to the top-level of your folder
+containing all the sub-folders that have input files in them can be
+stated using the @code{/p} option;
-The @option{-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}.
+@example
+forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @@file"
+@end example
-In addition, safe mode disallows @code{\include} directives and
-disables the use of backslashes in @TeX{} strings.
+If there are spaces in the path to the top-level folder, then the whole
+path needs to be inside double quotes;
-In safe mode, it is not possible to import LilyPond variables into
-Scheme.
+@example
+forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @@file"
+@end example
-@option{-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.
-Safe mode will prevent many useful LilyPond snippets from being
-compiled. The @option{--jail} is a more secure alternative, but
-requires more work to set up.
+@node Basic command line options for LilyPond
+@unnumberedsubsec Basic command line options for LilyPond
-@cindex output format, setting
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}
+@cindex options, command line
+@cindex switches
-@item backend
-the output format to use for the backend. Choices for @code{format}
-are:
+The following options are supported:
@table @code
-@item ps
-
-@cindex PostScript output
-
-for PostScript.
-
-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 eps
-
-@cindex Postscript, encapsulated
-@cindex EPS (Encapsulated PostScript)
-
-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.
-
-This mode is used by default by @command{lilypond-book}.
-
-@item svg
-
-@cindex SVG (Scalable Vector Graphics)
-
-for SVG (Scalable Vector Graphics).
-
-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 scm
-
-@cindex Scheme dump
-@cindex output, Scheme dump
-
-for a dump of the raw, internal Scheme-based drawing commands.
-
-@item null
-do not output a printed score; has the same effect as
-@option{-dno-print-pages}.
-@end table
+@item -b, --bigpdfs
+@cindex bigpdfs
-Example: @code{lilypond -dbackend=svg @var{filename}.ly}
+PDF files generated will be much larger than normal (due to little or no
+font optimization). However, if two or more PDF files are included
+within @w{@code{pdftex}}, @w{@code{xetex}} or @w{@code{luatex}}
+documents they can then be processed further via ghostscript (merging
+duplicated font data) resulting in @emph{significantly} smaller PDF
+files.
-@item preview
+@example
+lilypond -b myfile
+@end example
-@cindex preview, command line
+Then run @code{ghostscript};
-This option is supported by all backends; @code{pdf}, @code{png},
-@code{ps}, @code{eps} and @code{svg}, but not @code{scm} and generates
-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.
-
-An additional file in the form @code{myFile.preview.extensio} is
-generated, to avoid this use the additional @option{-dprint-pages} or
-@option{-dno-print-pages} options according to your requirements.
+@example
+gs -q -sDEVICE=pdfwrite -o gsout.pdf myfile.pdf
+@end example
-@item gui
-Runs silently and redirect all output to a log file.
+@code{pdfsizeopt.py} can then be used to further optimize the size
+of file;
-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.
+@example
+pdfsizeopt.py --use-multivalent=no gsout.pdf final.pdf
+@end example
-@item print-pages
-Generate the full pages, the default. @option{-dno-print-pages} is
-useful in combination with @option{-dpreview}.
-@end table
+@item -d, --define-default=@var{var}=@var{val}
+See @ref{Advanced command line options for LilyPond}.
@cindex Scheme, expression evaluation
-@cindex expression evalusation, Scheme
+@cindex expression evaluation, Scheme
-@item -e,--evaluate=@var{expr}
+@item -e, --evaluate=@var{expr}
Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
Multiple @option{-e} options may be given, they will be evaluated
sequentially.
@cindex output, format
@cindex format, output
-@item -f,--format=@var{format}
+@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
+@noindent
+For @code{svg} and @code{eps} formats use the @code{-dbackend} option.
+See @ref{Advanced command line options for LilyPond}.
+
+@item -h, --help
Show a summary of usage.
-@item -H,--header=@var{FIELD}
+@item -H, --header=@var{FIELD}
Dump a header field to file @file{BASENAME.@var{FIELD}}.
-@item -i,--init=@var{file}
+@item -i, --init=@var{file}
Set init file to @var{file} (default: @file{init.ly}).
@cindex file searching
@cindex chroot jail, running inside
-@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+@item -j, --jail=@var{user},@var{group},@var{jail},@var{dir}
Run @command{lilypond} in a chroot jail.
The @option{--jail} option provides a more flexible alternative to
-@option{--safe} when LilyPond formatting is available through a web
-server or whenever LilyPond executes externally provided
-sources.
-
-The @option{--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 @option{--jail} to work @command{lilypond} must
-be run as root, which is usually accomplished in a safe way using
-@command{sudo}.
-
-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:
+@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}.
+
+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:
@table @asis
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.
+(e.g., @file{/usr/share/lilypond}) should be copied.
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 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.
-
+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
@cindex loglevel
@cindex output, verbosity
-@item -l,--loglevel=@var{LEVEL}
+@item -l, --loglevel=@var{LEVEL}
Set the verbosity of the console output to @var{LEVEL}. Possible values
are:
@cindex output, setting filename
@cindex output, directory
-@item -o,--output=@var{FILE} or @var{FOLDER}
+@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
@item --pdf
Generate PDF. This implies @option{--ps}.
-@item -v,--version
+@item -v, --version
Show version information.
-@item -V,--verbose
+@item -V, --verbose
Be verbose: show full paths of all files read, and give timing
information.
-@item -w,--warranty
+@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
+
+@table @code
+
+@item -d@var{[option-name]}=@var{[value]},
+--define-default=@var{[option-name]}=@var{[value]}
+This sets the equivalent internal Scheme function to @var{value}. For
+example;
+
+@example
+-dbackend=svg
+@end example
+
+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. For example;
+
+@cindex point and click, command line
+
+@example
+-dpoint-and-click=#f
+@end example
+
+@noindent
+is the same as
+@example
+-dno-point-and-click
+@end example
+@end table
+
+@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 a higher resolution (using the given factor) and scale
+down the result to prevent @q{jaggies} in @code{PNG} images.
+
+@item @code{aux-files}
+@tab @code{#t}
+@tab Create @code{.tex}, @code{.texi} and @code{.count} files when used
+with the @code{eps} backend option.
+
+@item @code{backend}
+@tab @code{ps}
+@tab This is the default setting. Postscript files (default) include
+@code{TTF}, @code{Type1} and @code{OTF} fonts. No @q{subsetting} of
+these fonts is done. Be aware that using @q{oriental} character sets
+can lead to very large file sizes.
+
+@item
+@tab @code{eps}
+@tab Used as default by the @command{lilypond-book} command. This dumps
+every page as both a single file with all pages and fonts included and
+as separate encapsulated postscript files for each page but without fonts
+included.
+
+@item
+@tab @code{null}
+@tab Do not output a printed score. This has the same effect as
+@code{-dno-print-pages}.
+
+@item
+@tab @code{scm}
+@tab This dumps out the raw, internal Scheme-based drawing commands.
+
+@item
+@tab @code{svg}
+@tab Scalable Vector Graphics.
+A single SVG file is created for every page of output. Music glyphs
+are encoded as vector graphics, but text fonts are @emph{not} embedded
+in the SVG files. Any SVG viewer will therefore need the relevant text
+fonts to be available to it for proper rendering of both text and
+lyrics. It is recommended to not use font @q{lists} or @q{aliases}
+in case an SVG viewer is unable to handle them. When using
+@emph{Web Open Font Format} (WOFF) files the additional
+@code{--svg-woff} switch is required.
+
+@item @code{check-internal-types}
+@tab @code{#f}
+@tab Check every property assignment for types.
+
+@item @code{clip-systems}
+@tab @code{#f}
+@tab Extract music fragments out of a score. This requires that the
+@code{clip-regions} function has been defined within the @code{\layout}
+block. See @ruser{Extracting fragments of music}. No fragments are
+extracted though if used with the @option{-dno-print-pages} option.
+
+@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{embed-source-code}
+@tab @code{#f}
+@tab Embed the LilyPond source files inside the generated PDF document.
+
+@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{font-export-dir}
+@tab @code{#f [dir]}
+@tab Directory for exporting fonts as PostScript files.
+
+@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{gs-never-embed-fonts}
+@tab @code{#f}
+@tab Make Ghostscript embed only TrueType fonts and no other font format.
+
+@item @code{gui}
+@tab @code{#f}
+@tab Runs silently and redirect all output to a log file.
+@end multitable
+
+@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{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{#t}
+@tab Add @q{point & click} links to PDF and SVG output.
+See @ref{Point and click}.
+
+@item @code{preview}
+@tab @code{#f}
+@tab Create preview images in addition to normal output.
+@end multitable
+
+@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
+
+@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,
+
+@quotation
+@verbatim
+#(s ystem "rm -rf /") % too dangerous to write correctly
+{
+ c4^$(ly:gulp-file "/etc/passwd") % malicious but not destructive
+}
+@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.
+
+@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.
+
+Safe mode will prevent many useful LilyPond snippets from being
+compiled.
+
+The @option{--jail} is an even more secure alternative, but requires
+more work to set up. See @ref{Basic command line options for LilyPond}.
+
+@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}@dots{}
+
+@item @code{show-available-fonts}
+@tab @code{#f}
+@tab List available font names.
+
+@item @code{strict-infinity-checking}
+@tab @code{#f}
+@tab Force a crash on encountering @code{Inf} and @code{NaN} floating
+point exceptions.
+
+@item @code{strip-output-dir}
+@tab @code{#t}
+@tab Don't use directories from input files while constructing output
+file names.
+
+@item @code{strokeadjust}
+@tab @code{#f}
+@tab Force PostScript stroke adjustment. This option is mostly
+relevant when a PDF is generated from PostScript output (stroke
+adjustment is usually enabled automatically for low-resolution bitmap
+devices). Without this option, PDF previewers tend to produce widely
+inconsistent stem widths at resolutions typical for screen display. The
+option does not noticeably affect print quality and causes large file
+size increases in PDF files.
+
+@item @code{svg-woff}
+@tab @code{#f}
+@tab This option is required when using Web Open Font Format (WOFF) font
+files with the backend @code{svg} command. A single SVG file is created
+for every page of output. Apart from LilyPond's own music glyphs, no
+other font information will be included. Any SVG viewer will therefore
+require the fonts be available to it for the proper rendering of both
+text and lyrics. It is also recommended not to use any font @q{aliases}
+or @q{lists} in case the SVG viewer cannot handle them.
+
+@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 @code{verbose}
+@tab @code{#f}
+@tab Verbose output, i.e. loglevel at DEBUG (read-only).
+
+@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
-
@cindex LANG
@cindex LILYPOND_DATADIR
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.
+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
A variable, as a percentage, that tunes memory management
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.
+Ubuntu GNU/Linux, and may require the use of @code{sudo} as appropriate.
@itemize
@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:
@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}
indicated line of your input file, try checking one or two lines
above the indicated position.
+Please note that diagnostics can be triggered at any point during the
+many stages of processing. For example if there are parts of the input
+that are processed multiple times (i.e. in midi and layout output), or
+if the same music variable is used in multiple contexts the same message
+may appear several times. Diagnostics produced at a @q{late} stage (i.e
+bar checks) might also be issued multiple times.
+
More information about errors is given in @ref{Common errors}.
@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::
* Warning staff affinities should only decrease::
+* Error message unexpected new::
+* Warning this voice needs a voiceXx or shiftXx setting::
@end menu
@node Music runs off the page
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
-\new Staff { a }
+@lilypond[quote,verbatim,fragment]
+\override Staff.NoteHead.color = #red
+\new Staff { a' }
@end lilypond
This is because a @code{Staff} context does not exist when the
another, separate, staff into which the notes are placed. The
correct code to color all note heads red is
-@lilypond[quote,verbatim,relative=2]
-\new Staff {
- \override Staff.NoteHead #'color = #red
- a
-}
-@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
-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' { c4 d e f }
-}
-@end lilypond
-
-Explicitly instantiating the @code{Voice} context fixes the
-problem:
-
-@lilypond[quote,verbatim]
-\new Voice {
- \repeat unfold 2 {
- \relative c' { c4 d e f }
- }
+\new Staff {
+ \override Staff.NoteHead.color = #red
+ a'
}
@end lilypond
-
-@node Apparent error in ../ly/init.ly
-@unnumberedsubsec Apparent error in @code{../ly/init.ly}
-
-Various obscure error messages may appear about syntax errors in
-@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.
-
-The most common error is a missing brace, (@code{@}}), at the end of
-a @code{score} block. Here the solution is obvious: check the
-@code{score} block is correctly terminated. The correct structure
-of an input file is described in @rlearning{How LilyPond input files work}.
-Using an editor which automatically highlights matching brackets and
-braces is helpful to avoid such errors.
-
-A second common cause is no white space between the last syllable
-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{Entering lyrics}.
-
-This error message can also appear if a terminating quote sign,
-(@code{"}), is omitted. In this case an accompanying error message
-@c keep "-matching straight in fancy editors
-should give a line number close to the line in error. The
-mismatched quote will usually be on the line one or two above.
-
@node Error message Unbound variable %
@unnumberedsubsec Error message Unbound variable %
@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
staff by inserting
@example
-\override VerticalAxisGroup #'staff-affinity = ##f
+\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}.
+
+
+@node Error message unexpected new
+@unnumberedsubsec Error message unexpected @code{@bs{}new}
+
+A @code{\score} block must contain a @emph{single} music expression.
+If instead it contains several @code{\new Staff},
+@code{\new StaffGroup} or similar contexts introduced with @code{\new}
+without them being enclosed in either curly brackets,
+@code{@{ @dots{} @}}, or double angle brackets, @code{<< @dots{} >>},
+like this:
+
+@example
+\score @{
+ % Invalid! Generates error: syntax error, unexpected \new
+ \new Staff @{ @dots{} @}
+ \new Staff @{ @dots{} @}
+@}
+@end example
+
+@noindent
+the error message will be produced.
+
+To avoid the error, enclose all the @code{\new} statements in
+curly or double angle brackets.
+
+Using curly brackets will introduce the @code{\new} statements
+sequentially:
+
+@lilypond[quote,verbatim]
+\score {
+ {
+ \new Staff { a' a' a' a' }
+ \new Staff { g' g' g' g' }
+ }
+}
+@end lilypond
+
+@noindent
+but more likely you should be using double angle brackets so the new
+staves are introduced in parallel, i.e. simultaneously:
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff { a' a' a' a' }
+ \new Staff { g' g' g' g' }
+ >>
+}
+@end lilypond
+
+@node Warning this voice needs a voiceXx or shiftXx setting
+@unnumberedsubsec Warning this voice needs a @code{@bs{}voiceXx} or @code{@bs{}shiftXx} setting
+
+If notes from two different voices with stems in the same direction
+occur at the same musical moment, but the voices have no
+voice-specific shifts specified, the warning message
+@samp{warning: this voice needs a \voiceXx or \shiftXx setting} will appear
+when compiling the LilyPond file. This warning will appear even when
+the notes have no visible stems, e.g. whole notes, if the stems for
+shorter notes at the same pitch would be in the same direction.
+
+Remember that the stem direction depends on the position of the
+note on the staff unless the stem direction is specified, for example
+by using @code{\voiceOne}, etc. In this case the warning will appear
+only when the stems happen to be in the same direction, i.e. when the
+notes are in the same half of the staff.
+
+By placing the notes in voices with stem directions and shifts
+specified, for example by using @code{\voiceOne}, etc., these warnings
+may be avoided.
+
+Notes in higher numbered voices, @code{\voiceThree} etc., are
+automatically shifted to avoid clashing note columns. This causes a
+visible shift for notes with stems, but whole notes are not visibly
+shifted unless an actual clash of the note heads occurs, or when the
+voices cross over from their natural order (when @code{\voiceThree}
+is higher than @code{\voiceOne}, etc.)
+
+@seealso
+@rlearning{Explicitly instantiating voices},
+@rlearning{Real music example},
+@ruser{Single-staff polyphony},
+@ruser{Collision resolution}.
projects / lilypond.git / blobdiff