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. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node Suggestions for writing files
14 @chapter Suggestions for writing files
16 Now you're ready to begin writing larger LilyPond input files --
17 not just the little examples in the tutorial, but whole pieces.
18 But how should you go about doing it?
20 As long as LilyPond can understand your input files and produce
21 the output that you want, it doesn't matter what your input files
22 look like. However, there are a few other things to consider when
23 writing LilyPond input files.
26 @item What if you make a mistake? The structure of a LilyPond
27 file can make certain errors easier (or harder) to find.
29 @item What if you want to share your input files with somebody
30 else? In fact, what if you want to alter your own input files in
31 a few years? Some LilyPond input files are understandable at
32 first glance; others may leave you scratching your head
35 @item What if you want to upgrade your LilyPond file for use
36 with a later version of LilyPond? The input syntax changes
37 occasionally as LilyPond improves. Most changes can be
38 done automatically with @code{convert-ly}, but some changes
39 might require manual assistance. LilyPond input files can be
40 structured in order to be easier (or harder) to update.
45 * General suggestions::
46 * Typesetting existing music::
49 * Make and Makefiles::
53 @node General suggestions
54 @section General suggestions
56 Here are a few suggestions that can help to avoid (and fix) the most
57 common problems when typesetting:
61 @strong{Always include a @code{\version} number in your input files} no
62 matter how small they are. This prevents having to remember which
63 version of LilyPond the file was created with and is especially relevant
64 when @ref{Updating files with convert-ly} command (which requires the
65 @code{\version} statement to be present); or if sending your input files
66 to other users (e.g. when asking for help on the mail lists). Note that
67 all of the LilyPond templates contain @code{\version} numbers.
70 @strong{For each line in your input file, write one bar of music}. This
71 will make debugging any problems in your input files much simpler.
74 @strong{Include @ruser{Bar and bar number checks} as well as
75 @ruser{Octave checks}}. Including @q{checks} of this type in your input
76 files will help pinpoint mistakes more quickly. How often checks are
77 added will depend on the complexity of the music being typeset. For
78 simple compositions, checks added at a few at strategic points within
79 the music can be enough but for more complex music, with many voices
80 and/or staves, checks may be better placed after every bar.
83 @strong{Add comments within input files}. References to musical themes
84 (i.e. @q{second theme in violins}, @q{fourth variation,} etc.), or
85 simply including bar numbers as comments, will make navigating the input
86 file much simpler especically if something needs to be altered later
87 on or if passing on LilyPond input files to another person.
90 @strong{Add explicit note durations at the start of @q{sections}}. For
91 example, @code{c4 d e f} instead of just @code{c d e f} can make
92 rearranging the music later on simpler.
95 @strong{Learn to indent and align braces and parallel music}. Many
96 problems are often caused by either @q{missing} braces. Clearly
97 indenting @q{opening} and @q{closing} braces (or @code{<<} and @code{>>}
98 indicators) will help avoid such problems. For example;
118 is much easier to follow than;
121 \new Staff @{ \relative @{ r4 g'8 g c4 c8 d | e4 r8
123 << @{ f8 c c @} \new Staff @{ f8 f c @} >> r4 | @} @}
128 @strong{Keep music and style separate} by putting overrides in the
129 @code{\layout} block;
133 @var{@dots{}music@dots{}}
135 \override TabStaff.Stemstencil = ##f
140 This will not create a new context but it will apply when one is
142 @rlearning{Saving typing with variables and functions}, and
143 @rlearning{Style sheets}.
148 @node Typesetting existing music
149 @section Typesetting existing music
151 If you are entering music from an existing score (i.e., typesetting a
152 piece of existing sheet music),
156 @item Enter the manuscript (the physical copy of the music) into
157 LilyPond one system at a time (but still only one bar per line of text),
158 and check each system when you finish it. You may use the
159 @code{showLastLength} or @code{showFirstLength} properties to speed up
160 processing -- see @ruser{Skipping corrected music}.
162 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
163 in the input file whenever the manuscript has a line break. This
164 makes it much easier to compare the LilyPond music to the original
165 music. When you are finished proofreading your score, you may
166 define @code{mBreak = @{ @}} to remove all those line breaks. This
167 will allow LilyPond to place line breaks wherever it feels are
170 @item When entering a part for a transposing instrument into a
171 variable, it is recommended that the notes are wrapped in
174 \transpose c natural-pitch @{@dots{}@}
178 (where @code{natural-pitch} is the open pitch of the instrument) so
179 that the music in the variable is effectively in C. You can transpose
180 it back again when the variable is used, if required, but you might
181 not want to (e.g., when printing a score in concert pitch,
182 converting a trombone part from treble to bass clef, etc.)
183 Mistakes in transpositions are less likely if all the music in
184 variables is at a consistent pitch.
186 Also, only ever transpose to/from C. That means that the only other
187 keys you will use are the natural pitches of the instruments - bes
188 for a B-flat trumpet, aes for an A-flat clarinet, etc.
194 @section Large projects
196 When working on a large project, having a clear structure to your
197 lilypond input files becomes vital.
201 @item @strong{Use a variable for each voice}, with a minimum of
202 structure inside the definition. The structure of the
203 @code{\score} section is the most likely thing to change;
204 the @code{violin} definition is extremely unlikely to change
205 in a new version of LilyPond.
208 violin = \relative @{
221 @item @strong{Separate tweaks from music definitions}. This point was
222 made previously, but for large projects it is absolutely vital. We
223 might need to change the definition of @code{fthenp}, but then we only
224 need to do this once, and we can still avoid touching anything inside
229 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
230 violin = \relative @{
238 @node Troubleshooting
239 @section Troubleshooting
241 Sooner or later, you will write a file that LilyPond cannot
242 compile. The messages that LilyPond gives may help
243 you find the error, but in many cases you need to do some
244 investigation to determine the source of the problem.
246 The most powerful tools for this purpose are the
247 single line comment (indicated by @code{%}) and the block
248 comment (indicated by @code{%@{@dots{}%@}}). If you don't
249 know where a problem is, start commenting out huge portions
250 of your input file. After you comment out a section, try
251 compiling the file again. If it works, then the problem
252 must exist in the portion you just commented. If it doesn't
253 work, then keep on commenting out material until you have
254 something that works.
256 In an extreme case, you might end up with only
270 (in other words, a file without any music)
272 If that happens, don't give up. Uncomment a bit -- say,
273 the bass part -- and see if it works. If it doesn't work,
274 then comment out all of the bass music (but leave
275 @code{\bass} in the @code{\score} uncommented.
286 Now start slowly uncommenting more and more of the
287 @code{bass} part until you find the problem line.
289 Another very useful debugging technique is constructing
290 @rweb{Tiny examples}.
293 @node Make and Makefiles
294 @section Make and Makefiles
299 Pretty well all the platforms Lilypond can run on support a software
300 facility called @code{make}. This software reads a special file called a
301 @code{Makefile} that defines what files depend on what others and what
302 commands you need to give the operating system to produce one file from
303 another. For example the makefile would spell out how to produce
304 @file{ballad.pdf} and @file{ballad.midi} from @file{ballad.ly} by
307 There are times when it is a good idea to create a @code{Makefile}
308 for your project, either for your own convenience or
309 as a courtesy to others who might have access to your source files.
310 This is true for very large projects with many included files and
311 different output options (e.g. full score, parts, conductor's
312 score, piano reduction, etc.), or for projects that
313 require difficult commands to build them (such as
314 @code{lilypond-book} projects). Makefiles vary greatly in
315 complexity and flexibility, according to the needs and skills of
316 the authors. The program GNU Make comes installed on GNU/Linux
317 distributions and on MacOS X, and it is also available for Windows.
319 See the @strong{GNU Make Manual} for full details on using
320 @code{make}, as what follows here gives only a glimpse of what it
323 The commands to define rules in a makefile differ
324 according to platform; for instance the various forms of GNU/Linux and
325 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
326 MacOS X, you need to configure the system to use the command-line
327 interpreter. Here are some example makefiles, with versions for both
328 GNU/Linux/MacOS and Windows.
330 The first example is for an orchestral work in four
331 movements with a directory structure as follows:
348 | |-- symphony-cello.ly
349 | |-- symphony-horn.ly
350 | |-- symphony-oboes.ly
351 | |-- symphony-viola.ly
352 | |-- symphony-violinOne.ly
353 | `-- symphony-violinTwo.ly
363 The @file{.ly} files in the @file{Scores} and
364 @file{Parts} directories get their notes from @file{.ily}
365 files in the @file{Notes} directory:
368 %%% top of file "symphony-cello.ly"
369 \include ../symphonyDefs.ily
370 \include ../Notes/cello.ily
373 The makefile will have targets of @code{score} (entire piece in
374 full score), @code{movements} (individual movements in full score),
375 and @code{parts} (individual parts for performers). There
376 is also a target @code{archive} that will create a tarball of
377 the source files, suitable for sharing via web or email. Here is
378 the makefile for GNU/Linux or MacOS X. It should be saved with the
379 name @code{Makefile} in the top directory of the project:
381 @warning{When a target or pattern rule is defined, the
382 subsequent lines must begin with tabs, not spaces.}
385 # the name stem of the output files
387 # determine how many processors are present
388 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
389 # The command to run lilypond
390 LILY_CMD = lilypond -ddelete-intermediate-files \
391 -dno-point-and-click -djob-count=$(CPU_CORES)
393 # The suffixes used in this Makefile.
394 .SUFFIXES: .ly .ily .pdf .midi
396 # Input and output files are searched in the directories listed in
397 # the VPATH variable. All of them are subdirectories of the current
398 # directory (given by the GNU make variable `CURDIR').
405 # The pattern rule to create PDF and MIDI files from a LY input file.
406 # The .pdf output files are put into the `PDF' subdirectory, and the
407 # .midi files go into the `MIDI' subdirectory.
409 $(LILY_CMD) $<; \ # this line begins with a tab
410 if test -f "$*.pdf"; then \
413 if test -f "$*.midi"; then \
414 mv "$*.midi" MIDI/; \
425 # The dependencies of the movements.
426 $(piece)I.pdf: $(piece)I.ly $(notes)
427 $(piece)II.pdf: $(piece)II.ly $(notes)
428 $(piece)III.pdf: $(piece)III.ly $(notes)
429 $(piece)IV.pdf: $(piece)IV.ly $(notes)
431 # The dependencies of the full score.
432 $(piece).pdf: $(piece).ly $(notes)
434 # The dependencies of the parts.
435 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
436 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
437 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
438 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
439 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
440 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
442 # Type `make score' to generate the full score of all four
443 # movements as one file.
447 # Type `make parts' to generate all parts.
448 # Type `make foo.pdf' to generate the part for instrument `foo'.
449 # Example: `make symphony-cello.pdf'.
451 parts: $(piece)-cello.pdf \
452 $(piece)-violinOne.pdf \
453 $(piece)-violinTwo.pdf \
458 # Type `make movements' to generate files for the
459 # four movements separately.
461 movements: $(piece)I.pdf \
466 all: score parts movements
469 tar -cvvf stamitz.tar \ # this line begins with a tab
470 --exclude=*pdf --exclude=*~ \
471 --exclude=*midi --exclude=*.tar \
476 There are special complications on the Windows platform. After
477 downloading and installing GNU Make for Windows, you must set the
478 correct path in the system's environment variables so that the
479 DOS shell can find the Make program. To do this, right-click on
480 "My Computer," then choose @code{Properties} and
481 @code{Advanced}. Click @code{Environment Variables}, and then
482 in the @code{System Variables} pane, highlight @code{Path}, click
483 @code{edit}, and add the path to the GNU Make executable file, which
484 will look something like this:
487 C:\Program Files\GnuWin32\bin
490 The makefile itself has to be altered to handle different shell
491 commands and to deal with spaces that are present
492 in some default system directories. The @code{archive} target
493 is eliminated since Windows does not have the @code{tar} command,
494 and Windows also has a different default extension for midi files.
501 LILY_CMD = lilypond -ddelete-intermediate-files \
502 -dno-point-and-click \
503 -djob-count=$(NUMBER_OF_PROCESSORS)
505 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
506 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
509 .SUFFIXES: .ly .ily .pdf .mid
518 $(LILY_CMD) $< # this line begins with a tab
519 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
520 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
532 $(piece)I.pdf: $(piece)I.ly $(notes)
533 $(piece)II.pdf: $(piece)II.ly $(notes)
534 $(piece)III.pdf: $(piece)III.ly $(notes)
535 $(piece)IV.pdf: $(piece)IV.ly $(notes)
537 $(piece).pdf: $(piece).ly $(notes)
539 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
540 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
541 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
542 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
543 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
544 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
550 parts: $(piece)-cello.pdf \
551 $(piece)-violinOne.pdf \
552 $(piece)-violinTwo.pdf \
558 movements: $(piece)I.pdf \
563 all: score parts movements
567 The next Makefile is for a @command{lilypond-book} document done in
568 LaTeX. This project has an index, which requires that the
569 @command{latex} command be run twice to update links. Output files are
570 all stored in the @code{out} directory for .pdf output and in the
571 @code{htmlout} directory for the html output.
580 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
581 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
582 PDF=cd $(OUTDIR) && pdflatex $(FILE)
583 HTML=cd $(WEBDIR) && latex2html $(FILE)
584 INDEX=cd $(OUTDIR) && makeindex $(FILE)
585 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
590 $(LILYBOOK_PDF) # begin with tab
591 $(PDF) # begin with tab
592 $(INDEX) # begin with tab
593 $(PDF) # begin with tab
594 $(PREVIEW) # begin with tab
597 $(LILYBOOK_HTML) # begin with tab
598 $(HTML) # begin with tab
599 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
600 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
603 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
606 rm -rf $(OUTDIR) # begin with tab
609 rm -rf $(WEBDIR) # begin with tab
612 tar -cvvf myproject.tar \ # begin this line with tab
614 --exclude=htmlout/* \
615 --exclude=myproject/* \
622 TODO: make this thing work on Windows
624 The previous makefile does not work on Windows. An alternative
625 for Windows users would be to create a simple batch file
626 containing the build commands. This will not
627 keep track of dependencies the way a makefile does, but it at
628 least reduces the build process to a single command. Save the
629 following code as @command{build.bat} or @command{build.cmd}.
630 The batch file can be run at the DOS prompt or by simply
631 double-clicking its icon.
634 lilypond-book --output=out --pdf myproject.lytex
640 copy out\myproject.pdf MyProject.pdf
647 @ref{Command-line usage},