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:
-
-@itemize
-
-@item
-@code{lilypond file.ly 1>stdout.log} to redirect normal output
+@unnumberedsubsubsec Using LilyPond with standard shell features
-@item
-@code{lilypond file.ly 2>stderr.log} to redirect error messages
+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 &>all.log} to redirect all output
+For example:
-@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
+This should also work for MacOS@tie{}X users.
-The following options are supported:
+A Windows user would run;
-@cindex help, command line
-
-@table @code
-
-@item help
-Running @code{lilypond -dhelp} will print all of the @option{-d} options
-available.
-
-@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.
+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}.
-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
-
-@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
-
-Example: @code{lilypond -dbackend=svg @var{filename}.ly}
-
-@item preview
-
-@cindex preview, command line
-
-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.
-
-@item gui
-Runs silently and redirect all output to a log 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.
-
-@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 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
+@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
@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
+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.
-
+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}.
+
+@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, e.g.
+
+@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 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 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/}.
+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 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{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
+
+@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 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 @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
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 ignoring too many clashing note columns::
@end menu
@node Music runs off the page
heads remaining the default black in the lower staff.
@lilypond[quote,verbatim,relative=2]
-\override Staff.NoteHead #'color = #red
+\override Staff.NoteHead.color = #red
\new Staff { a }
@end lilypond
@lilypond[quote,verbatim,relative=2]
\new Staff {
- \override Staff.NoteHead #'color = #red
+ \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 }
- }
-}
-@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 ignoring too many clashing note columns
+@unnumberedsubsec Warning ignoring too many clashing note columns
+
+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: ignoring too many clashing note columns} 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