From: Graham Percival Date: Fri, 25 Sep 2009 20:54:17 +0000 (+0100) Subject: Doc: move Common errors into running. X-Git-Tag: release/2.13.5-0~45 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=37863e78b0a241f6c2ebb071322faae2c6ce2f20;p=lilypond.git Doc: move Common errors into running. --- diff --git a/Documentation/application/running.itely b/Documentation/application/running.itely index e5a5874634..c123b8bc95 100644 --- a/Documentation/application/running.itely +++ b/Documentation/application/running.itely @@ -16,9 +16,10 @@ 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 @@ -50,9 +51,9 @@ scope of this manual; please consult other documentation on this topic 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 @@ -489,6 +490,149 @@ above the indicated position. 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 diff --git a/Documentation/application/suggestions.itely b/Documentation/application/suggestions.itely index bd58b7c687..a32768ac00 100644 --- a/Documentation/application/suggestions.itely +++ b/Documentation/application/suggestions.itely @@ -198,152 +198,9 @@ g4\fthenp c'8. e16 @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)