1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Working on LilyPond projects
3 @chapter Working on LilyPond projects
5 This section explains a how to solve or avoid certain common
6 problems. If you have programming experience, many of these
7 tips may seem obvious, but it is still advisable to read
12 * Suggestions for writing LilyPond files::
13 * Typesetting existing music::
14 * Updating old files::
15 * Troubleshooting (taking it all apart)::
16 * Saving typing with identifiers and functions::
18 * Fitting music onto fewer pages::
22 @node Suggestions for writing LilyPond files
23 @section Suggestions for writing LilyPond files
25 Now you're ready to begin writing larger LilyPond files -- not just the
26 little examples in the tutorial, but whole pieces. But how should you
29 The best answer is ``however you want to do it.'' As long as LilyPond
30 can understand your files and produces the output that you want, it
31 doesn't matter what your files look like. That said, sometimes we
32 make mistakes when writing files. If LilyPond can't understand your
33 files, or produces output that you don't like, how do you fix the
36 Here are a few suggestions that can help you to avoid or fix
40 @item @strong{Include @code{\version} numbers in every file}. Note that all
41 templates contain a @code{\version "2.8.0"} string. We
42 highly recommend that you always include the @code{\version}, no matter
43 how small your file is. Speaking from personal experience, it's
44 quite frustrating to try to remember which version of LilyPond you were
45 using a few years ago. @code{convert-ly} requires you to declare
46 which version of LilyPond you used.
48 @item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}. If
50 include checks every so often, then if you make a mistake, you can pinpoint
51 it quicker. How often is ``every so often''? It depends on the complexity
52 of the music. For very simple music, perhaps just once or twice. For
53 very complex music, perhaps every bar.
55 @item @strong{One bar per line of text}. If there is anything complicated,
57 itself or in the output you desire, it's often good to write only one bar
58 per line. Saving screen space by cramming eight bars per line just isn't
59 worth it if you have to `debug' your files.
61 @item @strong{Comment your files}. Use either bar numbers (every so often)
63 references to musical themes (``second theme in violins,'' ``fourth
64 variation'', etc). You may not need comments when you're writing the piece
65 for the first time, but if you want to go back to change something two or
66 three years later, or if you pass the source over to a friend, it will
68 challenging to determine your intentions or how your file is structured if
69 you didn't comment the file.
71 @item @strong{Indent your braces}. A lot of problems are caused by an
73 in the number of @code{@{} and @code{@}}.
78 @node Typesetting existing music
79 @section Typesetting existing music
81 If you are entering music from an existing score (i.e., typesetting a
82 piece of existing sheet music),
86 @item Enter one manuscript (the physical copy) system at a time (but still
87 only one bar per line of text), and
88 check each system when you finish it. You may use the
89 @code{showLastLength} command to speed up processing -- see
90 @ref{Skipping corrected music}.
92 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
93 in the input file whenever the manuscript has a line break. This
94 makes it much easier to compare the LilyPond music to the original
95 music. When you are finished proofreading your score, you may
96 define @code{mBreak = @{ @}} to remove all those line breaks. This
97 will allow LilyPond to place line breaks wherever it feels are
103 @node Updating old files
104 @section Updating old files
106 The LilyPond input syntax occasionally changes. As LilyPond itself
107 improves, the syntax (input language) is modified accordingly. Sometimes
108 these changes are made to make the input easier to read and write or
109 sometimes the changes are made to accomodate new features of LilyPond.
111 LilyPond comes with a file that makes this updating easier:
112 @code{convert-ly}. For details about how to run this program, see
113 @ref{Updating files with convert-ly}.
115 Unforunately, @code{convert-ly} cannot handle all input changes. It
116 takes care of simple search-and-replace changes (such as @code{raggedright}
117 becoming @code{ragged-right}), but some changes are too
118 complicated. The syntax changes that @code{convert-ly} cannot handle
119 are listed in @ref{Updating files with convert-ly}.
121 For example, in LilyPond 2.4 and earlier, accents and non-English
122 letters were entered using LaTeX -- for example,
123 "@code{No\"el}" (this would print the French word for
124 `Christmas'). In LilyPond 2.6 and above, the special
125 "@code{ë}" must be entered directly into the LilyPond file as an
126 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
127 special characters into UTF-8 characters; you must manually update
128 your old LilyPond files.
131 @node Troubleshooting (taking it all apart)
132 @section Troubleshooting (taking it all apart)
134 Sooner or later, you will write a file that LilyPond cannot
135 compile. The messages that LilyPond gives may help
136 you find the error, but in many cases you need to do some
137 investigation to determine the source of the problem.
139 The most powerful tools for this purpose are the
140 single line comment (indicated by @code{%}) and the block
141 comment (indicated by @code{%@{ ... %@}}). If you don't
142 know where a problem is, start commenting out huge portions
143 of your input file. After you comment out a section, try
144 compiling the file again. If it works, then the problem
145 must exist in the portion you just commented. If it doesn't
146 work, then keep on commenting out material until you have
147 something that works.
149 In an extreme case, you might end up with only
163 (in other words, a file without any music)
165 If that happens, don't give up. Uncomment a bit -- say,
166 the bass part -- and see if it works. If it doesn't work,
167 then comment out all of the bass music (but leave
168 @code{\bass} in the @code{\score} uncommented.
171 bass = \relative c' @{
179 Now start slowly uncommenting more and more of the
180 @code{bass} part until you find the problem line.
183 @node Saving typing with identifiers and functions
184 @section Saving typing with identifiers and functions
186 By this point, you've seen this kind of thing:
188 @lilypond[quote,verbatim,ragged-right]
189 hornNotes = \relative c'' { c4 b dis c }
197 You may even realize that this could be useful in minimalist music:
199 @lilypond[quote,verbatim,ragged-right]
200 fragA = \relative c'' { a4 a8. b16 }
201 fragB = \relative c'' { a8. gis16 ees4 }
202 violin = \new Staff { \fragA \fragA \fragB \fragA }
210 However, you can also use these identifiers (also known as
211 variables, macros, or (user-defined) command) for tweaks:
213 @lilypond[quote,verbatim,ragged-right]
214 dolce = \markup{ \italic \bold dolce }
215 padText = { \once \override TextScript #'padding = #5.0 }
216 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
217 violin = \relative c'' {
219 c4._\dolce b8 a8 g a b |
221 c4.^"hi there!" d8 e' f g d |
222 c,4.\fthenp b8 c4 c-. |
229 \layout{ragged-right=##t}
233 These identifiers are obviously useful for saving
234 typing. But they're worth considering even if you
235 only use them once -- they reduce complexity. Let's
236 look at the previous example without any
237 identifiers. It's a lot harder to read, especially
241 violin = \relative c'' @{
243 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
244 \once \override TextScript #'padding = #5.0
245 c4.^"hi there!" d8 e' f g d |
246 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
247 \hspace #0.1 \dynamic p @} b8 c4 c-. |
252 So far we've seen static substitution -- when LilyPond
253 sees @code{\padText}, it replaces it with the stuff that
254 we've defined it to be (ie the stuff to the right of
257 LilyPond can handle non-static substitution, too (you
258 can think of these as functions).
260 @lilypond[quote,verbatim,ragged-right]
262 #(define-music-function (parser location padding) (number?)
264 \once \override TextScript #'padding = #$padding
272 c4^"piu mosso" fis a g
276 Using identifiers is also a good way to reduce work if the
277 LilyPond input syntax changes (see @ref{Updating old files}). If
278 you have a single definition (such as @code{\dolce}) for all your
279 files (see @ref{Style sheets}), then if the syntax changes, you
280 only need to update your single @code{\dolce} definition,
281 instead of making changes throughout every @code{.ly} file.
285 @section Style sheets
287 The output that LilyPond produces can be heavily modified; see
288 @ref{Tweaking output} for details. But what if you have many
289 files that you want to apply your tweaks to? Or what if you
290 simply want to separate your tweaks from the actual music? This
293 Let's look at an example. Don't worry if you don't understand
294 the parts with all the #(). This is explained in
295 @ref{Advanced tweaks with Scheme}.
297 @lilypond[quote,verbatim,ragged-right]
298 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
299 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
300 tempoMark = #(define-music-function (parser location markp) (string?)
302 \once \override Score . RehearsalMark #'self-alignment-X = #left
303 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
304 \mark \markup { \bold $markp }
309 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
310 \tempoMark "Poco piu mosso"
311 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
315 There are some problems with overlapping output; we'll fix those using
316 the techniques in @ref{Moving objects}. But let's also
317 do something about the @code{mpdolce} and @code{tempoMark}
318 definitions. They produce the output we desire, but we might want
319 to use them in another piece. We could simply copy-and-paste them
320 at the top of every file, but that's an annoyance. It also leaves
321 those definitions in our music files, and I personally find all
322 the #() somewhat ugly. Let's hide them in another file:
325 %%% save this to a file called "definitions.ly"
326 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
327 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
328 tempoMark = #(define-music-function (parser location markp) (string?)
330 \once \override Score . RehearsalMark #'self-alignment-X = #left
331 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
332 \mark \markup @{ \bold $markp @}
336 Now let's modify our music (let's save this file as @file{"music.ly"}).
338 @c We have to do this awkward example/lilypond-non-verbatim
339 @c because we can't do the \include stuff in the manual.
342 \include "definitions.ly"
346 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
347 \once \override Score.RehearsalMark #'padding = #2.0
348 \tempoMark "Poco piu mosso"
349 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
353 @lilypond[quote,ragged-right]
354 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
355 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
356 tempoMark = #(define-music-function (parser location markp) (string?)
358 \once \override Score . RehearsalMark #'self-alignment-X = #left
359 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
360 \mark \markup { \bold $markp }
365 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
366 \once \override Score.RehearsalMark #'padding = #2.0
367 \tempoMark "Poco piu mosso"
368 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
372 That looks better, but let's make a few changes. The glissando is hard
373 to see, so let's make it thicker and closer to the noteheads. Let's
374 put the metronome marking above the clef, instead of over the first
375 note. And finally, my composition professor hates "C" time signatures,
376 so we'd better make that "4/4" instead.
378 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
383 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
384 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
385 tempoMark = #(define-music-function (parser location markp) (string?)
387 \once \override Score . RehearsalMark #'self-alignment-X = #left
388 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
389 \mark \markup @{ \bold $markp @}
394 \override MetronomeMark #'extra-offset = #'(-9 . 0)
395 \override MetronomeMark #'padding = #'3
398 \override TimeSignature #'style = #'numbered
401 \override Glissando #'thickness = #3
402 \override Glissando #'gap = #0.1
407 @lilypond[quote,ragged-right]
408 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
409 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
410 tempoMark = #(define-music-function (parser location markp) (string?)
412 \once \override Score . RehearsalMark #'self-alignment-X = #left
413 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
414 \mark \markup { \bold $markp }
419 \override MetronomeMark #'extra-offset = #'(-9 . 0)
420 \override MetronomeMark #'padding = #'3
423 \override TimeSignature #'style = #'numbered
426 \override Glissando #'thickness = #3
427 \override Glissando #'gap = #0.1
433 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
434 \once \override Score.RehearsalMark #'padding = #2.0
435 \tempoMark "Poco piu mosso"
436 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
440 That looks nicer! But now suppose that I want to publish this
441 piece. My composition professor doesn't like "C" time
442 signatures, but I'm somewhat fond of them. Let's copy the
443 current @file{definitions.ly} to @file{web-publish.ly} and
444 modify that. Since this music is aimed at producing a pdf which
445 will be displayed on the screen, we'll also increase the
446 overall size of the output.
450 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
451 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
452 tempoMark = #(define-music-function (parser location markp) (string?)
454 \once \override Score . RehearsalMark #'self-alignment-X = #left
455 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
456 \mark \markup @{ \bold $markp @}
459 #(set-global-staff-size 23)
462 \override MetronomeMark #'extra-offset = #'(-9 . 0)
463 \override MetronomeMark #'padding = #'3
468 \override Glissando #'thickness = #3
469 \override Glissando #'gap = #0.1
474 @lilypond[quote,ragged-right]
475 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
476 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
477 tempoMark = #(define-music-function (parser location markp) (string?)
479 \once \override Score . RehearsalMark #'self-alignment-X = #left
480 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
481 \mark \markup { \bold $markp }
484 #(set-global-staff-size 23)
487 \override MetronomeMark #'extra-offset = #'(-9 . 0)
488 \override MetronomeMark #'padding = #'3
491 \override Glissando #'thickness = #3
492 \override Glissando #'gap = #0.1
498 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
499 \once \override Score.RehearsalMark #'padding = #2.0
500 \tempoMark "Poco piu mosso"
501 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
505 Now in our music, I simply replace
506 @code{\include "definitions.ly"} with
507 @code{\include "web-publish.ly"}. Of course, we could make this
508 even more convenient. We could make a @file{definitions.ly} file which
509 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
510 @file{web-publish.ly} file which contains only the @code{\layout}
511 section listed above, and a @file{university.ly} file which
512 contains only the tweaks to produce the output that my professor
513 prefers. The top of @file{music.ly} would then look like this:
516 \include "definitions.ly"
518 %%% Only uncomment one of these two lines!
519 \include "web-publish.ly"
520 %\include "university.ly"
523 This approach can be useful even if you are only producing
524 one set of parts. I use half a dozen different
525 ``style sheet'' files for my projects. I begin every music
526 file with @code{\include "../global.ly"}, which contains
531 #(ly:set-option 'point-and-click #f)
532 \include "../init/init-defs.ly"
533 \include "../init/init-layout.ly"
534 \include "../init/init-headers.ly"
535 \include "../init/init-paper.ly"
539 @node Fitting music onto fewer pages
540 @section Fitting music onto fewer pages
542 Sometimes you can end up with one or two staves on a second
543 (or third, or fourth...) page. This is annoying, especially
544 if you look at previous pages and it looks like there is plenty
545 of room left on those.
547 When investigating layout issues, @code{annotate-spacing} is
548 an invaluable tool. This command prints the values of various
549 layout spacing commands; see @ref{Displaying spacing} for more
550 details. From the output of @code{annotate-spacing}, we can
551 see which margins we may wish to alter.
553 Other than margins, there are a few other options to save space:
557 You may tell LilyPond to place systems as close together as
558 possible (to fit as many systems as possible onto a page), but
559 then to space those systems out so that there is no blank
560 space at the bottom of the page.
564 between-system-padding = #0.5
565 ragged-last-bottom = ##f
571 You may force the number of systems (i.e., if LilyPond wants
572 to typeset some music with 11 systems, you could force it to
582 Avoid (or reduce) objects which increase the vertical size of
583 a system. For example, volta repeats (or alternate repeats)
584 require extra space. If these repeats are spread over two
585 systems, they will take up more space than one system with
586 the volta repeats and another system without.
588 Another example is moving dynamics which ``stick out'' of
591 @lilypond[verbatim,quote,fragment]
594 \override DynamicLineSpanner #'padding = #-1.8
595 \override DynamicText #'extra-offset = #'( -2.1 . 0)