@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-learning.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
@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.
@menu
* Suggestions for writing LilyPond files::
-* Saving typing with identifiers and functions::
-* Style sheets::
-* Updating old files::
-* Troubleshooting (taking it all apart)::
+* When things don't work::
+* Scores and parts::
@end menu
that you want, it doesn't matter what your files look like. However,
there are a few other things to consider when writing lilypond files.
-@itemize @bullet
+@itemize
@item What if you make a mistake? The structure of a lilypond
file can make certain errors easier (or harder) to find.
occasionally as lilypond improves. Most changes can be
done automatically with @code{convert-ly}, but some changes
might require manual assistance. Lilypond files can be
-structured in order to be easier (or header) to update.
+structured in order to be easier (or harder) to update.
@end itemize
@menu
* General suggestions::
* Typesetting existing music::
* Large projects::
+* Saving typing with variables and functions::
+* Style sheets::
@end menu
Here are a few suggestions that can help you to avoid or fix
problems:
-@itemize @bullet
+@itemize
@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
+using a few years ago. @command{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
-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
-very complex music, perhaps every bar.
+@item @strong{Include checks}: @ruser{Bar and barnumber checks},
+@ruser{Octave 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 very
+complex music, perhaps every bar.
@item @strong{One bar per line of text}. If there is anything complicated,
either in the music
imbalance
in the number of @code{@{} and @code{@}}.
-@item @strong{Explicity add durations} at the beginnings of sections
-and identifiers. If you specify @code{c4 d e} at the beginning of a
+@item @strong{Explicitly add durations} at the beginnings of sections
+and variables. 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{Saving typing with variables and functions}, and
@ref{Style sheets}.
@end itemize
If you are entering music from an existing score (i.e., typesetting a
piece of existing sheet music),
-@itemize @bullet
+@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
@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
When working on a large project, having a clear structure to your
lilypond files becomes vital.
-@itemize @bullet
+@itemize
-@item @strong{Use an identifier for each voice}, with a minimum of
+@item @strong{Use an variable for each voice}, with a minimum of
structure inside the definition. The structure of the
@code{\score} section is the most likely thing to change;
the @code{violin} definition is extremely unlikely to change
@end example
@item @strong{Separate tweaks from music definitions}. This
-point was made in @ref{General suggestions}, but for large
+point was made in previously, 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 itemize
-@node Saving typing with identifiers and functions
-@section Saving typing with identifiers and functions
+@node Saving typing with variables and functions
+@subsection Saving typing with variables and functions
@cindex variables
-@cindex identifiers
+@cindex variables
By this point, you've seen this kind of thing:
}
@end lilypond
-However, you can also use these identifiers (also known as
+However, you can also use these variables (also known as
variables, macros, or (user-defined) command) for tweaks:
@lilypond[quote,verbatim,ragged-right]
}
@end lilypond
-These identifiers are obviously useful for saving
+These variables are obviously useful for saving
typing. But they're worth considering even if you
only use them once -- they reduce complexity. Let's
look at the previous example without any
-identifiers. It's a lot harder to read, especially
+variables. It's a lot harder to read, especially
the last line.
@example
}
@end lilypond
-Using identifiers is also a good way to reduce work if the
+Using variables is also a good way to reduce work if the
LilyPond input syntax changes (see @ref{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
@node Style sheets
-@section Style sheets
+@subsection 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"
@end lilypond
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
+to see, so let's make it thicker and closer to the note heads. 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 @w{"@version{}"}
#(ly:set-option 'point-and-click #f)
\include "../init/init-defs.ly"
\include "../init/init-layout.ly"
@end example
+@node When things don't work
+@section When things don't work
+
+@menu
+* Updating old files::
+* Troubleshooting (taking it all apart)::
+* Minimal examples::
+@end menu
+
@node Updating old files
-@section Updating old files
+@subsection Updating old files
The LilyPond input syntax occasionally changes. As LilyPond itself
improves, the syntax (input language) is modified accordingly. Sometimes
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,
-@samp{No\"el} (this would print the French word for
+@code{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
+@code{ë} 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.
@node Troubleshooting (taking it all apart)
-@section Troubleshooting (taking it all apart)
+@subsection Troubleshooting (taking it all apart)
Sooner or later, you will write a file that LilyPond cannot
compile. The messages that LilyPond gives may help
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
+@subsection 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
+
+
+
+@node Scores and parts
+@section Scores and parts
+
+TODO: this is really old stuff from the really old tutorial.
+Rewrite, fix, etc. Or maybe delete entirely. -gp
+Include section on tags -td
+and then move to section 5. Working ... -td
+
+In orchestral music, all notes are printed twice. Once in a part for
+the musicians, and once in a full score for the conductor. Variables can
+be used to avoid double work. The music is entered once, and stored in
+a variable. The contents of that variable is then used to generate
+both the part and the full score.
+
+It is convenient to define the notes in a special file. For example,
+suppose that the file @file{horn-music.ly} contains the following part
+of a horn/@/bassoon duo
+
+@example
+hornNotes = \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
+@end example
+
+@noindent
+Then, an individual part is made by putting the following in a file
+
+@example
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
+
+@{
+ \transpose f c' \hornNotes
+@}
+@end example
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards. The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
+@code{f} is denoted by notated @code{c'}, which corresponds with the
+tuning of a normal French Horn in@tie{}F. The transposition can be seen
+in the following output
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+In ensemble pieces, one of the voices often does not play for many
+measures. This is denoted by a special rest, the multi-measure
+rest. It is entered with a capital @code{R} followed by a duration
+(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
+etc.). By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3@tie{}measures in 2/4 time
+
+@example
+R2*3
+@end example
+
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
+
+@example
+\set Score.skipBars = ##t
+@end example
+
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}). Prepending the rest and
+this option to the music above, leads to the following result
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+
+The score is made by combining all of the music together. Assuming
+that the other voice is in @code{bassoonNotes} in the file
+@file{bassoon-music.ly}, a score is made with
+
+@example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+<<
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+>>
+@end example
+
+@noindent
+leading to
+
+@lilypond[quote,ragged-right]
+\relative c <<
+ \new Staff {
+ \time 2/4 R2*3
+ r4 f8 a cis4 f e d
+ }
+ \new Staff {
+ \clef bass
+ r4 d,8 f | gis4 c | b bes |
+ a8 e f4 | g d | gis f
+ }
+>>
+@end lilypond
+