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::
21 @node Suggestions for writing LilyPond files
22 @section Suggestions for writing LilyPond files
24 Now you're ready to begin writing larger LilyPond files -- not just the
25 little examples in the tutorial, but whole pieces. But how should you
28 The best answer is ``however you want to do it.'' As long as LilyPond
29 can understand your files and produces the output that you want, it
30 doesn't matter what your files look like. That said, sometimes we
31 make mistakes when writing files. If LilyPond can't understand your
32 files, or produces output that you don't like, how do you fix the
35 Here are a few suggestions that can help you to avoid or fix
39 @item @strong{Include @code{\version} numbers in every file}. Note that all
40 templates contain a @code{\version "2.8.0"} string. We
41 highly recommend that you always include the @code{\version}, no matter
42 how small your file is. Speaking from personal experience, it's
43 quite frustrating to try to remember which version of LilyPond you were
44 using a few years ago. @code{convert-ly} requires you to declare
45 which version of LilyPond you used.
47 @item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}. If
49 include checks every so often, then if you make a mistake, you can pinpoint
50 it quicker. How often is ``every so often''? It depends on the complexity
51 of the music. For very simple music, perhaps just once or twice. For
52 very complex music, perhaps every bar.
54 @item @strong{One bar per line of text}. If there is anything complicated,
56 itself or in the output you desire, it's often good to write only one bar
57 per line. Saving screen space by cramming eight bars per line just isn't
58 worth it if you have to `debug' your files.
60 @item @strong{Comment your files}. Use either bar numbers (every so often)
62 references to musical themes (``second theme in violins,'' ``fourth
63 variation'', etc). You may not need comments when you're writing the piece
64 for the first time, but if you want to go back to change something two or
65 three years later, or if you pass the source over to a friend, it will
67 challenging to determine your intentions or how your file is structured if
68 you didn't comment the file.
70 @item @strong{Indent your braces}. A lot of problems are caused by an
72 in the number of @code{@{} and @code{@}}.
77 @node Typesetting existing music
78 @section Typesetting existing music
80 If you are entering music from an existing score (i.e., typesetting a
81 piece of existing sheet music),
85 @item Enter one manuscript (the physical copy) system at a time (but still
86 only one bar per line of text), and
87 check each system when you finish it. You may use the
88 @code{showLastLength} command to speed up processing -- see
89 @ref{Skipping corrected music}.
91 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
92 in the input file whenever the manuscript has a line break. This
93 makes it much easier to compare the LilyPond music to the original
94 music. When you are finished proofreading your score, you may
95 define @code{mBreak = @{ @}} to remove all those line breaks. This
96 will allow LilyPond to place line breaks wherever it feels are
102 @node Updating old files
103 @section Updating old files
105 The LilyPond input syntax occasionally changes. As LilyPond itself
106 improves, the syntax (input language) is modified accordingly. Sometimes
107 these changes are made to make the input easier to read and write or
108 sometimes the changes are made to accomodate new features of LilyPond.
110 LilyPond comes with a file that makes this updating easier:
111 @code{convert-ly}. For details about how to run this program, see
112 @ref{Updating files with convert-ly}.
114 Unforunately, @code{convert-ly} cannot handle all input changes. It
115 takes care of simple search-and-replace changes (such as @code{raggedright}
116 becoming @code{ragged-right}), but some changes are too
117 complicated. The syntax changes that @code{convert-ly} cannot handle
118 are listed in @ref{Updating files with convert-ly}.
120 For example, in LilyPond 2.4 and earlier, accents and non-English
121 letters were entered using LaTeX -- for example,
122 "@code{No\"el}" (this would print the French word for
123 `Christmas'). In LilyPond 2.6 and above, the special
124 "@code{ë}" must be entered directly into the LilyPond file as an
125 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
126 special characters into UTF-8 characters; you must manually update
127 your old LilyPond files.
130 @node Troubleshooting (taking it all apart)
131 @section Troubleshooting (taking it all apart)
133 Sooner or later, you will write a file that LilyPond cannot
134 compile. The messages that LilyPond gives may help
135 you find the error, but in many cases you need to do some
136 investigation to determine the source of the problem.
138 The most powerful tools for this purpose are the
139 single line comment (indicated by @code{%}) and the block
140 comment (indicated by @code{%@{ ... %@}}). If you don't
141 know where a problem is, start commenting out huge portions
142 of your input file. After you comment out a section, try
143 compiling the file again. If it works, then the problem
144 must exist in the portion you just commented. If it doesn't
145 work, then keep on commenting out material until you have
146 something that works.
148 In an extreme case, you might end up with only
162 (in other words, a file without any music)
164 If that happens, don't give up. Uncomment a bit -- say,
165 the bass part -- and see if it works. If it doesn't work,
166 then comment out all of the bass music (but leave
167 @code{\bass} in the @code{\score} uncommented.
170 bass = \relative c' @{
178 Now start slowly uncommenting more and more of the
179 @code{bass} part until you find the problem line.
182 @node Saving typing with identifiers and functions
183 @section Saving typing with identifiers and functions
185 By this point, you've seen this kind of thing:
187 @lilypond[quote,verbatim,ragged-right]
188 hornNotes = \relative c'' { c4 b dis c }
196 You may even realize that this could be useful in minimalist music:
198 @lilypond[quote,verbatim,ragged-right]
199 fragA = \relative c'' { a4 a8. b16 }
200 fragB = \relative c'' { a8. gis16 ees4 }
201 violin = \new Staff { \fragA \fragA \fragB \fragA }
209 However, you can also use these identifiers (also known as
210 variables, macros, or (user-defined) command) for tweaks:
212 @lilypond[quote,verbatim,ragged-right]
213 dolce = \markup{ \italic \bold dolce }
214 padText = { \once \override TextScript #'padding = #5.0 }
215 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
216 violin = \relative c'' {
218 c4._\dolce b8 a8 g a b |
220 c4.^"hi there!" d8 e' f g d |
221 c,4.\fthenp b8 c4 c-. |
228 \layout{ragged-right=##t}
232 These identifiers are obviously useful for saving
233 typing. But they're worth considering even if you
234 only use them once -- they reduce complexity. Let's
235 look at the previous example without any
236 identifiers. It's a lot harder to read, especially
240 violin = \relative c'' @{
242 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
243 \once \override TextScript #'padding = #5.0
244 c4.^"hi there!" d8 e' f g d |
245 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
246 \hspace #0.1 \dynamic p @} b8 c4 c-. |
251 So far we've seen static substitution -- when LilyPond
252 sees @code{\padText}, it replaces it with the stuff that
253 we've defined it to be (ie the stuff to the right of
256 LilyPond can handle non-static substitution, too (you
257 can think of these as functions).
259 @lilypond[quote,verbatim,ragged-right]
261 #(define-music-function (parser location padding) (number?)
263 \once \override TextScript #'padding = #$padding
271 c4^"piu mosso" fis a g
275 Using identifiers is also a good way to reduce work if the
276 LilyPond input syntax changes (see @ref{Updating old files}). If
277 you have a single definition (such as @code{\dolce}) for all your
278 files (see @ref{Style sheets}), then if the syntax changes, you
279 only need to update your single @code{\dolce} definition,
280 instead of making changes throughout every @code{.ly} file.
284 @section Style sheets
286 The output that LilyPond produces can be heavily modified; see
287 @ref{Tweaking output} for details. But what if you have many
288 files that you want to apply your tweaks to? Or what if you
289 simply want to separate your tweaks from the actual music? This
292 Let's look at an example. Don't worry if you don't understand
293 the parts with all the #(). This is explained in
294 @ref{Advanced tweaks with Scheme}.
296 @lilypond[quote,verbatim,ragged-right]
297 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
298 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
299 tempoMark = #(define-music-function (parser location markp) (string?)
301 \once \override Score . RehearsalMark #'self-alignment-X = #left
302 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
303 \mark \markup { \bold $markp }
308 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
309 \tempoMark "Poco piu mosso"
310 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
314 There are some problems with overlapping output; we'll fix those using
315 the techniques in @ref{Moving objects}. But let's also
316 do something about the @code{mpdolce} and @code{tempoMark}
317 definitions. They produce the output we desire, but we might want
318 to use them in another piece. We could simply copy-and-paste them
319 at the top of every file, but that's an annoyance. It also leaves
320 those definitions in our music files, and I personally find all
321 the #() somewhat ugly. Let's hide them in another file:
324 %%% save this to a file called "definitions.ly"
325 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
326 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
327 tempoMark = #(define-music-function (parser location markp) (string?)
329 \once \override Score . RehearsalMark #'self-alignment-X = #left
330 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
331 \mark \markup @{ \bold $markp @}
335 Now let's modify our music (let's save this file as @file{"music.ly"}).
337 @c We have to do this awkward example/lilypond-non-verbatim
338 @c because we can't do the \include stuff in the manual.
341 \include "definitions.ly"
345 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
346 \once \override Score.RehearsalMark #'padding = #2.0
347 \tempoMark "Poco piu mosso"
348 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
352 @lilypond[quote,ragged-right]
353 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
354 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
355 tempoMark = #(define-music-function (parser location markp) (string?)
357 \once \override Score . RehearsalMark #'self-alignment-X = #left
358 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
359 \mark \markup { \bold $markp }
364 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
365 \once \override Score.RehearsalMark #'padding = #2.0
366 \tempoMark "Poco piu mosso"
367 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
371 That looks better, but let's make a few changes. The glissando is hard
372 to see, so let's make it thicker and closer to the noteheads. Let's
373 put the metronome marking above the clef, instead of over the first
374 note. And finally, my composition professor hates "C" time signatures,
375 so we'd better make that "4/4" instead.
377 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
382 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
383 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
384 tempoMark = #(define-music-function (parser location markp) (string?)
386 \once \override Score . RehearsalMark #'self-alignment-X = #left
387 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
388 \mark \markup @{ \bold $markp @}
393 \override MetronomeMark #'extra-offset = #'(-9 . 0)
394 \override MetronomeMark #'padding = #'3
397 \override TimeSignature #'style = #'numbered
400 \override Glissando #'thickness = #3
401 \override Glissando #'gap = #0.1
406 @lilypond[quote,ragged-right]
407 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
408 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
409 tempoMark = #(define-music-function (parser location markp) (string?)
411 \once \override Score . RehearsalMark #'self-alignment-X = #left
412 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
413 \mark \markup { \bold $markp }
418 \override MetronomeMark #'extra-offset = #'(-9 . 0)
419 \override MetronomeMark #'padding = #'3
422 \override TimeSignature #'style = #'numbered
425 \override Glissando #'thickness = #3
426 \override Glissando #'gap = #0.1
432 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
433 \once \override Score.RehearsalMark #'padding = #2.0
434 \tempoMark "Poco piu mosso"
435 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
439 That looks nicer! But now suppose that I want to publish this
440 piece. My composition professor doesn't like "C" time
441 signatures, but I'm somewhat fond of them. Let's copy the
442 current @file{definitions.ly} to @file{web-publish.ly} and
443 modify that. Since this music is aimed at producing a pdf which
444 will be displayed on the screen, we'll also increase the
445 overall size of the output.
449 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
450 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
451 tempoMark = #(define-music-function (parser location markp) (string?)
453 \once \override Score . RehearsalMark #'self-alignment-X = #left
454 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
455 \mark \markup @{ \bold $markp @}
458 #(set-global-staff-size 23)
461 \override MetronomeMark #'extra-offset = #'(-9 . 0)
462 \override MetronomeMark #'padding = #'3
467 \override Glissando #'thickness = #3
468 \override Glissando #'gap = #0.1
473 @lilypond[quote,ragged-right]
474 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
475 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
476 tempoMark = #(define-music-function (parser location markp) (string?)
478 \once \override Score . RehearsalMark #'self-alignment-X = #left
479 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
480 \mark \markup { \bold $markp }
483 #(set-global-staff-size 23)
486 \override MetronomeMark #'extra-offset = #'(-9 . 0)
487 \override MetronomeMark #'padding = #'3
490 \override Glissando #'thickness = #3
491 \override Glissando #'gap = #0.1
497 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
498 \once \override Score.RehearsalMark #'padding = #2.0
499 \tempoMark "Poco piu mosso"
500 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
504 Now in our music, I simply replace
505 @code{\include "definitions.ly"} with
506 @code{\include "web-publish.ly"}. Of course, we could make this
507 even more convenient. We could make a @file{definitions.ly} file which
508 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
509 @file{web-publish.ly} file which contains only the @code{\layout}
510 section listed above, and a @file{university.ly} file which
511 contains only the tweaks to produce the output that my professor
512 prefers. The top of @file{music.ly} would then look like this:
515 \include "definitions.ly"
517 %%% Only uncomment one of these two lines!
518 \include "web-publish.ly"
519 %\include "university.ly"
522 This approach can be useful even if you are only producing
523 one set of parts. I use half a dozen different
524 ``style sheet'' files for my projects. I begin every music
525 file with @code{\include "../global.ly"}, which contains
530 #(ly:set-option 'point-and-click #f)
531 \include "../init/init-defs.ly"
532 \include "../init/init-layout.ly"
533 \include "../init/init-headers.ly"
534 \include "../init/init-paper.ly"