1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Putting it all together
3 @chapter Putting it all together
5 This section explains how to use the rest of the documentation and
6 how to solve common problems.
9 * Suggestions for writing LilyPond files::
10 * Extending the templates::
11 * Fixing overlapping notation::
12 * How LilyPond files work::
13 * Troubleshooting (taking it all apart)::
17 @node Suggestions for writing LilyPond files
18 @section Suggestions for writing LilyPond files
20 Now you're ready to begin writing larger LilyPond files -- not just the
21 little examples in the tutorial, but whole pieces. But how should you
24 The best answer is ``however you want to do it.'' As long as LilyPond
25 can understand your files and produces the output that you want, it
26 doesn't matter what your files look like. That said, sometimes we
27 make mistakes when writing files. If LilyPond can't understand your
28 files, or produces output that you don't like, how do you fix the
31 Here are a few suggestions that can help you to avoid or fix
35 @item Include @code{\version} numbers in every file. Note that all
36 templates contain a @code{\version "2.6.0"} string. We
37 highly recommend that you always include the @code{\version}, no matter
38 how small your file is. Speaking from personal experience, it's
39 quite frustrating to try to remember which version of LilyPond you were
40 using a few years ago. @code{convert-ly} requires you to declare
41 which version of LilyPond you used.
43 @item Include checks: See @ref{Bar check} and @ref{Octave check}. If you
44 include checks every so often, then if you make a mistake, you can pinpoint
45 it quicker. How often is ``every so often''? It depends on the complexity
46 of the music. For very simple music, perhaps just once or twice. For
47 very complex music, every bar.
49 @item One bar per line. If there is anything complicated, either in the music
50 itself or in the output you desire, it's often good to write only one bar
51 per line. Saving screen space by cramming eight bars per line just isn't
52 worth it if you have to `debug' your files.
54 @item Comment your files, with either bar numbers (every so often) or
55 references to musical themes (``second theme in violins'', ``fourth
56 variation''). You may not need it when you're writing the piece for
57 the first time, but if you want to go back and change something two
58 or three years later, you won't know how your file is structured if you
59 didn't comment the file.
61 @item Ident your braces. A lot of problems are caused by an imbalance
62 in the number of @code{@{} and @code{@}}.
67 @node Extending the templates
68 @section Extending the templates
70 You've read the tutorial, you know how to write music. But how can you
71 get the staves that you want? The templates are ok, but what if you
72 want something that isn't covered?
74 Start off with the template that seems closest to what you want to end
75 up with. Let's say that you want to write something for soprano and
76 cello. In this case, we would start with ``Notes and lyrics'' (for the
81 melody = \relative c' @{
95 \context Voice = one @{
99 \lyricsto "one" \new Lyrics \text
102 \midi @{ \tempo 4=60 @}
106 Now we want to add a cello part. Let's look at the ``Notes only'' example:
110 melody = \relative c' @{
121 \midi @{ \tempo 4=60 @}
125 We don't need two @code{\version} commands. We'll need the @code{melody}
126 section. We don't want two @code{\score} sections -- if we had two
127 @code{\score}s, we'd get the two parts separately. We want them together,
128 as a duet. Within the @code{\score} section, we don't need two
129 @code{\layout} or @code{\midi}.
131 If we simply cut and paste the @code{melody} section, we would end up with
132 two @code{melody} sections. So let's rename them. We'll call the one
133 for the soprano @code{sopranoMusic}, and the one for the cello can be
134 called @code{celloMusic}. While we're doing this, let's rename @code{text}
135 to be @code{sopranoLyrics}. Remember to rename both instances of all
136 these names -- both the initial definition (the
137 @code{melody = relative c' @{ } part) and the name's use (in the
138 @code{\score} section).
140 While we're doing this, let's change the cello part's staff -- celli
141 normally use bass clef. We'll also give the cello some different
146 sopranoMusic = \relative c' @{
154 sopranoLyrics = \lyricmode @{
158 celloMusic = \relative c @{
168 \context Voice = one @{
172 \lyricsto "one" \new Lyrics \sopranoLyrics
175 \midi @{ \tempo 4=60 @}
179 This is looking promising, but the cello part won't appear in the
180 score -- we haven't used it in the @code{\score} section. If we
181 want the cello part to appear under the soprano part, we need to add
184 \new Staff \celloMusic
188 underneath the soprano stuff. We also need to add @code{<<} and
189 @code{>>} around the music -- that tells LilyPond that there's
190 more than one thing (in this case staff) happening at once. The
191 @code{\score} looks like this now
197 \context Voice = one @{
201 \lyricsto "one" \new Lyrics \sopranoLyrics
203 \new Staff \celloMusic
206 \midi @{ \tempo 4=60 @}
211 This looks a bit messy; the indentation is messed up now. That is
212 easily fixed. Here's the complete soprano and cello template.
214 @lilypond[quote,verbatim,raggedright]
216 sopranoMusic = \relative c' {
224 sopranoLyrics = \lyricmode {
228 celloMusic = \relative c {
239 \context Voice = one {
243 \lyricsto "one" \new Lyrics \sopranoLyrics
245 \new Staff \celloMusic
248 \midi { \tempo 4=60 }
254 @node Fixing overlapping notation
255 @section Fixing overlapping notation
257 This may come as a surprise, but LilyPond isn't perfect. Some notation
258 elements can overlap. This is unfortunate, but (in most cases) is easily
261 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
262 e4^\markup{ \italic ritenuto } g b e
267 The easiest solution is to increase the distance between the object
268 (in this case text, but it could easily be fingerings or dynamics
269 instead) and the note. In LilyPond, this is called the
270 @code{padding} property. For most objects, it is around 1.0 or
271 less (it varies with each object). We want to increase it, so let's
274 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
275 \once \override TextScript #'padding = #1.5
276 e4^\markup{ \italic ritenuto } g b e
279 That looks better, but it isn't quite big enough. After experimenting
280 with a few values, we think 2.3 is the best number in this case. However,
281 this number is merely the result of experimentation and my personal
282 taste in notation. Try the above example with 2.3... but also try higher
283 (and lower) numbers. Which do you think looks the best?
287 Another solution gives us complete control over placing the object -- we
288 can move it horizontally or vertically. This is done with the
289 @code{extra-offset} property. It is slightly more complicated and can
290 cause other problems. When we move objects with @code{extra-offset},
291 the movement is done after LilyPond has placed all other objects. This means
292 that the result can overlap with other objects.
294 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
295 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
296 e4^\markup{ \italic ritenuto } g b e
299 With @code{extra-offset}, the first number controls the horizontal
300 movement (left is negative); the second number controls the vertial
301 movement (up is positive). After a bit of experimenting, we decided
302 that these values look good
304 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
305 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
306 e4^\markup{ \italic ritenuto } g b e
310 Again, these numbers are simply the result of a few experiments and
311 looking at the output. You might prefer the text to be slightly higher,
312 or to the left, or whatever. Try it and look at the result!
317 This manual: @ref{The \override command}, @ref{Common tweaks}.
320 @node How LilyPond files work
321 @section How LilyPond files work
323 The LilyPond input format is quite free-form, giving experienced
324 users a lot of flexibility to structure their files however they
325 wish. However, this flexibility can make things confusing for
326 new users. This section will explain some of this structure, but
327 may gloss over some details in favor of simplicity. For a complete
328 description of the input format, see @ref{File structure}.
330 Most examples in this manual are little snippets -- for example
336 As you are (hopefully) aware by now, this will not compile by
337 itself. These examples are shorthand for complete
338 examples. They all need at least curly braces to compile
347 but most examples also make use of the @code{\relative c'}
348 (or @code{c''}) command. This is not necessary to merely
349 compile the examples, but in most cases the output will
350 look very odd if you omit the @code{\relative c'}.
352 @lilypond[quote,fragment,raggedright,verbatim]
358 Now we get to the only real stumbling block: LilyPond
359 input in this form is actually @emph{another}
360 shorthand. Although it compiles and displays the
361 correct output, it is shorthand for
371 A @code{\score} must begin with a single music
372 expression. Remember that a music expression could
373 be anything from a single note to a huge
378 insert the whole score of a Wager opera in here
384 Since everything is inside @code{@{ ... @}}, it counts
385 as one music expression.
387 The @code{\score} can contain other things, such as
400 Most people put some of those commands outside the
401 @code{\score} block -- for example, @code{\header} is
402 almost always placed above the @code{\score}. That's
403 just another shorthand.
405 Another great shorthand is the ability to define
406 variables. All the templates use this
409 melody = \relative c' @{
418 When LilyPond looks at this file, it takes the value of
419 @code{melody} (ie everything to the right of the
420 @code{melody = }) and inserts it whenever it sees
421 @code{\melody}. There's nothing special about the
422 name @code{melody}, @code{global}, @code{pianorighthand},
423 or @code{foofoobarbaz}. You can use whatever variable
426 For a complete definition
427 of the input format, see @ref{File structure}.
430 @node Troubleshooting (taking it all apart)
431 @section Troubleshooting (taking it all apart)
433 Sooner or later, you will write a file that LilyPond cannot
434 compile. The messages that LilyPond gives may help
435 you find the error, but in many cases you need to do some
436 investigation to determine the source of the problem.
438 The most powerful tool for this purpose is the
439 comment (@code{%} and @code{%@{ ... %@}}). If you don't
440 know where a problem is, start commenting out huge portions
441 of your input file. After you comment out a section, try
442 compiling the file again. If it works, then the problem
443 must exist in the portion you just commented. If it doens't
444 work, then keep on commenting out material until you have
445 something that works.
447 In an extreme case, you might end up with only
460 (in other words, an empty file)
462 If that happens, don't give up. Uncomment a bit -- say,
463 the bass part -- and see if it works. If it doesn't,
464 then comment out all of the bass music (but leave
465 @code{\bass} in the @code{\score} uncommented.
468 bass = \relative c' {
476 Now start slowly uncommenting more and more of the
477 @code{bass} part until you find the problem line.