1 @c -*- coding: utf-8; mode: texinfo; -*-
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::
24 * Make and Makefiles::
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::
66 @node General suggestions
67 @subsection General suggestions
69 Here are a few suggestions that can help you to avoid or fix
73 @item @strong{Include @code{\version} numbers in every file}. Note that all
74 templates contain @code{\version} information. We
75 highly recommend that you always include the @code{\version}, no matter
76 how small your file is. Speaking from personal experience, it's
77 quite frustrating to try to remember which version of LilyPond you were
78 using a few years ago. @command{convert-ly} requires you to declare
79 which version of LilyPond you used.
81 @item @strong{Include checks}: @ruser{Bar and bar number checks},
82 @ruser{Octave checks}. If you include checks every so often, then
83 if you make a mistake, you can pinpoint it quicker. How often is
84 @q{every so often}? It depends on the complexity of the music.
85 For very simple music, perhaps just once or twice. For very
86 complex music, perhaps every bar.
88 @item @strong{One bar per line of text}. If there is anything complicated,
90 itself or in the output you desire, it's often good to write only one bar
91 per line. Saving screen space by cramming eight bars per line just isn't
92 worth it if you have to @q{debug} your input files.
94 @item @strong{Comment your input files}. Use either bar numbers
96 references to musical themes (@q{second theme in violins,} @q{fourth
97 variation,} etc.). You may not need comments when you're writing the piece
98 for the first time, but if you want to go back to change something two or
99 three years later, or if you pass the source over to a friend, it will
101 challenging to determine your intentions or how your file is structured if
102 you didn't comment the file.
104 @item @strong{Indent your braces}. A lot of problems are caused by an
106 in the number of @code{@{} and @code{@}}.
108 @item @strong{Explicitly add durations} at the beginnings of sections
109 and variables. If you specify @code{c4 d e} at the beginning of a
110 phrase (instead of just @code{c d e}) you can save yourself some
111 problems if you rearrange your music later.
113 @item @strong{Separate tweaks} from music definitions. See
114 @ref{Saving typing with variables and functions}, and
120 @node Typesetting existing music
121 @subsection Typesetting existing music
123 If you are entering music from an existing score (i.e., typesetting a
124 piece of existing sheet music),
128 @item Enter the manuscript (the physical copy of the music) into
129 LilyPond one system at a time (but still only one bar per line of text),
130 and check each system when you finish it. You may use the
131 @code{showLastLength} or @code{showFirstLength} properties to speed up
132 processing -- see @ruser{Skipping corrected music}.
134 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
135 in the input file whenever the manuscript has a line break. This
136 makes it much easier to compare the LilyPond music to the original
137 music. When you are finished proofreading your score, you may
138 define @code{mBreak = @{ @}} to remove all those line breaks. This
139 will allow LilyPond to place line breaks wherever it feels are
142 @item When entering a part for a transposing instrument into a
143 variable, it is recommended that the notes are wrapped in
146 \transpose c natural-pitch @{...@}
148 (where @code{natural-pitch} is the open pitch of the instrument) so
149 that the music in the variable is effectively in C. You can transpose
150 it back again when the variable is used, if required, but you might
151 not want to (e.g., when printing a score in concert pitch,
152 converting a trombone part from treble to bass clef, etc.)
153 Mistakes in transpositions are less likely if all the music in
154 variables is at a consistent pitch.
156 Also, only ever transpose to/from C. That means that the only other
157 keys you will use are the natural pitches of the instruments - bes
158 for a B-flat trumpet, aes for an A-flat clarinet, etc.
164 @subsection Large projects
166 When working on a large project, having a clear structure to your
167 lilypond input files becomes vital.
171 @item @strong{Use a variable for each voice}, with a minimum of
172 structure inside the definition. The structure of the
173 @code{\score} section is the most likely thing to change;
174 the @code{violin} definition is extremely unlikely to change
175 in a new version of LilyPond.
178 violin = \relative c'' @{
191 @item @strong{Separate tweaks from music definitions}. This
192 point was made previously, but for large
193 projects it is absolutely vital. We might need to change
194 the definition of @code{fthenp}, but then we only need
195 to do this once, and we can still avoid touching anything
196 inside @code{violin}.
200 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
201 violin = \relative c'' @{
209 @node When things don't work
210 @section When things don't work
213 * Updating old input files::
215 * Troubleshooting (taking it all apart)::
219 @node Updating old input files
220 @subsection Updating old input files
223 @cindex updating old input files
225 The LilyPond input syntax occasionally changes. As LilyPond itself
226 improves, the syntax (input language) is modified accordingly. Sometimes
227 these changes are made to make the input easier to read and write or
228 sometimes the changes are made to accommodate new features of LilyPond.
230 LilyPond comes with a file that makes this updating easier:
231 @code{convert-ly}. For details about how to run this program, see
232 @rprogram{Updating files with convert-ly}.
234 Unfortunately, @code{convert-ly} cannot handle all input changes. It
235 takes care of simple search-and-replace changes (such as @code{raggedright}
236 becoming @code{ragged-right}), but some changes are too
237 complicated. The syntax changes that @code{convert-ly} cannot handle
238 are listed in @rprogram{Updating files with convert-ly}.
240 For example, in LilyPond 2.4 and earlier, accents and non-English
241 letters were entered using LaTeX -- for example,
242 @code{No\"el} (this would print the French word for
243 @q{Christmas}). In LilyPond 2.6 and above, the special
244 @code{ë} must be entered directly into the LilyPond file as an
245 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
246 special characters into UTF-8 characters; you must manually update
247 your old LilyPond input files.
250 @subsection Common errors
252 The error conditions described below occur often, yet the cause
253 is not obvious or easily found. Once seen and understood, they
258 * Music runs off the page::
259 * An extra staff appears::
260 * Apparent error in ../ly/init.ly::
261 * Error message Unbound variable %::
262 * Error message FT_Get_Glyph_Name::
265 @node Music runs off the page
266 @unnumberedsubsubsec Music runs off the page
268 Music running off the page over the right margin or appearing
269 unduly compressed is almost always due to entering an incorrect
270 duration on a note, causing the final note in a measure to extend
271 over the bar line. It is not invalid if the final note in a
272 measure does not end on the automatically entered bar line, as the
273 note is simply assumed to carry over into the next measure. But
274 if a long sequence of such carry-over measures occurs the music
275 can appear compressed or may flow off the page because automatic
276 line breaks can be inserted only at the end of complete measures,
277 i.e., where all notes end before or at the end of the measure.
279 @warning{An incorrect duration can cause line breaks to be
280 inhibited, leading to a line of highly compressed music or
281 music which flows off the page.}
283 The incorrect duration can be found easily if bar checks are used,
284 see @ruser{Bar and bar number checks}.
286 If you actually intend to have a series of such carry-over measures
287 you will need to insert an invisible bar line where you want the
288 line to break. For details, see @ruser{Bar lines}.
291 @node An extra staff appears
292 @unnumberedsubsubsec An extra staff appears
294 If contexts are not created explicitly with @code{\new} they will be
295 silently created as soon as a command is encountered which cannot
296 be applied to an existing context. In simple scores the automatic
297 creation of contexts is useful, and most of the examples in the
298 LilyPond manuals take advantage of this simplification. But
299 occasionally the silent creation of contexts can give rise to
300 unexpected new staves or scores. For example, it might be expected
301 that the following code would cause all note heads within the
302 following staff to be colored red, but in fact it results in two
303 staves with the note heads remaining the default black in the lower
306 @lilypond[quote,verbatim,relative=2]
307 \override Staff.NoteHead #'color = #red
311 This is because a @code{Staff} context does not exist when the
312 override is processed, so one is implicitly created and the override
313 is applied to it, but then the @code{\new Staff} command creates
314 another, separate, staff into which the notes are placed. The
315 correct code to color all note heads red is
317 @lilypond[quote,verbatim,relative=2]
319 \override Staff.NoteHead #'color = #red
324 As a second example, if a @code{\relative} command is placed inside
325 a @code{\repeat} command two staves result, the second offset from
326 the first, because the @code{\repeat} command generates two
327 @code{\relative} blocks, which each implicitly create @code{Staff}
328 and @code{Voice} blocks.
330 @lilypond[quote,verbatim]
331 \repeat unfold 2 \relative { c d e f }
334 The correct way is to reverse the @code{\repeat} and
335 @code{\relative} commands, like this:
337 @lilypond[quote,verbatim]
339 \repeat unfold 2 { c d e f }
344 @node Apparent error in ../ly/init.ly
345 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
347 Various obscure error messages may appear about syntax errors in
348 @code{../ly/init.ly} if the input file is not correctly formed,
349 for example, if it does not contain correctly
350 matched braces or quote signs.
352 The most common error is a missing brace, (@code{@}}), at the end of
353 a @code{score} block. Here the solution is obvious: check the
354 @code{score} block is correctly terminated. The correct structure
355 of an input file is described in @ref{How LilyPond input files work}.
356 Using an editor which automatically highlights matching brackets and
357 braces is helpful to avoid such errors.
359 This error message can also appear if a terminating quote sign,
360 (@code{"}), is omitted. In this case an accompanying error message
361 should give a line number close to the line in error. The
362 mismatched quote will usually be on the line one or two above.
364 @node Error message Unbound variable %
365 @unnumberedsubsubsec Error message Unbound variable %
367 This error message will appear at the bottom of the console
368 output or log file together with a @qq{GUILE signalled an error ...}
369 message every time a Scheme routine is called which (invalidly)
370 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
372 LilyPond comments begin with a percent sign, (@code{%}), and must
373 not be used within Scheme routines. Scheme comments begin with a
374 semi-colon, (@code{;}).
376 @node Error message FT_Get_Glyph_Name
377 @unnumberedsubsubsec Error message FT_Get_Glyph_Name
379 This error messages appears in the console output or log file if
380 an input file contains a non-ASCII character and was not saved in
381 UTF-8 encoding. For details, see @ruser{Text encoding}.
383 @node Troubleshooting (taking it all apart)
384 @subsection Troubleshooting (taking it all apart)
386 Sooner or later, you will write a file that LilyPond cannot
387 compile. The messages that LilyPond gives may help
388 you find the error, but in many cases you need to do some
389 investigation to determine the source of the problem.
391 The most powerful tools for this purpose are the
392 single line comment (indicated by @code{%}) and the block
393 comment (indicated by @code{%@{ ... %@}}). If you don't
394 know where a problem is, start commenting out huge portions
395 of your input file. After you comment out a section, try
396 compiling the file again. If it works, then the problem
397 must exist in the portion you just commented. If it doesn't
398 work, then keep on commenting out material until you have
399 something that works.
401 In an extreme case, you might end up with only
415 (in other words, a file without any music)
417 If that happens, don't give up. Uncomment a bit -- say,
418 the bass part -- and see if it works. If it doesn't work,
419 then comment out all of the bass music (but leave
420 @code{\bass} in the @code{\score} uncommented.
423 bass = \relative c' @{
431 Now start slowly uncommenting more and more of the
432 @code{bass} part until you find the problem line.
434 Another very useful debugging technique is constructing
435 @ref{Minimal examples}.
438 @node Minimal examples
439 @subsection Minimal examples
441 A minimal example is an example which is as small as possible. These
442 examples are much easier to understand than long examples. Minimal
443 examples are used for
447 @item Sending a help request to mailing lists
448 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
449 LilyPond Snippet Repository}
452 To construct an example which is as small as possible, the rule is
453 quite simple: remove anything which is not necessary. When trying to
454 remove unnecessary parts of a file, it is a very good idea to comment
455 out lines instead of deleting them. That way, if you discover that you
456 actually @emph{do} need some lines, you can uncomment them, instead of
457 typing them in from scratch.
459 There are two exceptions to the @qq{as small as possible} rule:
462 @item Include the @code{\version} number.
463 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
467 The whole point of a minimal example is to make it easy to read:
470 @item Avoid using complicated notes, keys, or time signatures, unless you
471 wish to demonstrate something is about the behavior of those items.
472 @item Do not use @code{\override} commands unless that is the point of the
478 @node Make and Makefiles
479 @section Make and Makefiles
484 Pretty well all the platforms Lilypond can run on support a software
485 facility called @code{make}. This software reads a special file called a
486 @code{Makefile} that defines what files depend on what others and what
487 commands you need to give the operating system to produce one file from
488 another. For example the makefile would spell out how to produce
489 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
492 There are times when it is a good idea to create a @code{Makefile}
493 for your project, either for your own convenience or
494 as a courtesy to others who might have access to your source files.
495 This is true for very large projects with many included files and
496 different output options (e.g. full score, parts, conductor's
497 score, piano reduction, etc.), or for projects that
498 require difficult commands to build them (such as
499 @code{lilypond-book} projects). Makefiles vary greatly in
500 complexity and flexibility, according to the needs and skills of
501 the authors. The program GNU Make comes installed on GNU/Linux
502 distributions and on MacOS X, and it is also available for Windows.
504 See the @strong{GNU Make Manual} for full details on using
505 @code{make}, as what follows here gives only a glimpse of what it
508 The commands to define rules in a makefile differ
509 according to platform; for instance the various forms of Linux and
510 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
511 MacOS X, you need to configure the system to use the command-line
512 intepreter. Here are some example makefiles, with versions for both
513 Linux/MacOS and Windows.
515 The first example is for an orchestral work in four
516 movements with a directory structure as follows:
533 | |-- symphony-cello.ly
534 | |-- symphony-horn.ly
535 | |-- symphony-oboes.ly
536 | |-- symphony-viola.ly
537 | |-- symphony-violinOne.ly
538 | `-- symphony-violinTwo.ly
548 The @code{.ly} files in the @code{Scores} and
549 @code{Parts} directories get their notes from @code{.ily}
550 files in the @code{Notes} directory:
553 %%% top of file "symphony-cello.ly"
554 \include ../definitions.ily
555 \include ../Notes/cello.ily
558 The makefile will have targets of @code{score} (entire piece in
559 full score), @code{movements} (individual movements in full score),
560 and @code{parts} (individual parts for performers). There
561 is also a target @code{archive} that will create a tarball of
562 the source files, suitable for sharing via web or email. Here is
563 the makefile for GNU/Linux or MacOS X. It should be saved with the
564 name @code{Makefile} in the top directory of the project:
566 @warning{When a target or pattern rule is defined, the
567 subsequent lines must begin with tabs, not spaces.}
570 # the name stem of the output files
572 # determine how many processors are present
573 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
574 # The command to run lilypond
575 LILY_CMD = lilypond -ddelete-intermediate-files \
576 -dno-point-and-click -djob-count=$(CPU_CORES)
578 # The suffixes used in this Makefile.
579 .SUFFIXES: .ly .ily .pdf .midi
581 # Input and output files are searched in the directories listed in
582 # the VPATH variable. All of them are subdirectories of the current
583 # directory (given by the GNU make variable `CURDIR').
590 # The pattern rule to create PDF and MIDI files from a LY input file.
591 # The .pdf output files are put into the `PDF' subdirectory, and the
592 # .midi files go into the `MIDI' subdirectory.
594 $(LILY_CMD) $<; \ # this line begins with a tab
595 if test -f "$*.pdf"; then \
598 if test -f "$*.midi"; then \
599 mv "$*.midi" MIDI/; \
610 # The dependencies of the movements.
611 $(piece)I.pdf: $(piece)I.ly $(notes)
612 $(piece)II.pdf: $(piece)II.ly $(notes)
613 $(piece)III.pdf: $(piece)III.ly $(notes)
614 $(piece)IV.pdf: $(piece)IV.ly $(notes)
616 # The dependencies of the full score.
617 $(piece).pdf: $(piece).ly $(notes)
619 # The dependencies of the parts.
620 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
621 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
622 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
623 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
624 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
625 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
627 # Type `make score' to generate the full score of all four
628 # movements as one file.
632 # Type `make parts' to generate all parts.
633 # Type `make foo.pdf' to generate the part for instrument `foo'.
634 # Example: `make symphony-cello.pdf'.
636 parts: $(piece)-cello.pdf \
637 $(piece)-violinOne.pdf \
638 $(piece)-violinTwo.pdf \
643 # Type `make movements' to generate files for the
644 # four movements separately.
646 movements: $(piece)I.pdf \
651 all: score parts movements
654 tar -cvvf stamitz.tar \ # this line begins with a tab
655 --exclude=*pdf --exclude=*~ \
656 --exclude=*midi --exclude=*.tar \
661 There are special complications on the Windows platform. After
662 downloading and installing GNU Make for Windows, you must set the
663 correct path in the system's environment variables so that the
664 DOS shell can find the Make program. To do this, right-click on
665 "My Computer," then choose @code{Properties} and
666 @code{Advanced}. Click @code{Environment Variables}, and then
667 in the @code{System Variables} pane, highlight @code{Path}, click
668 @code{edit}, and add the path to the GNU Make executable file, which
669 will look something like this:
672 C:\Program Files\GnuWin32\bin
675 The makefile itself has to be altered to handle different shell
676 commands and to deal with spaces that are present
677 in some default system directories. The @code{archive} target
678 is eliminated since Windows does not have the @code{tar} command,
679 and Windows also has a different default extension for midi files.
686 LILY_CMD = lilypond -ddelete-intermediate-files \
687 -dno-point-and-click \
688 -djob-count=$(NUMBER_OF_PROCESSORS)
690 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
691 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
694 .SUFFIXES: .ly .ily .pdf .mid
703 $(LILY_CMD) $< # this line begins with a tab
704 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
705 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
717 $(piece)I.pdf: $(piece)I.ly $(notes)
718 $(piece)II.pdf: $(piece)II.ly $(notes)
719 $(piece)III.pdf: $(piece)III.ly $(notes)
720 $(piece)IV.pdf: $(piece)IV.ly $(notes)
722 $(piece).pdf: $(piece).ly $(notes)
724 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
725 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
726 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
727 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
728 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
729 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
735 parts: $(piece)-cello.pdf \
736 $(piece)-violinOne.pdf \
737 $(piece)-violinTwo.pdf \
743 movements: $(piece)I.pdf \
748 all: score parts movements
752 The next Makefile is for a @command{lilypond-book} document done in
753 LaTeX. This project has an index, which requires that the
754 @command{latex} command be run twice to update links. Output files are
755 all stored in the @code{out} directory for .pdf output and in the
756 @code{htmlout} directory for the html output.
765 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
766 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
767 PDF=cd $(OUTDIR) && pdflatex $(FILE)
768 HTML=cd $(WEBDIR) && latex2html $(FILE)
769 INDEX=cd $(OUTDIR) && makeindex $(FILE)
770 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
775 $(LILYBOOK_PDF) # begin with tab
776 $(PDF) # begin with tab
777 $(INDEX) # begin with tab
778 $(PDF) # begin with tab
779 $(PREVIEW) # begin with tab
782 $(LILYBOOK_HTML) # begin with tab
783 $(HTML) # begin with tab
784 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
785 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
788 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
791 rm -rf $(OUTDIR) # begin with tab
794 rm -rf $(WEBDIR) # begin with tab
797 tar -cvvf myproject.tar \ # begin this line with tab
799 --exclude=htmlout/* \
800 --exclude=myproject/* \
807 TODO: make this thing work on Windows
809 The previous makefile does not work on Windows. An alternative
810 for Windows users would be to create a simple batch file
811 containing the build commands. This will not
812 keep track of dependencies the way a makefile does, but it at
813 least reduces the build process to a single command. Save the
814 following code as @command{build.bat} or @command{build.cmd}.
815 The batch file can be run at the DOS prompt or by simply
816 double-clicking its icon.
819 lilypond-book --output=out --pdf myproject.lytex
825 copy out\myproject.pdf MyProject.pdf
831 @rprogram{Setup for MacOS X},
832 @rprogram{Command-line usage},
833 @rprogram{LilyPond-book}