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
-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.
+@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.
@node Basic command line options for LilyPond
@table @code
-@item -d,--define-default=@var{var}=@var{val}
+@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
@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
+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
@code{EPS} backend.
@item @code{backend}
-@tab @code{'ps}
+@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 @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 @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,
+@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/}. 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.
+@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 @code{scm}
@tab Dump of the raw, internal Scheme-based drawing commands.
@item @code{check-internal-types}
@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.
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::
@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 %
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
projects / lilypond.git / blobdiff