This chapter details the technicalities of running LilyPond.
@menu
-* Normal usage::
-* Command-line usage::
-* Error messages::
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Common errors::
* Point and click::
* Text editor support::
@end menu
if you are unfamiliar with the command-line.
@menu
-* Invoking lilypond::
-* Command line options for lilypond::
-* Environment variables::
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::
@end menu
@node Invoking lilypond
More information about errors is given in @ref{Common errors}.
+@node Common errors
+@section Common errors
+
+The error conditions described below occur often, yet the cause
+is not obvious or easily found. Once seen and understood, they
+are easily handled.
+
+
+@menu
+* Music runs off the page::
+* An extra staff appears::
+* Apparent error in ../ly/init.ly::
+* Error message Unbound variable %::
+* Error message FT_Get_Glyph_Name::
+@end menu
+
+@node Music runs off the page
+@unnumberedsubsec Music runs off the page
+
+Music running off the page over the right margin or appearing
+unduly compressed is almost always due to entering an incorrect
+duration on a note, causing the final note in a measure to extend
+over the bar line. It is not invalid if the final note in a
+measure does not end on the automatically entered bar line, as the
+note is simply assumed to carry over into the next measure. But
+if a long sequence of such carry-over measures occurs the music
+can appear compressed or may flow off the page because automatic
+line breaks can be inserted only at the end of complete measures,
+i.e., where all notes end before or at the end of the measure.
+
+@warning{An incorrect duration can cause line breaks to be
+inhibited, leading to a line of highly compressed music or
+music which flows off the page.}
+
+The incorrect duration can be found easily if bar checks are used,
+see @ruser{Bar and bar number checks}.
+
+If you actually intend to have a series of such carry-over measures
+you will need to insert an invisible bar line where you want the
+line to break. For details, see @ruser{Bar lines}.
+
+
+@node An extra staff appears
+@unnumberedsubsec An extra staff appears
+
+If contexts are not created explicitly with @code{\new} they will be
+silently created as soon as a command is encountered which cannot
+be applied to an existing context. In simple scores the automatic
+creation of contexts is useful, and most of the examples in the
+LilyPond manuals take advantage of this simplification. But
+occasionally the silent creation of contexts can give rise to
+unexpected new staves or scores. For example, it might be expected
+that the following code would cause all note heads within the
+following staff to be colored red, but in fact it results in two
+staves with the note heads remaining the default black in the lower
+staff.
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.NoteHead #'color = #red
+\new Staff { a }
+@end lilypond
+
+This is because a @code{Staff} context does not exist when the
+override is processed, so one is implicitly created and the override
+is applied to it, but then the @code{\new Staff} command creates
+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 d e f }
+@end lilypond
+
+The correct way is to reverse the @code{\repeat} and
+@code{\relative} commands, like this:
+
+@lilypond[quote,verbatim]
+\relative {
+ \repeat unfold 2 { c 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
+@code{../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{Lyrics explained}.
+
+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 %
+
+This error message will appear at the bottom of the console
+output or log file together with a @qq{GUILE signalled an error ...}
+message every time a Scheme routine is called which (invalidly)
+contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
+
+LilyPond comments begin with a percent sign, (@code{%}), and must
+not be used within Scheme routines. Scheme comments begin with a
+semi-colon, (@code{;}).
+
+@node Error message FT_Get_Glyph_Name
+@unnumberedsubsec Error message FT_Get_Glyph_Name
+
+This error messages appears in the console output or log file if
+an input file contains a non-ASCII character and was not saved in
+UTF-8 encoding. For details, see @ruser{Text encoding}.
+
+
@node Point and click
@section Point and click
@section When things don't work
@menu
-* Common errors::
* Troubleshooting (taking it all apart)::
@end menu
-@node Common errors
-@subsection Common errors
-
-The error conditions described below occur often, yet the cause
-is not obvious or easily found. Once seen and understood, they
-are easily handled.
-
-
-@menu
-* Music runs off the page::
-* An extra staff appears::
-* Apparent error in ../ly/init.ly::
-* Error message Unbound variable %::
-* Error message FT_Get_Glyph_Name::
-@end menu
-
-@node Music runs off the page
-@unnumberedsubsubsec Music runs off the page
-
-Music running off the page over the right margin or appearing
-unduly compressed is almost always due to entering an incorrect
-duration on a note, causing the final note in a measure to extend
-over the bar line. It is not invalid if the final note in a
-measure does not end on the automatically entered bar line, as the
-note is simply assumed to carry over into the next measure. But
-if a long sequence of such carry-over measures occurs the music
-can appear compressed or may flow off the page because automatic
-line breaks can be inserted only at the end of complete measures,
-i.e., where all notes end before or at the end of the measure.
-
-@warning{An incorrect duration can cause line breaks to be
-inhibited, leading to a line of highly compressed music or
-music which flows off the page.}
-
-The incorrect duration can be found easily if bar checks are used,
-see @ruser{Bar and bar number checks}.
-
-If you actually intend to have a series of such carry-over measures
-you will need to insert an invisible bar line where you want the
-line to break. For details, see @ruser{Bar lines}.
-
-
-@node An extra staff appears
-@unnumberedsubsubsec An extra staff appears
-
-If contexts are not created explicitly with @code{\new} they will be
-silently created as soon as a command is encountered which cannot
-be applied to an existing context. In simple scores the automatic
-creation of contexts is useful, and most of the examples in the
-LilyPond manuals take advantage of this simplification. But
-occasionally the silent creation of contexts can give rise to
-unexpected new staves or scores. For example, it might be expected
-that the following code would cause all note heads within the
-following staff to be colored red, but in fact it results in two
-staves with the note heads remaining the default black in the lower
-staff.
-
-@lilypond[quote,verbatim,relative=2]
-\override Staff.NoteHead #'color = #red
-\new Staff { a }
-@end lilypond
-
-This is because a @code{Staff} context does not exist when the
-override is processed, so one is implicitly created and the override
-is applied to it, but then the @code{\new Staff} command creates
-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 d e f }
-@end lilypond
-
-The correct way is to reverse the @code{\repeat} and
-@code{\relative} commands, like this:
-
-@lilypond[quote,verbatim]
-\relative {
- \repeat unfold 2 { c d e f }
-}
-@end lilypond
-
-
-@node Apparent error in ../ly/init.ly
-@unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
-
-Various obscure error messages may appear about syntax errors in
-@code{../ly/init.ly} if the input file is not correctly formed,
-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{Lyrics explained}.
-
-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 %
-@unnumberedsubsubsec Error message Unbound variable %
-
-This error message will appear at the bottom of the console
-output or log file together with a @qq{GUILE signalled an error ...}
-message every time a Scheme routine is called which (invalidly)
-contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
-
-LilyPond comments begin with a percent sign, (@code{%}), and must
-not be used within Scheme routines. Scheme comments begin with a
-semi-colon, (@code{;}).
-
-@node Error message FT_Get_Glyph_Name
-@unnumberedsubsubsec Error message FT_Get_Glyph_Name
-
-This error messages appears in the console output or log file if
-an input file contains a non-ASCII character and was not saved in
-UTF-8 encoding. For details, see @ruser{Text encoding}.
-
@node Troubleshooting (taking it all apart)
@subsection Troubleshooting (taking it all apart)
projects / lilypond.git / commitdiff