1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
10 @node Working on LilyPond projects
11 @chapter Working on LilyPond projects
13 This section explains how to solve or avoid certain common
14 problems. If you have programming experience, many of these
15 tips may seem obvious, but it is still advisable to read
20 * Suggestions for writing LilyPond files::
21 * When things don't work::
26 @node Suggestions for writing LilyPond files
27 @section Suggestions for writing LilyPond files
29 Now you're ready to begin writing larger LilyPond files -- not just the
30 little examples in the tutorial, but whole pieces. But how should you
33 As long as LilyPond can understand your files and produces the output
34 that you want, it doesn't matter what your files look like. However,
35 there are a few other things to consider when writing LilyPond files.
38 @item What if you make a mistake? The structure of a LilyPond
39 file can make certain errors easier (or harder) to find.
41 @item What if you want to share your files with somebody
42 else? In fact, what if you want to alter your own files in
43 a few years? Some LilyPond files are understandable at
44 first glance; other files may leave you scratching your head
47 @item What if you want to upgrade your LilyPond file for use
48 with a later version of LilyPond? The input syntax changes
49 occasionally as LilyPond improves. Most changes can be
50 done automatically with @code{convert-ly}, but some changes
51 might require manual assistance. LilyPond files can be
52 structured in order to be easier (or harder) to update.
56 * General suggestions::
57 * Typesetting existing music::
59 * Saving typing with variables and functions::
64 @node General suggestions
65 @subsection General suggestions
67 Here are a few suggestions that can help you to avoid or fix
71 @item @strong{Include @code{\version} numbers in every file}. Note that all
72 templates contain @code{\version} information. We
73 highly recommend that you always include the @code{\version}, no matter
74 how small your file is. Speaking from personal experience, it's
75 quite frustrating to try to remember which version of LilyPond you were
76 using a few years ago. @command{convert-ly} requires you to declare
77 which version of LilyPond you used.
79 @item @strong{Include checks}: @ruser{Bar and barnumber checks},
80 @ruser{Octave check}. If you include checks every so often, then
81 if you make a mistake, you can pinpoint it quicker. How often is
82 @q{every so often}? It depends on the complexity of the music.
83 For very simple music, perhaps just once or twice. For very
84 complex music, perhaps every bar.
86 @item @strong{One bar per line of text}. If there is anything complicated,
88 itself or in the output you desire, it's often good to write only one bar
89 per line. Saving screen space by cramming eight bars per line just isn't
90 worth it if you have to @q{debug} your files.
92 @item @strong{Comment your files}. Use either bar numbers (every so often)
94 references to musical themes (@q{second theme in violins,} @q{fourth
95 variation,} etc.). You may not need comments when you're writing the piece
96 for the first time, but if you want to go back to change something two or
97 three years later, or if you pass the source over to a friend, it will
99 challenging to determine your intentions or how your file is structured if
100 you didn't comment the file.
102 @item @strong{Indent your braces}. A lot of problems are caused by an
104 in the number of @code{@{} and @code{@}}.
106 @item @strong{Explicitly add durations} at the beginnings of sections
107 and variables. If you specify @code{c4 d e} at the beginning of a
108 phrase (instead of just @code{c d e}) you can save yourself some
109 problems if you rearrange your music later.
111 @item @strong{Separate tweaks} from music definitions. See
112 @ref{Saving typing with variables and functions}, and
118 @node Typesetting existing music
119 @subsection Typesetting existing music
121 If you are entering music from an existing score (i.e., typesetting a
122 piece of existing sheet music),
126 @item Enter one manuscript (the physical copy) system at a time (but still
127 only one bar per line of text), and
128 check each system when you finish it. You may use the
129 @code{showLastLength} command to speed up processing -- see
130 @ruser{Skipping corrected music}.
132 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
133 in the input file whenever the manuscript has a line break. This
134 makes it much easier to compare the LilyPond music to the original
135 music. When you are finished proofreading your score, you may
136 define @code{mBreak = @{ @}} to remove all those line breaks. This
137 will allow LilyPond to place line breaks wherever it feels are
144 @subsection Large projects
146 When working on a large project, having a clear structure to your
147 lilypond files becomes vital.
151 @item @strong{Use an variable for each voice}, with a minimum of
152 structure inside the definition. The structure of the
153 @code{\score} section is the most likely thing to change;
154 the @code{violin} definition is extremely unlikely to change
155 in a new version of LilyPond.
158 violin = \relative c'' @{
171 @item @strong{Separate tweaks from music definitions}. This
172 point was made in previously, but for large
173 projects it is absolutely vital. We might need to change
174 the definition of @code{fthenp}, but then we only need
175 to do this once, and we can still avoid touching anything
176 inside @code{violin}.
180 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
181 violin = \relative c'' @{
189 @node Saving typing with variables and functions
190 @subsection Saving typing with variables and functions
195 By this point, you've seen this kind of thing:
197 @lilypond[quote,verbatim,ragged-right]
198 hornNotes = \relative c'' { c4 b dis c }
206 You may even realize that this could be useful in minimalist music:
208 @lilypond[quote,verbatim,ragged-right]
209 fragA = \relative c'' { a4 a8. b16 }
210 fragB = \relative c'' { a8. gis16 ees4 }
211 violin = \new Staff { \fragA \fragA \fragB \fragA }
219 However, you can also use these variables (also known as
220 variables, macros, or (user-defined) command) for tweaks:
222 @lilypond[quote,verbatim,ragged-right]
223 dolce = \markup{ \italic \bold dolce }
224 padText = { \once \override TextScript #'padding = #5.0 }
225 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
226 violin = \relative c'' {
228 c4._\dolce b8 a8 g a b |
230 c4.^"hi there!" d8 e' f g d |
231 c,4.\fthenp b8 c4 c-. |
238 \layout{ragged-right=##t}
242 These variables are obviously useful for saving
243 typing. But they're worth considering even if you
244 only use them once -- they reduce complexity. Let's
245 look at the previous example without any
246 variables. It's a lot harder to read, especially
250 violin = \relative c'' @{
252 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
253 \once \override TextScript #'padding = #5.0
254 c4.^"hi there!" d8 e' f g d |
255 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
256 \hspace #0.1 \dynamic p @} b8 c4 c-. |
261 So far we've seen static substitution -- when LilyPond
262 sees @code{\padText}, it replaces it with the stuff that
263 we've defined it to be (ie the stuff to the right of
266 LilyPond can handle non-static substitution, too (you
267 can think of these as functions).
269 @lilypond[quote,verbatim,ragged-right]
271 #(define-music-function (parser location padding) (number?)
273 \once \override TextScript #'padding = #$padding
281 c4^"piu mosso" fis a g
285 Using variables is also a good way to reduce work if the
286 LilyPond input syntax changes (see @ref{Updating old files}). If
287 you have a single definition (such as @code{\dolce}) for all your
288 files (see @ref{Style sheets}), then if the syntax changes, you
289 only need to update your single @code{\dolce} definition,
290 instead of making changes throughout every @code{.ly} file.
294 @subsection Style sheets
296 The output that LilyPond produces can be heavily modified; see
297 @ref{Tweaking output}, for details. But what if you have many
298 files that you want to apply your tweaks to? Or what if you
299 simply want to separate your tweaks from the actual music? This
302 Let's look at an example. Don't worry if you don't understand
303 the parts with all the @code{#()}. This is explained in
304 @ref{Advanced tweaks with Scheme}.
306 @lilypond[quote,verbatim,ragged-right]
307 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
308 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
309 tempoMark = #(define-music-function (parser location markp) (string?)
311 \once \override Score . RehearsalMark #'self-alignment-X = #left
312 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
313 \mark \markup { \bold $markp }
318 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
319 \tempoMark "Poco piu mosso"
320 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
324 There are some problems with overlapping output; we'll fix those using
325 the techniques in @ref{Moving objects}. But let's also
326 do something about the @code{mpdolce} and @code{tempoMark}
327 definitions. They produce the output we desire, but we might want
328 to use them in another piece. We could simply copy-and-paste them
329 at the top of every file, but that's an annoyance. It also leaves
330 those definitions in our music files, and I personally find all
331 the @code{#()} somewhat ugly. Let's hide them in another file:
334 %%% save this to a file called "definitions.ly"
335 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
336 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
337 tempoMark = #(define-music-function (parser location markp) (string?)
339 \once \override Score . RehearsalMark #'self-alignment-X = #left
340 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
341 \mark \markup @{ \bold $markp @}
345 Now let's modify our music (let's save this file as @file{"music.ly"}).
347 @c We have to do this awkward example/lilypond-non-verbatim
348 @c because we can't do the \include stuff in the manual.
351 \include "definitions.ly"
355 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
356 \once \override Score.RehearsalMark #'padding = #2.0
357 \tempoMark "Poco piu mosso"
358 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
362 @lilypond[quote,ragged-right]
363 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
364 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
365 tempoMark = #(define-music-function (parser location markp) (string?)
367 \once \override Score . RehearsalMark #'self-alignment-X = #left
368 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
369 \mark \markup { \bold $markp }
374 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
375 \once \override Score.RehearsalMark #'padding = #2.0
376 \tempoMark "Poco piu mosso"
377 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
381 That looks better, but let's make a few changes. The glissando is hard
382 to see, so let's make it thicker and closer to the note heads. Let's
383 put the metronome marking above the clef, instead of over the first
384 note. And finally, my composition professor hates @q{C} time signatures,
385 so we'd better make that @q{4/4} instead.
387 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
392 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
393 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
394 tempoMark = #(define-music-function (parser location markp) (string?)
396 \once \override Score . RehearsalMark #'self-alignment-X = #left
397 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
398 \mark \markup @{ \bold $markp @}
403 \override MetronomeMark #'extra-offset = #'(-9 . 0)
404 \override MetronomeMark #'padding = #'3
407 \override TimeSignature #'style = #'numbered
410 \override Glissando #'thickness = #3
411 \override Glissando #'gap = #0.1
416 @lilypond[quote,ragged-right]
417 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
418 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
419 tempoMark = #(define-music-function (parser location markp) (string?)
421 \once \override Score . RehearsalMark #'self-alignment-X = #left
422 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
423 \mark \markup { \bold $markp }
428 \override MetronomeMark #'extra-offset = #'(-9 . 0)
429 \override MetronomeMark #'padding = #'3
432 \override TimeSignature #'style = #'numbered
435 \override Glissando #'thickness = #3
436 \override Glissando #'gap = #0.1
442 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
443 \once \override Score.RehearsalMark #'padding = #2.0
444 \tempoMark "Poco piu mosso"
445 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
449 That looks nicer! But now suppose that I want to publish this
450 piece. My composition professor doesn't like @q{C} time
451 signatures, but I'm somewhat fond of them. Let's copy the
452 current @file{definitions.ly} to @file{web-publish.ly} and
453 modify that. Since this music is aimed at producing a pdf which
454 will be displayed on the screen, we'll also increase the
455 overall size of the output.
459 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
460 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
461 tempoMark = #(define-music-function (parser location markp) (string?)
463 \once \override Score . RehearsalMark #'self-alignment-X = #left
464 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
465 \mark \markup @{ \bold $markp @}
468 #(set-global-staff-size 23)
471 \override MetronomeMark #'extra-offset = #'(-9 . 0)
472 \override MetronomeMark #'padding = #'3
477 \override Glissando #'thickness = #3
478 \override Glissando #'gap = #0.1
483 @lilypond[quote,ragged-right]
484 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
485 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
486 tempoMark = #(define-music-function (parser location markp) (string?)
488 \once \override Score . RehearsalMark #'self-alignment-X = #left
489 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
490 \mark \markup { \bold $markp }
493 #(set-global-staff-size 23)
496 \override MetronomeMark #'extra-offset = #'(-9 . 0)
497 \override MetronomeMark #'padding = #'3
500 \override Glissando #'thickness = #3
501 \override Glissando #'gap = #0.1
507 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
508 \once \override Score.RehearsalMark #'padding = #2.0
509 \tempoMark "Poco piu mosso"
510 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
514 Now in our music, I simply replace
515 @code{\include "definitions.ly"} with
516 @code{\include "web-publish.ly"}. Of course, we could make this
517 even more convenient. We could make a @file{definitions.ly} file which
518 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
519 @file{web-publish.ly} file which contains only the @code{\layout}
520 section listed above, and a @file{university.ly} file which
521 contains only the tweaks to produce the output that my professor
522 prefers. The top of @file{music.ly} would then look like this:
525 \include "definitions.ly"
527 %%% Only uncomment one of these two lines!
528 \include "web-publish.ly"
529 %\include "university.ly"
532 This approach can be useful even if you are only producing
533 one set of parts. I use half a dozen different
534 @q{style sheet} files for my projects. I begin every music
535 file with @code{\include "../global.ly"}, which contains
539 \version @w{"@version{}"}
540 #(ly:set-option 'point-and-click #f)
541 \include "../init/init-defs.ly"
542 \include "../init/init-layout.ly"
543 \include "../init/init-headers.ly"
544 \include "../init/init-paper.ly"
548 @node When things don't work
549 @section When things don't work
552 * Updating old files::
553 * Troubleshooting (taking it all apart)::
557 @node Updating old files
558 @subsection Updating old files
560 The LilyPond input syntax occasionally changes. As LilyPond itself
561 improves, the syntax (input language) is modified accordingly. Sometimes
562 these changes are made to make the input easier to read and write or
563 sometimes the changes are made to accommodate new features of LilyPond.
565 LilyPond comes with a file that makes this updating easier:
566 @code{convert-ly}. For details about how to run this program, see
567 @rprogram{Updating files with convert-ly}.
569 Unfortunately, @code{convert-ly} cannot handle all input changes. It
570 takes care of simple search-and-replace changes (such as @code{raggedright}
571 becoming @code{ragged-right}), but some changes are too
572 complicated. The syntax changes that @code{convert-ly} cannot handle
573 are listed in @rprogram{Updating files with convert-ly}.
575 For example, in LilyPond 2.4 and earlier, accents and non-English
576 letters were entered using LaTeX -- for example,
577 @code{No\"el} (this would print the French word for
578 @q{Christmas}). In LilyPond 2.6 and above, the special
579 @code{ë} must be entered directly into the LilyPond file as an
580 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
581 special characters into UTF-8 characters; you must manually update
582 your old LilyPond files.
585 @node Troubleshooting (taking it all apart)
586 @subsection Troubleshooting (taking it all apart)
588 Sooner or later, you will write a file that LilyPond cannot
589 compile. The messages that LilyPond gives may help
590 you find the error, but in many cases you need to do some
591 investigation to determine the source of the problem.
593 The most powerful tools for this purpose are the
594 single line comment (indicated by @code{%}) and the block
595 comment (indicated by @code{%@{ ... %@}}). If you don't
596 know where a problem is, start commenting out huge portions
597 of your input file. After you comment out a section, try
598 compiling the file again. If it works, then the problem
599 must exist in the portion you just commented. If it doesn't
600 work, then keep on commenting out material until you have
601 something that works.
603 In an extreme case, you might end up with only
617 (in other words, a file without any music)
619 If that happens, don't give up. Uncomment a bit -- say,
620 the bass part -- and see if it works. If it doesn't work,
621 then comment out all of the bass music (but leave
622 @code{\bass} in the @code{\score} uncommented.
625 bass = \relative c' @{
633 Now start slowly uncommenting more and more of the
634 @code{bass} part until you find the problem line.
636 Another very useful debugging technique is constructing
637 @ref{Minimal examples}.
640 @node Minimal examples
641 @subsection Minimal examples
643 A minimal example is an example which is as small as possible. These
644 examples are much easier to understand than long examples. Minimal
645 examples are used for
649 @item Sending a help request to mailing lists
650 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
651 LilyPond Snippet Repository}
654 To construct an example which is as small as possible, the rule is
655 quite simple: remove anything which is not necessary. When trying to
656 remove unnecessary parts of a file, it is a very good idea to comment
657 out lines instead of deleting them. That way, if you discover that you
658 actually @emph{do} need some lines, you can uncomment them, instead of
659 typing them in from scratch.
661 There are two exceptions to the @qq{as small as possible} rule:
664 @item Include the @code{\version} number.
665 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
669 The whole point of a minimal example is to make it easy to read:
672 @item Avoid using complicated notes, keys, or time signatures, unless you
673 wish to demonstrate something is about the behavior of those items.
674 @item Do not use @code{\override} commands unless that is the point of the
680 @node Scores and parts
681 @section Scores and parts
683 TODO: this is really old stuff from the really old tutorial.
684 Rewrite, fix, etc. Or maybe delete entirely. -gp
685 Include section on tags -td
686 and then move to section 5. Working ... -td
688 In orchestral music, all notes are printed twice. Once in a part for
689 the musicians, and once in a full score for the conductor. Variables can
690 be used to avoid double work. The music is entered once, and stored in
691 a variable. The contents of that variable is then used to generate
692 both the part and the full score.
694 It is convenient to define the notes in a special file. For example,
695 suppose that the file @file{horn-music.ly} contains the following part
696 of a horn/@/bassoon duo
699 hornNotes = \relative c @{
706 Then, an individual part is made by putting the following in a file
709 \include "horn-music.ly"
711 instrument = "Horn in F"
715 \transpose f c' \hornNotes
722 \include "horn-music.ly"
726 substitutes the contents of @file{horn-music.ly} at this position in
727 the file, so @code{hornNotes} is defined afterwards. The command
728 @code{\transpose f@tie{}c'} indicates that the argument, being
729 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
730 @code{f} is denoted by notated @code{c'}, which corresponds with the
731 tuning of a normal French Horn in@tie{}F. The transposition can be seen
732 in the following output
734 @lilypond[quote,ragged-right]
735 \transpose f c' \relative c {
741 In ensemble pieces, one of the voices often does not play for many
742 measures. This is denoted by a special rest, the multi-measure
743 rest. It is entered with a capital @code{R} followed by a duration
744 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
745 etc.). By multiplying the
746 duration, longer rests can be constructed. For example, this rest
747 takes 3@tie{}measures in 2/4 time
753 When printing the part, multi-rests
754 must be condensed. This is done by setting a run-time variable
757 \set Score.skipBars = ##t
761 This command sets the property @code{skipBars} in the
762 @code{Score} context to true (@code{##t}). Prepending the rest and
763 this option to the music above, leads to the following result
765 @lilypond[quote,ragged-right]
766 \transpose f c' \relative c {
768 \set Score.skipBars = ##t
775 The score is made by combining all of the music together. Assuming
776 that the other voice is in @code{bassoonNotes} in the file
777 @file{bassoon-music.ly}, a score is made with
780 \include "bassoon-music.ly"
781 \include "horn-music.ly"
784 \new Staff \hornNotes
785 \new Staff \bassoonNotes
792 @lilypond[quote,ragged-right]
800 r4 d,8 f | gis4 c | b bes |
801 a8 e f4 | g d | gis f