@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.
* Style sheets::
* Updating old files::
* Troubleshooting (taking it all apart)::
+* Minimal examples::
@end menu
@itemize @bullet
@item @strong{Include @code{\version} numbers in every file}. Note that all
-templates contain a @code{\version "2.9.13"} string. We
+templates contain a @code{\version "2.11.15"} string. We
highly recommend that you always include the @code{\version}, no matter
how small your file is. Speaking from personal experience, it's
quite frustrating to try to remember which version of LilyPond you were
using a few years ago. @code{convert-ly} requires you to declare
which version of LilyPond you used.
-@item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}. If
-you
+@item @strong{Include checks}: @ref{Bar check}, @ref{Octave check}, and
+@ref{Barnumber check}. If you
include checks every so often, then if you make a mistake, you can pinpoint
-it quicker. How often is ``every so often''? It depends on the complexity
+it quicker. How often is @q{every so often}? It depends on the complexity
of the music. For very simple music, perhaps just once or twice. For
very complex music, perhaps every bar.
either in the music
itself or in the output you desire, it's often good to write only one bar
per line. Saving screen space by cramming eight bars per line just isn't
-worth it if you have to `debug' your files.
+worth it if you have to @q{debug} your files.
@item @strong{Comment your files}. Use either bar numbers (every so often)
or
-references to musical themes (``second theme in violins,'' ``fourth
-variation'', etc). You may not need comments when you're writing the piece
+references to musical themes (@q{second theme in violins,} @q{fourth
+variation,} etc.). You may not need comments when you're writing the piece
for the first time, but if you want to go back to change something two or
three years later, or if you pass the source over to a friend, it will
be much more
problems if you rearrange your music later.
@item @strong{Separate tweaks} from music definitions. See
-@ref{Saving typing with identifiers and functions} and
+@ref{Saving typing with identifiers and functions}, and
@ref{Style sheets}.
@end itemize
@section Style sheets
The output that LilyPond produces can be heavily modified; see
-@ref{Tweaking output} for details. But what if you have many
+@ref{Tweaking output}, for details. But what if you have many
files that you want to apply your tweaks to? Or what if you
simply want to separate your tweaks from the actual music? This
is quite easy to do.
Let's look at an example. Don't worry if you don't understand
-the parts with all the #(). This is explained in
+the parts with all the @code{#()}. This is explained in
@ref{Advanced tweaks with Scheme}.
@lilypond[quote,verbatim,ragged-right]
to use them in another piece. We could simply copy-and-paste them
at the top of every file, but that's an annoyance. It also leaves
those definitions in our music files, and I personally find all
-the #() somewhat ugly. Let's hide them in another file:
+the @code{#()} somewhat ugly. Let's hide them in another file:
@example
%%% save this to a file called "definitions.ly"
That looks better, but let's make a few changes. The glissando is hard
to see, so let's make it thicker and closer to the noteheads. Let's
put the metronome marking above the clef, instead of over the first
-note. And finally, my composition professor hates "C" time signatures,
-so we'd better make that "4/4" instead.
+note. And finally, my composition professor hates @q{C} time signatures,
+so we'd better make that @q{4/4} instead.
Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
with this:
@end lilypond
That looks nicer! But now suppose that I want to publish this
-piece. My composition professor doesn't like "C" time
+piece. My composition professor doesn't like @q{C} time
signatures, but I'm somewhat fond of them. Let's copy the
current @file{definitions.ly} to @file{web-publish.ly} and
modify that. Since this music is aimed at producing a pdf which
This approach can be useful even if you are only producing
one set of parts. I use half a dozen different
-``style sheet'' files for my projects. I begin every music
+@q{style sheet} files for my projects. I begin every music
file with @code{\include "../global.ly"}, which contains
@example
%%% global.ly
-\version "2.9.13"
+\version "2.11.15"
#(ly:set-option 'point-and-click #f)
\include "../init/init-defs.ly"
\include "../init/init-layout.ly"
@code{convert-ly}. For details about how to run this program, see
@ref{Updating files with convert-ly}.
-Unforunately, @code{convert-ly} cannot handle all input changes. It
+Unfortunately, @code{convert-ly} cannot handle all input changes. It
takes care of simple search-and-replace changes (such as @code{raggedright}
becoming @code{ragged-right}), but some changes are too
complicated. The syntax changes that @code{convert-ly} cannot handle
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- for example,
-"@code{No\"el}" (this would print the French word for
-`Christmas'). In LilyPond 2.6 and above, the special
-"@code{ë}" must be entered directly into the LilyPond file as an
+@samp{No\"el} (this would print the French word for
+@q{Christmas}). In LilyPond 2.6 and above, the special
+@samp{ë} must be entered directly into the LilyPond file as an
UTF-8 character. @code{convert-ly} cannot change all the LaTeX
special characters into UTF-8 characters; you must manually update
your old LilyPond files.
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@/.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 uncomment 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 @code{\override} commands unless that is the point of the
+example.
+@end itemize
+
projects / lilypond.git / blobdiff