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::
+* 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
+@unnumberedsubsubsec Using LilyPond with standard shell features
-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:
+Since LilyPond is a command line application, features of the @q{shell}
+used for calling LilyPond can also be put to good use.
-@itemize
+For example:
-@item
-@code{lilypond file.ly 1>stdout.log} to redirect normal output
+@example
+lilypond *.ly
+@end example
-@item
-@code{lilypond file.ly 2>stderr.log} to redirect error messages
+@noindent
+will process all LilyPond files in the current directory.
-@item
-@code{lilypond file.ly &>all.log} to redirect all output
+Redirecting the console output (e.g. to a file) may also be useful:
-@end itemize
+@example
+lilypond file.ly 1> stdout.txt
+
+lilypond file.ly 2> stderr.txt
+
+lilypond file.ly &> all.txt
+@end example
+
+@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.
+
+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
+find . -name '*.ly' -exec lilypond '@{@}' \;
+@end example
+
+@noindent
+This should also work for MacOS@tie{}X users.
+
+A Windows user would run;
+
+@example
+forfiles /s /M *.ly /c "cmd /c lilypond @@file"
+@end example
+
+@noindent
+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}.
-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.
+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;
+
+@example
+forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @@file"
+@end example
+
+If there are spaces in the path to the top-level folder, then the whole
+path needs to be inside double quotes;
+
+@example
+forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @@file"
+@end example
@node Basic command line options for LilyPond
@table @code
-@item -d,--define-default=@var{var}=@var{val}
+@item -b, --bigpdfs
+@cindex bigpdfs
+
+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.
+
+@example
+lilypond -b myfile
+@end example
+
+Then run @code{ghostscript};
+
+@example
+gs -q -sDEVICE=pdfwrite -o gsout.pdf myfile.pdf
+@end example
+
+@code{pdfsizeopt.py} can then be used to further optimize the size
+of file;
+
+@example
+pdfsizeopt.py --use-multivalent=no gsout.pdf final.pdf
+@end example
+
+
+@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
+@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
@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}!)
@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}. 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 -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
@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.
+@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}, @code{.count} files in the
-@code{EPS} backend.
+@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 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.
+@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 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}.
+@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; has the same effect as
+@tab @code{null}
+@tab Do not output a printed score. This 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.
+@tab @code{scm}
+@tab This dumps out the raw, internal Scheme-based drawing commands.
@item
-@tab @code{'scm}
-@tab Dump of the raw, internal Scheme-based drawing commands.
+@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}
@item @code{clip-systems}
@tab @code{#f}
-@tab Generate cut-out snippets of a score.
+@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 @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.
@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.
@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
@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}.
+@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}
@quotation
@verbatim
-#(system "rm -rf /")
+#(s ystem "rm -rf /") % too dangerous to write correctly
{
- c4^$(ly:gulp-file "/etc/passwd")
+ c4^$(ly:gulp-file "/etc/passwd") % malicious but not destructive
}
@end verbatim
@end quotation
@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}, ...
+data to files @code{FILE1.log}, @code{FILE2.log}@dots{}
@item @code{show-available-fonts}
@tab @code{#f}
@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.
+@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}
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 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