Add dynamic script fffff; update docs.

[lilypond.git] / Documentation / user / working.itely

diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
index 3a55de215698ec447fb86f7840d815c473cb7e97..34e82c3bee658221cc17bb1fa4d94e44f47ea66f 100644 (file)
--- a/Documentation/user/working.itely
+++ b/Documentation/user/working.itely
@@ -128,9 +128,9 @@ piece of existing sheet music),
 
 @itemize
 
-@item Enter one manuscript (the physical copy) system at a time (but still
-only one bar per line of text), and
-check each system when you finish it.  You may use the
+@item Enter the manuscript (the physical copy of the music) into
+LilyPond one system at a time (but still only one bar per line of text),
+and check each system when you finish it.  You may use the
 @code{showLastLength} or @code{showFirstLength} properties to speed up
 processing -- see @ruser{Skipping corrected music}.
 
@@ -576,6 +576,7 @@ file with @code{\include "../global.ily"}, which contains
 
 @menu
 * Updating old input files::
+* Common errors::
 * Troubleshooting (taking it all apart)::
 * Minimal examples::
 @end menu
@@ -583,6 +584,9 @@ file with @code{\include "../global.ily"}, which contains
 @node Updating old input files
 @subsection Updating old input files
 
+@cindex convert-ly
+@cindex updating old input files
+
 The LilyPond input syntax occasionally changes.  As LilyPond itself
 improves, the syntax (input language) is modified accordingly.  Sometimes
 these changes are made to make the input easier to read and write or
@@ -607,6 +611,76 @@ UTF-8 character.  @code{convert-ly} cannot change all the LaTeX
 special characters into UTF-8 characters; you must manually update
 your old LilyPond input files.
 
+@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::
+* Apparent error in ../ly/init.ly::
+* Error message Unbound variable %::
+@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 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 @ref{How LilyPond input files work}.
+Using an editor which automatically highlights matching brackets and
+braces is helpful to avoid such errors.
+
+This error message can also appear if a terminating quote sign,
+(@code{"}), is omitted.  In this case an accompanying error message
+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 Troubleshooting (taking it all apart)
 @subsection Troubleshooting (taking it all apart)