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.
59 * General suggestions::
60 * Typesetting existing music::
62 * Saving typing with variables and functions::
67 @node General suggestions
68 @subsection General suggestions
70 Here are a few suggestions that can help you to avoid or fix
74 @item @strong{Include @code{\version} numbers in every file}. Note that all
75 templates contain @code{\version} information. We
76 highly recommend that you always include the @code{\version}, no matter
77 how small your file is. Speaking from personal experience, it's
78 quite frustrating to try to remember which version of LilyPond you were
79 using a few years ago. @command{convert-ly} requires you to declare
80 which version of LilyPond you used.
82 @item @strong{Include checks}: @ruser{Bar and bar number checks},
83 @ruser{Octave checks}. If you include checks every so often, then
84 if you make a mistake, you can pinpoint it quicker. How often is
85 @q{every so often}? It depends on the complexity of the music.
86 For very simple music, perhaps just once or twice. For very
87 complex music, perhaps every bar.
89 @item @strong{One bar per line of text}. If there is anything complicated,
91 itself or in the output you desire, it's often good to write only one bar
92 per line. Saving screen space by cramming eight bars per line just isn't
93 worth it if you have to @q{debug} your input files.
95 @item @strong{Comment your input files}. Use either bar numbers
97 references to musical themes (@q{second theme in violins,} @q{fourth
98 variation,} etc.). You may not need comments when you're writing the piece
99 for the first time, but if you want to go back to change something two or
100 three years later, or if you pass the source over to a friend, it will
102 challenging to determine your intentions or how your file is structured if
103 you didn't comment the file.
105 @item @strong{Indent your braces}. A lot of problems are caused by an
107 in the number of @code{@{} and @code{@}}.
109 @item @strong{Explicitly add durations} at the beginnings of sections
110 and variables. If you specify @code{c4 d e} at the beginning of a
111 phrase (instead of just @code{c d e}) you can save yourself some
112 problems if you rearrange your music later.
114 @item @strong{Separate tweaks} from music definitions. See
115 @ref{Saving typing with variables and functions}, and
121 @node Typesetting existing music
122 @subsection Typesetting existing music
124 If you are entering music from an existing score (i.e., typesetting a
125 piece of existing sheet music),
129 @item Enter one manuscript (the physical copy) system at a time (but still
130 only one bar per line of text), and
131 check each system when you finish it. You may use the
132 @code{showLastLength} command to speed up processing -- see
133 @ruser{Skipping corrected music}.
135 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
136 in the input file whenever the manuscript has a line break. This
137 makes it much easier to compare the LilyPond music to the original
138 music. When you are finished proofreading your score, you may
139 define @code{mBreak = @{ @}} to remove all those line breaks. This
140 will allow LilyPond to place line breaks wherever it feels are
147 @subsection Large projects
149 When working on a large project, having a clear structure to your
150 lilypond input files becomes vital.
154 @item @strong{Use an variable for each voice}, with a minimum of
155 structure inside the definition. The structure of the
156 @code{\score} section is the most likely thing to change;
157 the @code{violin} definition is extremely unlikely to change
158 in a new version of LilyPond.
161 violin = \relative c'' @{
174 @item @strong{Separate tweaks from music definitions}. This
175 point was made in previously, but for large
176 projects it is absolutely vital. We might need to change
177 the definition of @code{fthenp}, but then we only need
178 to do this once, and we can still avoid touching anything
179 inside @code{violin}.
183 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
184 violin = \relative c'' @{
192 @node Saving typing with variables and functions
193 @subsection Saving typing with variables and functions
198 By this point, you've seen this kind of thing:
200 @lilypond[quote,verbatim,ragged-right]
201 hornNotes = \relative c'' { c4 b dis c }
209 You may even realize that this could be useful in minimalist music:
211 @lilypond[quote,verbatim,ragged-right]
212 fragmentA = \relative c'' { a4 a8. b16 }
213 fragmentB = \relative c'' { a8. gis16 ees4 }
214 violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
222 However, you can also use these variables (also known as
223 variables, macros, or (user-defined) command) for tweaks:
225 @lilypond[quote,verbatim,ragged-right]
226 dolce = \markup{ \italic \bold dolce }
227 padText = { \once \override TextScript #'padding = #5.0 }
228 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
229 violin = \relative c'' {
231 c4._\dolce b8 a8 g a b |
233 c4.^"hi there!" d8 e' f g d |
234 c,4.\fthenp b8 c4 c-. |
241 \layout{ragged-right=##t}
245 These variables are obviously useful for saving
246 typing. But they're worth considering even if you
247 only use them once -- they reduce complexity. Let's
248 look at the previous example without any
249 variables. It's a lot harder to read, especially
253 violin = \relative c'' @{
255 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
256 \once \override TextScript #'padding = #5.0
257 c4.^"hi there!" d8 e' f g d |
258 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
259 \hspace #0.1 \dynamic p @} b8 c4 c-. |
264 @c TODO Replace the following with a better example -td
265 @c Skylining handles this correctly without padText
267 So far we've seen static substitution -- when LilyPond
268 sees @code{\padText}, it replaces it with the stuff that
269 we've defined it to be (ie the stuff to the right of
272 LilyPond can handle non-static substitution, too (you
273 can think of these as functions).
275 @lilypond[quote,verbatim,ragged-right]
277 #(define-music-function (parser location padding) (number?)
279 \once \override TextScript #'padding = #$padding
287 c4^"piu mosso" fis a g
291 Using variables is also a good way to reduce work if the
292 LilyPond input syntax changes (see @ref{Updating old input files}). If
293 you have a single definition (such as @code{\dolce}) for all your
294 input files (see @ref{Style sheets}), then if the syntax changes, you
295 only need to update your single @code{\dolce} definition,
296 instead of making changes throughout every @code{.ly} file.
300 @subsection Style sheets
302 The output that LilyPond produces can be heavily modified; see
303 @ref{Tweaking output}, for details. But what if you have many
304 input files that you want to apply your tweaks to? Or what if you
305 simply want to separate your tweaks from the actual music? This
308 Let's look at an example. Don't worry if you don't understand
309 the parts with all the @code{#()}. This is explained in
310 @ref{Advanced tweaks with Scheme}.
312 @lilypond[quote,verbatim,ragged-right]
313 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
314 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
315 tempoMark = #(define-music-function (parser location markp) (string?)
317 \once \override Score . RehearsalMark #'self-alignment-X = #left
318 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
319 \mark \markup { \bold $markp }
324 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
325 \tempoMark "Poco piu mosso"
326 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
330 There are some problems with overlapping output; we'll fix those using
331 the techniques in @ref{Moving objects}. But let's also
332 do something about the @code{mpdolce} and @code{tempoMark}
333 definitions. They produce the output we desire, but we might want
334 to use them in another piece. We could simply copy-and-paste them
335 at the top of every file, but that's an annoyance. It also leaves
336 those definitions in our input files, and I personally find all
337 the @code{#()} somewhat ugly. Let's hide them in another file:
340 %%% save this to a file called "definitions.ly"
341 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
342 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
343 tempoMark = #(define-music-function (parser location markp) (string?)
345 \once \override Score . RehearsalMark #'self-alignment-X = #left
346 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
347 \mark \markup @{ \bold $markp @}
351 Now let's modify our music (let's save this file as @file{"music.ly"}).
353 @c We have to do this awkward example/lilypond-non-verbatim
354 @c because we can't do the \include stuff in the manual.
357 \include "definitions.ly"
361 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
362 \once \override Score.RehearsalMark #'padding = #2.0
363 \tempoMark "Poco piu mosso"
364 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
368 @lilypond[quote,ragged-right]
369 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
370 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
371 tempoMark = #(define-music-function (parser location markp) (string?)
373 \once \override Score . RehearsalMark #'self-alignment-X = #left
374 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
375 \mark \markup { \bold $markp }
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 That looks better, but let's make a few changes. The glissando is hard
388 to see, so let's make it thicker and closer to the note heads. Let's
389 put the metronome marking above the clef, instead of over the first
390 note. And finally, my composition professor hates @q{C} time signatures,
391 so we'd better make that @q{4/4} instead.
393 Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
398 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
399 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
400 tempoMark = #(define-music-function (parser location markp) (string?)
402 \once \override Score . RehearsalMark #'self-alignment-X = #left
403 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
404 \mark \markup @{ \bold $markp @}
409 \override MetronomeMark #'extra-offset = #'(-9 . 0)
410 \override MetronomeMark #'padding = #'3
413 \override TimeSignature #'style = #'numbered
416 \override Glissando #'thickness = #3
417 \override Glissando #'gap = #0.1
422 @lilypond[quote,ragged-right]
423 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
424 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
425 tempoMark = #(define-music-function (parser location markp) (string?)
427 \once \override Score . RehearsalMark #'self-alignment-X = #left
428 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
429 \mark \markup { \bold $markp }
434 \override MetronomeMark #'extra-offset = #'(-9 . 0)
435 \override MetronomeMark #'padding = #'3
438 \override TimeSignature #'style = #'numbered
441 \override Glissando #'thickness = #3
442 \override Glissando #'gap = #0.1
448 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
449 \once \override Score.RehearsalMark #'padding = #2.0
450 \tempoMark "Poco piu mosso"
451 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
455 That looks nicer! But now suppose that I want to publish this
456 piece. My composition professor doesn't like @q{C} time
457 signatures, but I'm somewhat fond of them. Let's copy the
458 current @file{definitions.ly} to @file{web-publish.ly} and
459 modify that. Since this music is aimed at producing a pdf which
460 will be displayed on the screen, we'll also increase the
461 overall size of the output.
465 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
466 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
467 tempoMark = #(define-music-function (parser location markp) (string?)
469 \once \override Score . RehearsalMark #'self-alignment-X = #left
470 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
471 \mark \markup @{ \bold $markp @}
474 #(set-global-staff-size 23)
477 \override MetronomeMark #'extra-offset = #'(-9 . 0)
478 \override MetronomeMark #'padding = #'3
483 \override Glissando #'thickness = #3
484 \override Glissando #'gap = #0.1
489 @lilypond[quote,ragged-right]
490 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
491 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
492 tempoMark = #(define-music-function (parser location markp) (string?)
494 \once \override Score . RehearsalMark #'self-alignment-X = #left
495 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
496 \mark \markup { \bold $markp }
499 #(set-global-staff-size 23)
502 \override MetronomeMark #'extra-offset = #'(-9 . 0)
503 \override MetronomeMark #'padding = #'3
506 \override Glissando #'thickness = #3
507 \override Glissando #'gap = #0.1
513 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
514 \once \override Score.RehearsalMark #'padding = #2.0
515 \tempoMark "Poco piu mosso"
516 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
520 Now in our music, I simply replace
521 @code{\include "definitions.ly"} with
522 @code{\include "web-publish.ly"}. Of course, we could make this
523 even more convenient. We could make a @file{definitions.ly} file which
524 contains only the definitions of @code{mpdolce} and @code{tempoMark}, a
525 @file{web-publish.ly} file which contains only the @code{\layout}
526 section listed above, and a @file{university.ly} file which
527 contains only the tweaks to produce the output that my professor
528 prefers. The top of @file{music.ly} would then look like this:
531 \include "definitions.ly"
533 %%% Only uncomment one of these two lines!
534 \include "web-publish.ly"
535 %\include "university.ly"
538 This approach can be useful even if you are only producing
539 one set of parts. I use half a dozen different
540 @q{style sheet} files for my projects. I begin every music
541 file with @code{\include "../global.ly"}, which contains
545 \version @w{"@version{}"}
546 #(ly:set-option 'point-and-click #f)
547 \include "../init/init-defs.ly"
548 \include "../init/init-layout.ly"
549 \include "../init/init-headers.ly"
550 \include "../init/init-paper.ly"
554 @node When things don't work
555 @section When things don't work
558 * Updating old input files::
559 * Troubleshooting (taking it all apart)::
563 @node Updating old input files
564 @subsection Updating old input files
566 The LilyPond input syntax occasionally changes. As LilyPond itself
567 improves, the syntax (input language) is modified accordingly. Sometimes
568 these changes are made to make the input easier to read and write or
569 sometimes the changes are made to accommodate new features of LilyPond.
571 LilyPond comes with a file that makes this updating easier:
572 @code{convert-ly}. For details about how to run this program, see
573 @rprogram{Updating files with convert-ly}.
575 Unfortunately, @code{convert-ly} cannot handle all input changes. It
576 takes care of simple search-and-replace changes (such as @code{raggedright}
577 becoming @code{ragged-right}), but some changes are too
578 complicated. The syntax changes that @code{convert-ly} cannot handle
579 are listed in @rprogram{Updating files with convert-ly}.
581 For example, in LilyPond 2.4 and earlier, accents and non-English
582 letters were entered using LaTeX -- for example,
583 @code{No\"el} (this would print the French word for
584 @q{Christmas}). In LilyPond 2.6 and above, the special
585 @code{ë} must be entered directly into the LilyPond file as an
586 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
587 special characters into UTF-8 characters; you must manually update
588 your old LilyPond input files.
591 @node Troubleshooting (taking it all apart)
592 @subsection Troubleshooting (taking it all apart)
594 Sooner or later, you will write a file that LilyPond cannot
595 compile. The messages that LilyPond gives may help
596 you find the error, but in many cases you need to do some
597 investigation to determine the source of the problem.
599 The most powerful tools for this purpose are the
600 single line comment (indicated by @code{%}) and the block
601 comment (indicated by @code{%@{ ... %@}}). If you don't
602 know where a problem is, start commenting out huge portions
603 of your input file. After you comment out a section, try
604 compiling the file again. If it works, then the problem
605 must exist in the portion you just commented. If it doesn't
606 work, then keep on commenting out material until you have
607 something that works.
609 In an extreme case, you might end up with only
623 (in other words, a file without any music)
625 If that happens, don't give up. Uncomment a bit -- say,
626 the bass part -- and see if it works. If it doesn't work,
627 then comment out all of the bass music (but leave
628 @code{\bass} in the @code{\score} uncommented.
631 bass = \relative c' @{
639 Now start slowly uncommenting more and more of the
640 @code{bass} part until you find the problem line.
642 Another very useful debugging technique is constructing
643 @ref{Minimal examples}.
646 @node Minimal examples
647 @subsection Minimal examples
649 A minimal example is an example which is as small as possible. These
650 examples are much easier to understand than long examples. Minimal
651 examples are used for
655 @item Sending a help request to mailing lists
656 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
657 LilyPond Snippet Repository}
660 To construct an example which is as small as possible, the rule is
661 quite simple: remove anything which is not necessary. When trying to
662 remove unnecessary parts of a file, it is a very good idea to comment
663 out lines instead of deleting them. That way, if you discover that you
664 actually @emph{do} need some lines, you can uncomment them, instead of
665 typing them in from scratch.
667 There are two exceptions to the @qq{as small as possible} rule:
670 @item Include the @code{\version} number.
671 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
675 The whole point of a minimal example is to make it easy to read:
678 @item Avoid using complicated notes, keys, or time signatures, unless you
679 wish to demonstrate something is about the behavior of those items.
680 @item Do not use @code{\override} commands unless that is the point of the
686 @node Scores and parts
687 @section Scores and parts
689 TODO: this is really old stuff from the really old tutorial.
690 Rewrite, fix, etc. Or maybe delete entirely. -gp
691 Include section on tags -td
692 and then move to section 5. Working ... -td
694 In orchestral music, all notes are printed twice. Once in a part for
695 the musicians, and once in a full score for the conductor. Variables can
696 be used to avoid double work. The music is entered once, and stored in
697 a variable. The contents of that variable is then used to generate
698 both the part and the full score.
700 It is convenient to define the notes in a special file. For example,
701 suppose that the file @file{horn-music.ly} contains the following part
702 of a horn/@/bassoon duo
705 hornNotes = \relative c @{
712 Then, an individual part is made by putting the following in a file
715 \include "horn-music.ly"
717 instrument = "Horn in F"
721 \transpose f c' \hornNotes
728 \include "horn-music.ly"
732 substitutes the contents of @file{horn-music.ly} at this position in
733 the file, so @code{hornNotes} is defined afterwards. The command
734 @code{\transpose f@tie{}c'} indicates that the argument, being
735 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
736 @code{f} is denoted by notated @code{c'}, which corresponds with the
737 tuning of a normal French Horn in@tie{}F. The transposition can be seen
738 in the following output
740 @lilypond[quote,ragged-right]
741 \transpose f c' \relative c {
747 In ensemble pieces, one of the voices often does not play for many
748 measures. This is denoted by a special rest, the multi-measure
749 rest. It is entered with a capital @code{R} followed by a duration
750 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
751 etc.). By multiplying the
752 duration, longer rests can be constructed. For example, this rest
753 takes 3@tie{}measures in 2/4 time
759 When printing the part, multi-rests
760 must be condensed. This is done by setting a run-time variable
763 \set Score.skipBars = ##t
767 This command sets the property @code{skipBars} in the
768 @code{Score} context to true (@code{##t}). Prepending the rest and
769 this option to the music above, leads to the following result
771 @lilypond[quote,ragged-right]
772 \transpose f c' \relative c {
774 \set Score.skipBars = ##t
781 The score is made by combining all of the music together. Assuming
782 that the other voice is in @code{bassoonNotes} in the file
783 @file{bassoon-music.ly}, a score is made with
786 \include "bassoon-music.ly"
787 \include "horn-music.ly"
790 \new Staff \hornNotes
791 \new Staff \bassoonNotes
798 @lilypond[quote,ragged-right]
806 r4 d,8 f | gis4 c | b bes |
807 a8 e f4 | g d | gis f