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 * Saving typing with identifiers and functions::
15 * Updating old files::
16 * Troubleshooting (taking it all apart)::
20 @node Suggestions for writing LilyPond files
21 @section Suggestions for writing LilyPond files
23 Now you're ready to begin writing larger LilyPond files -- not just the
24 little examples in the tutorial, but whole pieces. But how should you
27 As long as LilyPond can understand your files and produces the output
28 that you want, it doesn't matter what your files look like. However,
29 there are a few other things to consider when writing lilypond files.
32 @item What if you make a mistake? The structure of a lilypond
33 file can make certain errors easier (or harder) to find.
35 @item What if you want to share your files with somebody
36 else? In fact, what if you want to alter your own files in
37 a few years? Some lilypond files are understandable at
38 first glance; other files may leave you scratching your head
41 @item What if you want to upgrade your lilypond file for use
42 with a later version of lilypond? The input syntax changes
43 occasionally as lilypond improves. Most changes can be
44 done automatically with @code{convert-ly}, but some changes
45 might require manual assistance. Lilypond files can be
46 structured in order to be easier (or header) to update.
50 * General suggestions::
51 * Typesetting existing music::
56 @node General suggestions
57 @subsection General suggestions
59 Here are a few suggestions that can help you to avoid or fix
63 @item @strong{Include @code{\version} numbers in every file}. Note that all
64 templates contain a @code{\version "2.9.13"} string. We
65 highly recommend that you always include the @code{\version}, no matter
66 how small your file is. Speaking from personal experience, it's
67 quite frustrating to try to remember which version of LilyPond you were
68 using a few years ago. @code{convert-ly} requires you to declare
69 which version of LilyPond you used.
71 @item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}. If
73 include checks every so often, then if you make a mistake, you can pinpoint
74 it quicker. How often is ``every so often''? It depends on the complexity
75 of the music. For very simple music, perhaps just once or twice. For
76 very complex music, perhaps every bar.
78 @item @strong{One bar per line of text}. If there is anything complicated,
80 itself or in the output you desire, it's often good to write only one bar
81 per line. Saving screen space by cramming eight bars per line just isn't
82 worth it if you have to `debug' your files.
84 @item @strong{Comment your files}. Use either bar numbers (every so often)
86 references to musical themes (``second theme in violins,'' ``fourth
87 variation'', etc). You may not need comments when you're writing the piece
88 for the first time, but if you want to go back to change something two or
89 three years later, or if you pass the source over to a friend, it will
91 challenging to determine your intentions or how your file is structured if
92 you didn't comment the file.
94 @item @strong{Indent your braces}. A lot of problems are caused by an
96 in the number of @code{@{} and @code{@}}.
98 @item @strong{Explicity add durations} at the beginnings of sections
99 and identifiers. If you specify @code{c4 d e} at the beginning of a
100 phrase (instead of just @code{c d e}) you can save yourself some
101 problems if you rearrange your music later.
103 @item @strong{Separate tweaks} from music definitions. See
104 @ref{Saving typing with identifiers and functions} and
110 @node Typesetting existing music
111 @subsection Typesetting existing music
113 If you are entering music from an existing score (i.e., typesetting a
114 piece of existing sheet music),
118 @item Enter one manuscript (the physical copy) system at a time (but still
119 only one bar per line of text), and
120 check each system when you finish it. You may use the
121 @code{showLastLength} command to speed up processing -- see
122 @ref{Skipping corrected music}.
124 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
125 in the input file whenever the manuscript has a line break. This
126 makes it much easier to compare the LilyPond music to the original
127 music. When you are finished proofreading your score, you may
128 define @code{mBreak = @{ @}} to remove all those line breaks. This
129 will allow LilyPond to place line breaks wherever it feels are
136 @subsection Large projects
138 When working on a large project, having a clear structure to your
139 lilypond files becomes vital.
143 @item @strong{Use an identifier for each voice}, with a minimum of
144 structure inside the definition. The structure of the
145 @code{\score} section is the most likely thing to change;
146 the @code{violin} definition is extremely unlikely to change
147 in a new version of LilyPond.
150 violin = \relative c'' @{
163 @item @strong{Separate tweaks from music definitions}. This
164 point was made in @ref{General suggestions}, but for large
165 projects it is absolutely vital. We might need to change
166 the definition of @code{fthenp}, but then we only need
167 to do this once, and we can still avoid touching anything
168 inside @code{violin}.
172 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
173 violin = \relative c'' @{
181 @node Saving typing with identifiers and functions
182 @section Saving typing with identifiers and functions
187 By this point, you've seen this kind of thing:
189 @lilypond[quote,verbatim,ragged-right]
190 hornNotes = \relative c'' { c4 b dis c }
198 You may even realize that this could be useful in minimalist music:
200 @lilypond[quote,verbatim,ragged-right]
201 fragA = \relative c'' { a4 a8. b16 }
202 fragB = \relative c'' { a8. gis16 ees4 }
203 violin = \new Staff { \fragA \fragA \fragB \fragA }
211 However, you can also use these identifiers (also known as
212 variables, macros, or (user-defined) command) for tweaks:
214 @lilypond[quote,verbatim,ragged-right]
215 dolce = \markup{ \italic \bold dolce }
216 padText = { \once \override TextScript #'padding = #5.0 }
217 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
218 violin = \relative c'' {
220 c4._\dolce b8 a8 g a b |
222 c4.^"hi there!" d8 e' f g d |
223 c,4.\fthenp b8 c4 c-. |
230 \layout{ragged-right=##t}
234 These identifiers are obviously useful for saving
235 typing. But they're worth considering even if you
236 only use them once -- they reduce complexity. Let's
237 look at the previous example without any
238 identifiers. It's a lot harder to read, especially
242 violin = \relative c'' @{
244 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
245 \once \override TextScript #'padding = #5.0
246 c4.^"hi there!" d8 e' f g d |
247 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
248 \hspace #0.1 \dynamic p @} b8 c4 c-. |
253 So far we've seen static substitution -- when LilyPond
254 sees @code{\padText}, it replaces it with the stuff that
255 we've defined it to be (ie the stuff to the right of
258 LilyPond can handle non-static substitution, too (you
259 can think of these as functions).
261 @lilypond[quote,verbatim,ragged-right]
263 #(define-music-function (parser location padding) (number?)
265 \once \override TextScript #'padding = #$padding
273 c4^"piu mosso" fis a g
277 Using identifiers is also a good way to reduce work if the
278 LilyPond input syntax changes (see @ref{Updating old files}). If
279 you have a single definition (such as @code{\dolce}) for all your
280 files (see @ref{Style sheets}), then if the syntax changes, you
281 only need to update your single @code{\dolce} definition,
282 instead of making changes throughout every @code{.ly} file.
286 @section Style sheets
288 The output that LilyPond produces can be heavily modified; see
289 @ref{Tweaking output} for details. But what if you have many
290 files that you want to apply your tweaks to? Or what if you
291 simply want to separate your tweaks from the actual music? This
294 Let's look at an example. Don't worry if you don't understand
295 the parts with all the #(). This is explained in
296 @ref{Advanced tweaks with Scheme}.
298 @lilypond[quote,verbatim,ragged-right]
299 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
300 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
301 tempoMark = #(define-music-function (parser location markp) (string?)
303 \once \override Score . RehearsalMark #'self-alignment-X = #left
304 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
305 \mark \markup { \bold $markp }
310 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
311 \tempoMark "Poco piu mosso"
312 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
316 There are some problems with overlapping output; we'll fix those using
317 the techniques in @ref{Moving objects}. But let's also
318 do something about the @code{mpdolce} and @code{tempoMark}
319 definitions. They produce the output we desire, but we might want
320 to use them in another piece. We could simply copy-and-paste them
321 at the top of every file, but that's an annoyance. It also leaves
322 those definitions in our music files, and I personally find all
323 the #() somewhat ugly. Let's hide them in another file:
326 %%% save this to a file called "definitions.ly"
327 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
328 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
329 tempoMark = #(define-music-function (parser location markp) (string?)
331 \once \override Score . RehearsalMark #'self-alignment-X = #left
332 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
333 \mark \markup @{ \bold $markp @}
337 Now let's modify our music (let's save this file as @file{"music.ly"}).
339 @c We have to do this awkward example/lilypond-non-verbatim
340 @c because we can't do the \include stuff in the manual.
343 \include "definitions.ly"
347 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
348 \once \override Score.RehearsalMark #'padding = #2.0
349 \tempoMark "Poco piu mosso"
350 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
354 @lilypond[quote,ragged-right]
355 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
356 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
357 tempoMark = #(define-music-function (parser location markp) (string?)
359 \once \override Score . RehearsalMark #'self-alignment-X = #left
360 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
361 \mark \markup { \bold $markp }
366 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
367 \once \override Score.RehearsalMark #'padding = #2.0
368 \tempoMark "Poco piu mosso"
369 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
373 That looks better, but let's make a few changes. The glissando is hard
374 to see, so let's make it thicker and closer to the noteheads. Let's
375 put the metronome marking above the clef, instead of over the first
376 note. And finally, my composition professor hates "C" time signatures,
377 so we'd better make that "4/4" instead.
379 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
384 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
385 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
386 tempoMark = #(define-music-function (parser location markp) (string?)
388 \once \override Score . RehearsalMark #'self-alignment-X = #left
389 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
390 \mark \markup @{ \bold $markp @}
395 \override MetronomeMark #'extra-offset = #'(-9 . 0)
396 \override MetronomeMark #'padding = #'3
399 \override TimeSignature #'style = #'numbered
402 \override Glissando #'thickness = #3
403 \override Glissando #'gap = #0.1
408 @lilypond[quote,ragged-right]
409 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
410 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
411 tempoMark = #(define-music-function (parser location markp) (string?)
413 \once \override Score . RehearsalMark #'self-alignment-X = #left
414 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
415 \mark \markup { \bold $markp }
420 \override MetronomeMark #'extra-offset = #'(-9 . 0)
421 \override MetronomeMark #'padding = #'3
424 \override TimeSignature #'style = #'numbered
427 \override Glissando #'thickness = #3
428 \override Glissando #'gap = #0.1
434 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
435 \once \override Score.RehearsalMark #'padding = #2.0
436 \tempoMark "Poco piu mosso"
437 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
441 That looks nicer! But now suppose that I want to publish this
442 piece. My composition professor doesn't like "C" time
443 signatures, but I'm somewhat fond of them. Let's copy the
444 current @file{definitions.ly} to @file{web-publish.ly} and
445 modify that. Since this music is aimed at producing a pdf which
446 will be displayed on the screen, we'll also increase the
447 overall size of the output.
451 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
452 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
453 tempoMark = #(define-music-function (parser location markp) (string?)
455 \once \override Score . RehearsalMark #'self-alignment-X = #left
456 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
457 \mark \markup @{ \bold $markp @}
460 #(set-global-staff-size 23)
463 \override MetronomeMark #'extra-offset = #'(-9 . 0)
464 \override MetronomeMark #'padding = #'3
469 \override Glissando #'thickness = #3
470 \override Glissando #'gap = #0.1
475 @lilypond[quote,ragged-right]
476 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
477 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
478 tempoMark = #(define-music-function (parser location markp) (string?)
480 \once \override Score . RehearsalMark #'self-alignment-X = #left
481 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
482 \mark \markup { \bold $markp }
485 #(set-global-staff-size 23)
488 \override MetronomeMark #'extra-offset = #'(-9 . 0)
489 \override MetronomeMark #'padding = #'3
492 \override Glissando #'thickness = #3
493 \override Glissando #'gap = #0.1
499 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
500 \once \override Score.RehearsalMark #'padding = #2.0
501 \tempoMark "Poco piu mosso"
502 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
506 Now in our music, I simply replace
507 @code{\include "definitions.ly"} with
508 @code{\include "web-publish.ly"}. Of course, we could make this
509 even more convenient. We could make a @file{definitions.ly} file which
510 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
511 @file{web-publish.ly} file which contains only the @code{\layout}
512 section listed above, and a @file{university.ly} file which
513 contains only the tweaks to produce the output that my professor
514 prefers. The top of @file{music.ly} would then look like this:
517 \include "definitions.ly"
519 %%% Only uncomment one of these two lines!
520 \include "web-publish.ly"
521 %\include "university.ly"
524 This approach can be useful even if you are only producing
525 one set of parts. I use half a dozen different
526 ``style sheet'' files for my projects. I begin every music
527 file with @code{\include "../global.ly"}, which contains
532 #(ly:set-option 'point-and-click #f)
533 \include "../init/init-defs.ly"
534 \include "../init/init-layout.ly"
535 \include "../init/init-headers.ly"
536 \include "../init/init-paper.ly"
540 @node Updating old files
541 @section Updating old files
543 The LilyPond input syntax occasionally changes. As LilyPond itself
544 improves, the syntax (input language) is modified accordingly. Sometimes
545 these changes are made to make the input easier to read and write or
546 sometimes the changes are made to accomodate new features of LilyPond.
548 LilyPond comes with a file that makes this updating easier:
549 @code{convert-ly}. For details about how to run this program, see
550 @ref{Updating files with convert-ly}.
552 Unforunately, @code{convert-ly} cannot handle all input changes. It
553 takes care of simple search-and-replace changes (such as @code{raggedright}
554 becoming @code{ragged-right}), but some changes are too
555 complicated. The syntax changes that @code{convert-ly} cannot handle
556 are listed in @ref{Updating files with convert-ly}.
558 For example, in LilyPond 2.4 and earlier, accents and non-English
559 letters were entered using LaTeX -- for example,
560 "@code{No\"el}" (this would print the French word for
561 `Christmas'). In LilyPond 2.6 and above, the special
562 "@code{ë}" must be entered directly into the LilyPond file as an
563 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
564 special characters into UTF-8 characters; you must manually update
565 your old LilyPond files.
568 @node Troubleshooting (taking it all apart)
569 @section Troubleshooting (taking it all apart)
571 Sooner or later, you will write a file that LilyPond cannot
572 compile. The messages that LilyPond gives may help
573 you find the error, but in many cases you need to do some
574 investigation to determine the source of the problem.
576 The most powerful tools for this purpose are the
577 single line comment (indicated by @code{%}) and the block
578 comment (indicated by @code{%@{ ... %@}}). If you don't
579 know where a problem is, start commenting out huge portions
580 of your input file. After you comment out a section, try
581 compiling the file again. If it works, then the problem
582 must exist in the portion you just commented. If it doesn't
583 work, then keep on commenting out material until you have
584 something that works.
586 In an extreme case, you might end up with only
600 (in other words, a file without any music)
602 If that happens, don't give up. Uncomment a bit -- say,
603 the bass part -- and see if it works. If it doesn't work,
604 then comment out all of the bass music (but leave
605 @code{\bass} in the @code{\score} uncommented.
608 bass = \relative c' @{
616 Now start slowly uncommenting more and more of the
617 @code{bass} part until you find the problem line.