@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 @code{\version} information. 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}: @ruser{Bar check}, @ruser{Octave check}, and
+@ruser{Barnumber check}. If you
include checks every so often, then if you make a mistake, you can pinpoint
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
imbalance
in the number of @code{@{} and @code{@}}.
-@item @strong{Explicity add durations} at the beginnings of sections
+@item @strong{Explicitly add durations} at the beginnings of sections
and identifiers. If you specify @code{c4 d e} at the beginning of a
phrase (instead of just @code{c d e}) you can save yourself some
problems if you rearrange your music later.
@item @strong{Separate tweaks} from music definitions. See
-@ref{Saving typing with identifiers and functions} and
-@ref{Style sheets}.
+@ruser{Saving typing with identifiers and functions}, and
+@ruser{Style sheets}.
@end itemize
only one bar per line of text), and
check each system when you finish it. You may use the
@code{showLastLength} command to speed up processing -- see
-@ref{Skipping corrected music}.
+@ruser{Skipping corrected music}.
@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
in the input file whenever the manuscript has a line break. This
@end example
@item @strong{Separate tweaks from music definitions}. This
-point was made in @ref{General suggestions}, but for large
+point was made in @ruser{General suggestions}, but for large
projects it is absolutely vital. We might need to change
the definition of @code{fthenp}, but then we only need
to do this once, and we can still avoid touching anything
@end lilypond
Using identifiers is also a good way to reduce work if the
-LilyPond input syntax changes (see @ref{Updating old files}). If
+LilyPond input syntax changes (see @ruser{Updating old files}). If
you have a single definition (such as @code{\dolce}) for all your
-files (see @ref{Style sheets}), then if the syntax changes, you
+files (see @ruser{Style sheets}), then if the syntax changes, you
only need to update your single @code{\dolce} definition,
instead of making changes throughout every @code{.ly} file.
@section Style sheets
The output that LilyPond produces can be heavily modified; see
-@ref{Tweaking output} for details. But what if you have many
+@ruser{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
-@ref{Advanced tweaks with Scheme}.
+the parts with all the @code{#()}. This is explained in
+@ruser{Advanced tweaks with Scheme}.
@lilypond[quote,verbatim,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
@end lilypond
There are some problems with overlapping output; we'll fix those using
-the techniques in @ref{Moving objects}. But let's also
+the techniques in @ruser{Moving objects}. But let's also
do something about the @code{mpdolce} and @code{tempoMark}
definitions. They produce the output we desire, but we might want
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
@example
%%% global.ly
-\version "2.9.13"
+\version "2.11.23"
#(ly:set-option 'point-and-click #f)
\include "../init/init-defs.ly"
\include "../init/init-layout.ly"
LilyPond comes with a file that makes this updating easier:
@code{convert-ly}. For details about how to run this program, see
-@ref{Updating files with convert-ly}.
+@rprogram{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
-are listed in @ref{Updating files with convert-ly}.
+are listed in @rprogram{Updating files with convert-ly}.
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- for example,
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
+@ruser{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