From: Graham Percival <graham@percival-music.ca>
Date: Wed, 24 Jan 2007 08:22:14 +0000 (-0800)
Subject: Add tips for creating minimal examples.
X-Git-Tag: release/2.10.17-1^2~36
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=297b6362621ae501ce5497e91704bdc6f381c702;p=lilypond.git

Add tips for creating minimal examples.
---

diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely
index c57510c228..d728b97ce2 100644
--- a/Documentation/user/running.itely
+++ b/Documentation/user/running.itely
@@ -577,6 +577,9 @@ bug by following the directions on
 
 @uref{http://lilypond.org/web/devel/participating/bugs}
 
+Please construct submit @ref{Minimal examples} of bug reports.  We do not
+have the resources to investigate reports which are not as small as possible.
+
 
 @node Error messages
 @section Error messages
diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
index 31ea194e2c..e75b32e346 100644
--- a/Documentation/user/working.itely
+++ b/Documentation/user/working.itely
@@ -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 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
+