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{@}}.
75 @item @strong{Explicity add durations} at the beginnings of sections
76 and identifiers. If you specify @code{c4 d e} at the beginning of a
77 phrase (instead of just @code{c d e}) you can save yourself some
78 problems if you rearrange your music later.
83 @node Typesetting existing music
84 @section Typesetting existing music
86 If you are entering music from an existing score (i.e., typesetting a
87 piece of existing sheet music),
91 @item Enter one manuscript (the physical copy) system at a time (but still
92 only one bar per line of text), and
93 check each system when you finish it. You may use the
94 @code{showLastLength} command to speed up processing -- see
95 @ref{Skipping corrected music}.
97 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
98 in the input file whenever the manuscript has a line break. This
99 makes it much easier to compare the LilyPond music to the original
100 music. When you are finished proofreading your score, you may
101 define @code{mBreak = @{ @}} to remove all those line breaks. This
102 will allow LilyPond to place line breaks wherever it feels are
108 @node Updating old files
109 @section Updating old files
111 The LilyPond input syntax occasionally changes. As LilyPond itself
112 improves, the syntax (input language) is modified accordingly. Sometimes
113 these changes are made to make the input easier to read and write or
114 sometimes the changes are made to accomodate new features of LilyPond.
116 LilyPond comes with a file that makes this updating easier:
117 @code{convert-ly}. For details about how to run this program, see
118 @ref{Updating files with convert-ly}.
120 Unforunately, @code{convert-ly} cannot handle all input changes. It
121 takes care of simple search-and-replace changes (such as @code{raggedright}
122 becoming @code{ragged-right}), but some changes are too
123 complicated. The syntax changes that @code{convert-ly} cannot handle
124 are listed in @ref{Updating files with convert-ly}.
126 For example, in LilyPond 2.4 and earlier, accents and non-English
127 letters were entered using LaTeX -- for example,
128 "@code{No\"el}" (this would print the French word for
129 `Christmas'). In LilyPond 2.6 and above, the special
130 "@code{ë}" must be entered directly into the LilyPond file as an
131 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
132 special characters into UTF-8 characters; you must manually update
133 your old LilyPond files.
136 @node Troubleshooting (taking it all apart)
137 @section Troubleshooting (taking it all apart)
139 Sooner or later, you will write a file that LilyPond cannot
140 compile. The messages that LilyPond gives may help
141 you find the error, but in many cases you need to do some
142 investigation to determine the source of the problem.
144 The most powerful tools for this purpose are the
145 single line comment (indicated by @code{%}) and the block
146 comment (indicated by @code{%@{ ... %@}}). If you don't
147 know where a problem is, start commenting out huge portions
148 of your input file. After you comment out a section, try
149 compiling the file again. If it works, then the problem
150 must exist in the portion you just commented. If it doesn't
151 work, then keep on commenting out material until you have
152 something that works.
154 In an extreme case, you might end up with only
168 (in other words, a file without any music)
170 If that happens, don't give up. Uncomment a bit -- say,
171 the bass part -- and see if it works. If it doesn't work,
172 then comment out all of the bass music (but leave
173 @code{\bass} in the @code{\score} uncommented.
176 bass = \relative c' @{
184 Now start slowly uncommenting more and more of the
185 @code{bass} part until you find the problem line.
188 @node Saving typing with identifiers and functions
189 @section Saving typing with identifiers and functions
191 By this point, you've seen this kind of thing:
193 @lilypond[quote,verbatim,ragged-right]
194 hornNotes = \relative c'' { c4 b dis c }
202 You may even realize that this could be useful in minimalist music:
204 @lilypond[quote,verbatim,ragged-right]
205 fragA = \relative c'' { a4 a8. b16 }
206 fragB = \relative c'' { a8. gis16 ees4 }
207 violin = \new Staff { \fragA \fragA \fragB \fragA }
215 However, you can also use these identifiers (also known as
216 variables, macros, or (user-defined) command) for tweaks:
218 @lilypond[quote,verbatim,ragged-right]
219 dolce = \markup{ \italic \bold dolce }
220 padText = { \once \override TextScript #'padding = #5.0 }
221 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
222 violin = \relative c'' {
224 c4._\dolce b8 a8 g a b |
226 c4.^"hi there!" d8 e' f g d |
227 c,4.\fthenp b8 c4 c-. |
234 \layout{ragged-right=##t}
238 These identifiers are obviously useful for saving
239 typing. But they're worth considering even if you
240 only use them once -- they reduce complexity. Let's
241 look at the previous example without any
242 identifiers. It's a lot harder to read, especially
246 violin = \relative c'' @{
248 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
249 \once \override TextScript #'padding = #5.0
250 c4.^"hi there!" d8 e' f g d |
251 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
252 \hspace #0.1 \dynamic p @} b8 c4 c-. |
257 So far we've seen static substitution -- when LilyPond
258 sees @code{\padText}, it replaces it with the stuff that
259 we've defined it to be (ie the stuff to the right of
262 LilyPond can handle non-static substitution, too (you
263 can think of these as functions).
265 @lilypond[quote,verbatim,ragged-right]
267 #(define-music-function (parser location padding) (number?)
269 \once \override TextScript #'padding = #$padding
277 c4^"piu mosso" fis a g
281 Using identifiers is also a good way to reduce work if the
282 LilyPond input syntax changes (see @ref{Updating old files}). If
283 you have a single definition (such as @code{\dolce}) for all your
284 files (see @ref{Style sheets}), then if the syntax changes, you
285 only need to update your single @code{\dolce} definition,
286 instead of making changes throughout every @code{.ly} file.
290 @section Style sheets
292 The output that LilyPond produces can be heavily modified; see
293 @ref{Tweaking output} for details. But what if you have many
294 files that you want to apply your tweaks to? Or what if you
295 simply want to separate your tweaks from the actual music? This
298 Let's look at an example. Don't worry if you don't understand
299 the parts with all the #(). This is explained in
300 @ref{Advanced tweaks with Scheme}.
302 @lilypond[quote,verbatim,ragged-right]
303 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
304 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
305 tempoMark = #(define-music-function (parser location markp) (string?)
307 \once \override Score . RehearsalMark #'self-alignment-X = #left
308 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
309 \mark \markup { \bold $markp }
314 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
315 \tempoMark "Poco piu mosso"
316 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
320 There are some problems with overlapping output; we'll fix those using
321 the techniques in @ref{Moving objects}. But let's also
322 do something about the @code{mpdolce} and @code{tempoMark}
323 definitions. They produce the output we desire, but we might want
324 to use them in another piece. We could simply copy-and-paste them
325 at the top of every file, but that's an annoyance. It also leaves
326 those definitions in our music files, and I personally find all
327 the #() somewhat ugly. Let's hide them in another file:
330 %%% save this to a file called "definitions.ly"
331 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
332 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
333 tempoMark = #(define-music-function (parser location markp) (string?)
335 \once \override Score . RehearsalMark #'self-alignment-X = #left
336 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
337 \mark \markup @{ \bold $markp @}
341 Now let's modify our music (let's save this file as @file{"music.ly"}).
343 @c We have to do this awkward example/lilypond-non-verbatim
344 @c because we can't do the \include stuff in the manual.
347 \include "definitions.ly"
351 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
352 \once \override Score.RehearsalMark #'padding = #2.0
353 \tempoMark "Poco piu mosso"
354 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
358 @lilypond[quote,ragged-right]
359 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
360 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
361 tempoMark = #(define-music-function (parser location markp) (string?)
363 \once \override Score . RehearsalMark #'self-alignment-X = #left
364 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
365 \mark \markup { \bold $markp }
370 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
371 \once \override Score.RehearsalMark #'padding = #2.0
372 \tempoMark "Poco piu mosso"
373 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
377 That looks better, but let's make a few changes. The glissando is hard
378 to see, so let's make it thicker and closer to the noteheads. Let's
379 put the metronome marking above the clef, instead of over the first
380 note. And finally, my composition professor hates "C" time signatures,
381 so we'd better make that "4/4" instead.
383 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
388 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
389 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
390 tempoMark = #(define-music-function (parser location markp) (string?)
392 \once \override Score . RehearsalMark #'self-alignment-X = #left
393 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
394 \mark \markup @{ \bold $markp @}
399 \override MetronomeMark #'extra-offset = #'(-9 . 0)
400 \override MetronomeMark #'padding = #'3
403 \override TimeSignature #'style = #'numbered
406 \override Glissando #'thickness = #3
407 \override Glissando #'gap = #0.1
412 @lilypond[quote,ragged-right]
413 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
414 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
415 tempoMark = #(define-music-function (parser location markp) (string?)
417 \once \override Score . RehearsalMark #'self-alignment-X = #left
418 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
419 \mark \markup { \bold $markp }
424 \override MetronomeMark #'extra-offset = #'(-9 . 0)
425 \override MetronomeMark #'padding = #'3
428 \override TimeSignature #'style = #'numbered
431 \override Glissando #'thickness = #3
432 \override Glissando #'gap = #0.1
438 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
439 \once \override Score.RehearsalMark #'padding = #2.0
440 \tempoMark "Poco piu mosso"
441 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
445 That looks nicer! But now suppose that I want to publish this
446 piece. My composition professor doesn't like "C" time
447 signatures, but I'm somewhat fond of them. Let's copy the
448 current @file{definitions.ly} to @file{web-publish.ly} and
449 modify that. Since this music is aimed at producing a pdf which
450 will be displayed on the screen, we'll also increase the
451 overall size of the output.
455 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
456 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
457 tempoMark = #(define-music-function (parser location markp) (string?)
459 \once \override Score . RehearsalMark #'self-alignment-X = #left
460 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
461 \mark \markup @{ \bold $markp @}
464 #(set-global-staff-size 23)
467 \override MetronomeMark #'extra-offset = #'(-9 . 0)
468 \override MetronomeMark #'padding = #'3
473 \override Glissando #'thickness = #3
474 \override Glissando #'gap = #0.1
479 @lilypond[quote,ragged-right]
480 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
481 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
482 tempoMark = #(define-music-function (parser location markp) (string?)
484 \once \override Score . RehearsalMark #'self-alignment-X = #left
485 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
486 \mark \markup { \bold $markp }
489 #(set-global-staff-size 23)
492 \override MetronomeMark #'extra-offset = #'(-9 . 0)
493 \override MetronomeMark #'padding = #'3
496 \override Glissando #'thickness = #3
497 \override Glissando #'gap = #0.1
503 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
504 \once \override Score.RehearsalMark #'padding = #2.0
505 \tempoMark "Poco piu mosso"
506 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
510 Now in our music, I simply replace
511 @code{\include "definitions.ly"} with
512 @code{\include "web-publish.ly"}. Of course, we could make this
513 even more convenient. We could make a @file{definitions.ly} file which
514 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
515 @file{web-publish.ly} file which contains only the @code{\layout}
516 section listed above, and a @file{university.ly} file which
517 contains only the tweaks to produce the output that my professor
518 prefers. The top of @file{music.ly} would then look like this:
521 \include "definitions.ly"
523 %%% Only uncomment one of these two lines!
524 \include "web-publish.ly"
525 %\include "university.ly"
528 This approach can be useful even if you are only producing
529 one set of parts. I use half a dozen different
530 ``style sheet'' files for my projects. I begin every music
531 file with @code{\include "../global.ly"}, which contains
536 #(ly:set-option 'point-and-click #f)
537 \include "../init/init-defs.ly"
538 \include "../init/init-layout.ly"
539 \include "../init/init-headers.ly"
540 \include "../init/init-paper.ly"
544 @node Fitting music onto fewer pages
545 @section Fitting music onto fewer pages
547 Sometimes you can end up with one or two staves on a second
548 (or third, or fourth...) page. This is annoying, especially
549 if you look at previous pages and it looks like there is plenty
550 of room left on those.
552 When investigating layout issues, @code{annotate-spacing} is
553 an invaluable tool. This command prints the values of various
554 layout spacing commands; see @ref{Displaying spacing} for more
555 details. From the output of @code{annotate-spacing}, we can
556 see which margins we may wish to alter.
558 Other than margins, there are a few other options to save space:
562 You may tell LilyPond to place systems as close together as
563 possible (to fit as many systems as possible onto a page), but
564 then to space those systems out so that there is no blank
565 space at the bottom of the page.
569 between-system-padding = #0.5
570 ragged-last-bottom = ##f
576 You may force the number of systems (i.e., if LilyPond wants
577 to typeset some music with 11 systems, you could force it to
587 Avoid (or reduce) objects which increase the vertical size of
588 a system. For example, volta repeats (or alternate repeats)
589 require extra space. If these repeats are spread over two
590 systems, they will take up more space than one system with
591 the volta repeats and another system without.
593 Another example is moving dynamics which ``stick out'' of
596 @lilypond[verbatim,quote,fragment]
599 \override DynamicLineSpanner #'padding = #-1.8
600 \override DynamicText #'extra-offset = #'( -2.1 . 0)
606 Alter the horizontal spacing via @code{SpacingSpanner}. See
607 @ref{Changing horizontal spacing} for more details.
609 @lilypond[verbatim,quote]
612 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
613 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
614 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
615 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
620 \override SpacingSpanner
621 #'base-shortest-duration = #(ly:make-moment 1 4)