Merge with master

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

diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
index 97edb206c335eeee8dae48d4659090583a15e535..abef49234d2961dd6ebec0f36f340f3aed86e9a9 100644 (file)
--- a/Documentation/user/working.itely
+++ b/Documentation/user/working.itely
@@ -10,7 +10,7 @@
 @node Working on LilyPond projects
 @chapter Working on LilyPond projects
 
-This section explains a how to solve or avoid certain common
+This section explains how to solve or avoid certain common
 problems.  If you have programming experience, many of these
 tips may seem obvious, but it is still advisable to read
 this chapter.
@@ -22,6 +22,7 @@ this chapter.
 * Style sheets::                
 * Updating old files::          
 * Troubleshooting (taking it all apart)::  
+* Minimal examples::            
 @end menu
 
 
@@ -624,4 +625,46 @@ bass = \relative c' @{
 Now start slowly uncommenting more and more of the
 @code{bass} part until you find the problem line.
 
+Another very useful debugging technique is constructing
+@ref{Minimal examples}.
+
+
+@node Minimal examples
+@section Minimal examples
+
+A minimal example is an example which is as small as possible.  These
+examples are much easier to understand than long examples.  Minimal
+examples are used for
+
+@itemize
+@item Bug reports
+@item Sending a help request to mailists
+@item Adding an example to the @uref{http://lsr@/.dsi@/.unimi/2.it/,LilyPond
+Snippet Repository}
+@end itemize
+
+To construct an example which is as small as possible, the rule is
+quite simple: remove anything which is not necessary.  When trying to
+remove unnecessary parts of a file, it is a very good idea to comment
+out lines instead of deleting them.  That way, if you discover that you
+actually @emph{do} need some lines, you can un-comment them, instead of
+typing them in from scratch.
+
+There are two exceptions to the @qq{as small as possible} rule:
+
+@itemize
+@item Include the @code{\version} number.
+@item If possible, use @code{\paper@{ ragged-right=##t @}} at the
+top of your example.
+@end itemize
+
+The whole point of a minimal example is to make it easy to read:
+
+@itemize
+@item Avoid using complicated notes, keys, or time signatures, unless you
+wish to demonstrate something is about the behavior of those items.
+@item Do not use \override commands unless that is the point of the
+example.
+@end itemize
+