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.
12 @node Working on LilyPond projects
13 @chapter Working on LilyPond projects
15 This section explains how to solve or avoid certain common
16 problems. If you have programming experience, many of these
17 tips may seem obvious, but it is still advisable to read
22 * Suggestions for writing LilyPond input files::
23 * When things don't work::
28 @node Suggestions for writing LilyPond input files
29 @section Suggestions for writing LilyPond input files
31 Now you're ready to begin writing larger LilyPond input files --
32 not just the little examples in the tutorial, but whole pieces.
33 But how should you go about doing it?
35 As long as LilyPond can understand your input files and produce
36 the output that you want, it doesn't matter what your input files
37 look like. However, there are a few other things to consider when
38 writing LilyPond input files.
41 @item What if you make a mistake? The structure of a LilyPond
42 file can make certain errors easier (or harder) to find.
44 @item What if you want to share your input files with somebody
45 else? In fact, what if you want to alter your own input files in
46 a few years? Some LilyPond input files are understandable at
47 first glance; others may leave you scratching your head
50 @item What if you want to upgrade your LilyPond file for use
51 with a later version of LilyPond? The input syntax changes
52 occasionally as LilyPond improves. Most changes can be
53 done automatically with @code{convert-ly}, but some changes
54 might require manual assistance. LilyPond input files can be
55 structured in order to be easier (or harder) to update.
60 * General suggestions::
61 * Typesetting existing music::
63 * Saving typing with variables and functions::
68 @node General suggestions
69 @subsection General suggestions
71 Here are a few suggestions that can help you to avoid or fix
75 @item @strong{Include @code{\version} numbers in every file}. Note that all
76 templates contain @code{\version} information. We
77 highly recommend that you always include the @code{\version}, no matter
78 how small your file is. Speaking from personal experience, it's
79 quite frustrating to try to remember which version of LilyPond you were
80 using a few years ago. @command{convert-ly} requires you to declare
81 which version of LilyPond you used.
83 @item @strong{Include checks}: @ruser{Bar and bar number checks},
84 @ruser{Octave checks}. If you include checks every so often, then
85 if you make a mistake, you can pinpoint it quicker. How often is
86 @q{every so often}? It depends on the complexity of the music.
87 For very simple music, perhaps just once or twice. For very
88 complex music, perhaps every bar.
90 @item @strong{One bar per line of text}. If there is anything complicated,
92 itself or in the output you desire, it's often good to write only one bar
93 per line. Saving screen space by cramming eight bars per line just isn't
94 worth it if you have to @q{debug} your input files.
96 @item @strong{Comment your input files}. Use either bar numbers
98 references to musical themes (@q{second theme in violins,} @q{fourth
99 variation,} etc.). You may not need comments when you're writing the piece
100 for the first time, but if you want to go back to change something two or
101 three years later, or if you pass the source over to a friend, it will
103 challenging to determine your intentions or how your file is structured if
104 you didn't comment the file.
106 @item @strong{Indent your braces}. A lot of problems are caused by an
108 in the number of @code{@{} and @code{@}}.
110 @item @strong{Explicitly add durations} at the beginnings of sections
111 and variables. If you specify @code{c4 d e} at the beginning of a
112 phrase (instead of just @code{c d e}) you can save yourself some
113 problems if you rearrange your music later.
115 @item @strong{Separate tweaks} from music definitions. See
116 @ref{Saving typing with variables and functions}, and
122 @node Typesetting existing music
123 @subsection Typesetting existing music
125 If you are entering music from an existing score (i.e., typesetting a
126 piece of existing sheet music),
130 @item Enter one manuscript (the physical copy) system at a time (but still
131 only one bar per line of text), and
132 check each system when you finish it. You may use the
133 @code{showLastLength} or @code{showFirstLength} properties to speed up
134 processing -- see @ruser{Skipping corrected music}.
136 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
137 in the input file whenever the manuscript has a line break. This
138 makes it much easier to compare the LilyPond music to the original
139 music. When you are finished proofreading your score, you may
140 define @code{mBreak = @{ @}} to remove all those line breaks. This
141 will allow LilyPond to place line breaks wherever it feels are
144 @item When entering a part for a transposing instrument into a
145 variable, it is recommended that the notes are wrapped in
148 \transpose c natural-pitch @{...@}
150 (where @code{natural-pitch} is the open pitch of the instrument) so
151 that the music in the variable is effectively in C. You can transpose
152 it back again when the variable is used, if required, but you might
153 not want to (e.g., when printing a score in concert pitch,
154 converting a trombone part from treble to bass clef, etc.)
155 Mistakes in transpositions are less likely if all the music in
156 variables is at a consistent pitch.
158 Also, only ever transpose to/from C. That means that the only other
159 keys you will use are the natural pitches of the instruments - bes
160 for a B-flat trumpet, aes for an A-flat clarinet, etc.
166 @subsection Large projects
168 When working on a large project, having a clear structure to your
169 lilypond input files becomes vital.
173 @item @strong{Use an variable for each voice}, with a minimum of
174 structure inside the definition. The structure of the
175 @code{\score} section is the most likely thing to change;
176 the @code{violin} definition is extremely unlikely to change
177 in a new version of LilyPond.
180 violin = \relative c'' @{
193 @item @strong{Separate tweaks from music definitions}. This
194 point was made in previously, but for large
195 projects it is absolutely vital. We might need to change
196 the definition of @code{fthenp}, but then we only need
197 to do this once, and we can still avoid touching anything
198 inside @code{violin}.
202 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
203 violin = \relative c'' @{
211 @node Saving typing with variables and functions
212 @subsection Saving typing with variables and functions
217 By this point, you've seen this kind of thing:
219 @lilypond[quote,verbatim,ragged-right]
220 hornNotes = \relative c'' { c4 b dis c }
228 You may even realize that this could be useful in minimalist music:
230 @lilypond[quote,verbatim,ragged-right]
231 fragmentA = \relative c'' { a4 a8. b16 }
232 fragmentB = \relative c'' { a8. gis16 ees4 }
233 violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
241 However, you can also use these variables (also known as
242 variables, macros, or (user-defined) command) for tweaks:
244 @lilypond[quote,verbatim,ragged-right]
245 dolce = \markup{ \italic \bold dolce }
246 padText = { \once \override TextScript #'padding = #5.0 }
247 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
248 violin = \relative c'' {
250 c4._\dolce b8 a8 g a b |
252 c4.^"hi there!" d8 e' f g d |
253 c,4.\fthenp b8 c4 c-. |
260 \layout{ragged-right=##t}
264 These variables are obviously useful for saving
265 typing. But they're worth considering even if you
266 only use them once -- they reduce complexity. Let's
267 look at the previous example without any
268 variables. It's a lot harder to read, especially
272 violin = \relative c'' @{
274 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
275 \once \override TextScript #'padding = #5.0
276 c4.^"hi there!" d8 e' f g d |
277 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
278 \hspace #0.1 \dynamic p @} b8 c4 c-. |
283 @c TODO Replace the following with a better example -td
284 @c Skylining handles this correctly without padText
286 So far we've seen static substitution -- when LilyPond
287 sees @code{\padText}, it replaces it with the stuff that
288 we've defined it to be (ie the stuff to the right of
291 LilyPond can handle non-static substitution, too (you
292 can think of these as functions).
294 @lilypond[quote,verbatim,ragged-right]
296 #(define-music-function (parser location padding) (number?)
298 \once \override TextScript #'padding = #$padding
306 c4^"piu mosso" fis a g
310 Using variables is also a good way to reduce work if the
311 LilyPond input syntax changes (see @ref{Updating old input files}). If
312 you have a single definition (such as @code{\dolce}) for all your
313 input files (see @ref{Style sheets}), then if the syntax changes, you
314 only need to update your single @code{\dolce} definition,
315 instead of making changes throughout every @code{.ly} file.
319 @subsection Style sheets
321 The output that LilyPond produces can be heavily modified; see
322 @ref{Tweaking output}, for details. But what if you have many
323 input files that you want to apply your tweaks to? Or what if you
324 simply want to separate your tweaks from the actual music? This
327 Let's look at an example. Don't worry if you don't understand
328 the parts with all the @code{#()}. This is explained in
329 @ref{Advanced tweaks with Scheme}.
331 @lilypond[quote,verbatim,ragged-right]
332 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
333 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
334 tempoMark = #(define-music-function (parser location markp) (string?)
336 \once \override Score . RehearsalMark #'self-alignment-X = #left
337 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
338 \mark \markup { \bold $markp }
343 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
344 \tempoMark "Poco piu mosso"
345 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
349 There are some problems with overlapping output; we'll fix those using
350 the techniques in @ref{Moving objects}. But let's also
351 do something about the @code{mpdolce} and @code{tempoMark}
352 definitions. They produce the output we desire, but we might want
353 to use them in another piece. We could simply copy-and-paste them
354 at the top of every file, but that's an annoyance. It also leaves
355 those definitions in our input files, and I personally find all
356 the @code{#()} somewhat ugly. Let's hide them in another file:
359 %%% save this to a file called "definitions.ly"
360 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
361 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
362 tempoMark = #(define-music-function (parser location markp) (string?)
364 \once \override Score . RehearsalMark #'self-alignment-X = #left
365 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
366 \mark \markup @{ \bold $markp @}
370 Now let's modify our music (let's save this file as @file{"music.ly"}).
372 @c We have to do this awkward example/lilypond-non-verbatim
373 @c because we can't do the \include stuff in the manual.
376 \include "definitions.ly"
380 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
381 \once \override Score.RehearsalMark #'padding = #2.0
382 \tempoMark "Poco piu mosso"
383 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
387 @lilypond[quote,ragged-right]
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 #'extra-spacing-width = #'(+inf.0 . -inf.0)
394 \mark \markup { \bold $markp }
399 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
400 \once \override Score.RehearsalMark #'padding = #2.0
401 \tempoMark "Poco piu mosso"
402 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
406 That looks better, but let's make a few changes. The glissando is hard
407 to see, so let's make it thicker and closer to the note heads. Let's
408 put the metronome marking above the clef, instead of over the first
409 note. And finally, my composition professor hates @q{C} time signatures,
410 so we'd better make that @q{4/4} instead.
412 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
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
441 @lilypond[quote,ragged-right]
442 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
443 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
444 tempoMark = #(define-music-function (parser location markp) (string?)
446 \once \override Score . RehearsalMark #'self-alignment-X = #left
447 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
448 \mark \markup { \bold $markp }
453 \override MetronomeMark #'extra-offset = #'(-9 . 0)
454 \override MetronomeMark #'padding = #'3
457 \override TimeSignature #'style = #'numbered
460 \override Glissando #'thickness = #3
461 \override Glissando #'gap = #0.1
467 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
468 \once \override Score.RehearsalMark #'padding = #2.0
469 \tempoMark "Poco piu mosso"
470 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
474 That looks nicer! But now suppose that I want to publish this
475 piece. My composition professor doesn't like @q{C} time
476 signatures, but I'm somewhat fond of them. Let's copy the
477 current @file{definitions.ly} to @file{web-publish.ly} and
478 modify that. Since this music is aimed at producing a pdf which
479 will be displayed on the screen, we'll also increase the
480 overall size of the output.
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
502 \override Glissando #'thickness = #3
503 \override Glissando #'gap = #0.1
508 @lilypond[quote,ragged-right]
509 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
510 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
511 tempoMark = #(define-music-function (parser location markp) (string?)
513 \once \override Score . RehearsalMark #'self-alignment-X = #left
514 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
515 \mark \markup { \bold $markp }
518 #(set-global-staff-size 23)
521 \override MetronomeMark #'extra-offset = #'(-9 . 0)
522 \override MetronomeMark #'padding = #'3
525 \override Glissando #'thickness = #3
526 \override Glissando #'gap = #0.1
532 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
533 \once \override Score.RehearsalMark #'padding = #2.0
534 \tempoMark "Poco piu mosso"
535 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
539 Now in our music, I simply replace
540 @code{\include "definitions.ly"} with
541 @code{\include "web-publish.ly"}. Of course, we could make this
542 even more convenient. We could make a @file{definitions.ly} file which
543 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
544 @file{web-publish.ly} file which contains only the @code{\layout}
545 section listed above, and a @file{university.ly} file which
546 contains only the tweaks to produce the output that my professor
547 prefers. The top of @file{music.ly} would then look like this:
550 \include "definitions.ly"
552 %%% Only uncomment one of these two lines!
553 \include "web-publish.ly"
554 %\include "university.ly"
557 This approach can be useful even if you are only producing
558 one set of parts. I use half a dozen different
559 @q{style sheet} files for my projects. I begin every music
560 file with @code{\include "../global.ly"}, which contains
564 \version @w{"@version{}"}
565 #(ly:set-option 'point-and-click #f)
566 \include "../init/init-defs.ly"
567 \include "../init/init-layout.ly"
568 \include "../init/init-headers.ly"
569 \include "../init/init-paper.ly"
573 @node When things don't work
574 @section When things don't work
577 * Updating old input files::
578 * Troubleshooting (taking it all apart)::
582 @node Updating old input files
583 @subsection Updating old input files
585 The LilyPond input syntax occasionally changes. As LilyPond itself
586 improves, the syntax (input language) is modified accordingly. Sometimes
587 these changes are made to make the input easier to read and write or
588 sometimes the changes are made to accommodate new features of LilyPond.
590 LilyPond comes with a file that makes this updating easier:
591 @code{convert-ly}. For details about how to run this program, see
592 @rprogram{Updating files with convert-ly}.
594 Unfortunately, @code{convert-ly} cannot handle all input changes. It
595 takes care of simple search-and-replace changes (such as @code{raggedright}
596 becoming @code{ragged-right}), but some changes are too
597 complicated. The syntax changes that @code{convert-ly} cannot handle
598 are listed in @rprogram{Updating files with convert-ly}.
600 For example, in LilyPond 2.4 and earlier, accents and non-English
601 letters were entered using LaTeX -- for example,
602 @code{No\"el} (this would print the French word for
603 @q{Christmas}). In LilyPond 2.6 and above, the special
604 @code{ë} must be entered directly into the LilyPond file as an
605 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
606 special characters into UTF-8 characters; you must manually update
607 your old LilyPond input files.
610 @node Troubleshooting (taking it all apart)
611 @subsection Troubleshooting (taking it all apart)
613 Sooner or later, you will write a file that LilyPond cannot
614 compile. The messages that LilyPond gives may help
615 you find the error, but in many cases you need to do some
616 investigation to determine the source of the problem.
618 The most powerful tools for this purpose are the
619 single line comment (indicated by @code{%}) and the block
620 comment (indicated by @code{%@{ ... %@}}). If you don't
621 know where a problem is, start commenting out huge portions
622 of your input file. After you comment out a section, try
623 compiling the file again. If it works, then the problem
624 must exist in the portion you just commented. If it doesn't
625 work, then keep on commenting out material until you have
626 something that works.
628 In an extreme case, you might end up with only
642 (in other words, a file without any music)
644 If that happens, don't give up. Uncomment a bit -- say,
645 the bass part -- and see if it works. If it doesn't work,
646 then comment out all of the bass music (but leave
647 @code{\bass} in the @code{\score} uncommented.
650 bass = \relative c' @{
658 Now start slowly uncommenting more and more of the
659 @code{bass} part until you find the problem line.
661 Another very useful debugging technique is constructing
662 @ref{Minimal examples}.
665 @node Minimal examples
666 @subsection Minimal examples
668 A minimal example is an example which is as small as possible. These
669 examples are much easier to understand than long examples. Minimal
670 examples are used for
674 @item Sending a help request to mailing lists
675 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
676 LilyPond Snippet Repository}
679 To construct an example which is as small as possible, the rule is
680 quite simple: remove anything which is not necessary. When trying to
681 remove unnecessary parts of a file, it is a very good idea to comment
682 out lines instead of deleting them. That way, if you discover that you
683 actually @emph{do} need some lines, you can uncomment them, instead of
684 typing them in from scratch.
686 There are two exceptions to the @qq{as small as possible} rule:
689 @item Include the @code{\version} number.
690 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
694 The whole point of a minimal example is to make it easy to read:
697 @item Avoid using complicated notes, keys, or time signatures, unless you
698 wish to demonstrate something is about the behavior of those items.
699 @item Do not use @code{\override} commands unless that is the point of the
705 @node Scores and parts
706 @section Scores and parts
708 TODO: this is really old stuff from the really old tutorial.
709 Rewrite, fix, etc. Or maybe delete entirely. -gp
710 Include section on tags -td
711 and then move to section 5. Working ... -td
713 In orchestral music, all notes are printed twice. Once in a part for
714 the musicians, and once in a full score for the conductor. Variables can
715 be used to avoid double work. The music is entered once, and stored in
716 a variable. The contents of that variable is then used to generate
717 both the part and the full score.
719 It is convenient to define the notes in a special file. For example,
720 suppose that the file @file{horn-music.ly} contains the following part
721 of a horn/@/bassoon duo
724 hornNotes = \relative c @{
731 Then, an individual part is made by putting the following in a file
734 \include "horn-music.ly"
736 instrument = "Horn in F"
740 \transpose f c' \hornNotes
747 \include "horn-music.ly"
751 substitutes the contents of @file{horn-music.ly} at this position in
752 the file, so @code{hornNotes} is defined afterwards. The command
753 @code{\transpose f@tie{}c'} indicates that the argument, being
754 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
755 @code{f} is denoted by notated @code{c'}, which corresponds with the
756 tuning of a normal French Horn in@tie{}F. The transposition can be seen
757 in the following output
759 @lilypond[quote,ragged-right]
760 \transpose f c' \relative c {
766 In ensemble pieces, one of the voices often does not play for many
767 measures. This is denoted by a special rest, the multi-measure
768 rest. It is entered with a capital @code{R} followed by a duration
769 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
770 etc.). By multiplying the
771 duration, longer rests can be constructed. For example, this rest
772 takes 3@tie{}measures in 2/4 time
778 When printing the part, multi-rests
779 must be condensed. This is done by setting a run-time variable
782 \set Score.skipBars = ##t
786 This command sets the property @code{skipBars} in the
787 @code{Score} context to true (@code{##t}). Prepending the rest and
788 this option to the music above, leads to the following result
790 @lilypond[quote,ragged-right]
791 \transpose f c' \relative c {
793 \set Score.skipBars = ##t
800 The score is made by combining all of the music together. Assuming
801 that the other voice is in @code{bassoonNotes} in the file
802 @file{bassoon-music.ly}, a score is made with
805 \include "bassoon-music.ly"
806 \include "horn-music.ly"
809 \new Staff \hornNotes
810 \new Staff \bassoonNotes
817 @lilypond[quote,ragged-right]
825 r4 d,8 f | gis4 c | b bes |
826 a8 e f4 | g d | gis f