]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/usage/suggestions.itely
Doc: Part of Issue 989 non-integer for \bendAfter
[lilypond.git] / Documentation / usage / suggestions.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
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..
9 @end ignore
10
11 @c \version "2.12.0"
12
13 @node Suggestions for writing files
14 @chapter Suggestions for writing files
15
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?
19
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.
24
25 @itemize
26 @item What if you make a mistake?  The structure of a LilyPond
27 file can make certain errors easier (or harder) to find.
28
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
33 for an hour.
34
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.
41
42 @end itemize
43
44 @menu
45 * General suggestions::
46 * Typesetting existing music::
47 * Large projects::
48 * Troubleshooting::
49 * Make and Makefiles::
50 @end menu
51
52
53 @node General suggestions
54 @section General suggestions
55
56 Here are a few suggestions that can help you to avoid or fix
57 problems:
58
59 @itemize
60 @item @strong{Include @code{\version} numbers in every file}.  Note that all
61 templates contain @code{\version} information.  We
62 highly recommend that you always include the @code{\version}, no matter
63 how small your file is.  Speaking from personal experience, it's
64 quite frustrating to try to remember which version of LilyPond you were
65 using a few years ago.  @command{convert-ly} requires you to declare
66 which version of LilyPond you used.
67
68 @item @strong{Include checks}: @ruser{Bar and bar number checks},
69 @ruser{Octave checks}.  If you include checks every so often, then
70 if you make a mistake, you can pinpoint it quicker.  How often is
71 @q{every so often}?  It depends on the complexity of the music.
72 For very simple music, perhaps just once or twice.  For very
73 complex music, perhaps every bar.
74
75 @item @strong{One bar per line of text}.  If there is anything complicated,
76 either in the music
77 itself or in the output you desire, it's often good to write only one bar
78 per line.  Saving screen space by cramming eight bars per line just isn't
79 worth it if you have to @q{debug} your input files.
80
81 @item @strong{Comment your input files}.  Use either bar numbers
82 (every so often) or
83 references to musical themes (@q{second theme in violins,} @q{fourth
84 variation,} etc.).  You may not need comments when you're writing the piece
85 for the first time, but if you want to go back to change something two or
86 three years later, or if you pass the source over to a friend, it will
87 be much more
88 challenging to determine your intentions or how your file is structured if
89 you didn't comment the file.
90
91 @item @strong{Indent your braces}.  A lot of problems are caused by an
92 imbalance
93 in the number of @code{@{} and @code{@}}.
94
95 @item @strong{Explicitly add durations} at the beginnings of sections
96 and variables.  If you specify @code{c4 d e} at the beginning of a
97 phrase (instead of just @code{c d e}) you can save yourself some
98 problems if you rearrange your music later.
99
100 @item @strong{Separate tweaks} from music definitions.  See
101 @rlearning{Saving typing with variables and functions}, and
102 @rlearning{Style sheets}.
103
104 @end itemize
105
106
107 @node Typesetting existing music
108 @section Typesetting existing music
109
110 If you are entering music from an existing score (i.e., typesetting a
111 piece of existing sheet music),
112
113 @itemize
114
115 @item Enter the manuscript (the physical copy of the music) into
116 LilyPond one system at a time (but still only one bar per line of text),
117 and check each system when you finish it.  You may use the
118 @code{showLastLength} or @code{showFirstLength} properties to speed up
119 processing -- see @ruser{Skipping corrected music}.
120
121 @item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
122 in the input file whenever the manuscript has a line break.  This
123 makes it much easier to compare the LilyPond music to the original
124 music.  When you are finished proofreading your score, you may
125 define @code{mBreak = @{ @}} to remove all those line breaks.  This
126 will allow LilyPond to place line breaks wherever it feels are
127 best.
128
129 @item When entering a part for a transposing instrument into a
130 variable, it is recommended that the notes are wrapped in
131
132 @example
133 \transpose c natural-pitch @{...@}
134 @end example
135
136 @noindent
137 (where @code{natural-pitch} is the open pitch of the instrument) so
138 that the music in the variable is effectively in C. You can transpose
139 it back again when the variable is used, if required, but you might
140 not want to (e.g., when printing a score in concert pitch,
141 converting a trombone part from treble to bass clef, etc.)
142 Mistakes in transpositions are less likely if all the music in
143 variables is at a consistent pitch.
144
145 Also, only ever transpose to/from C. That means that the only other
146 keys you will use are the natural pitches of the instruments - bes
147 for a B-flat trumpet, aes for an A-flat clarinet, etc.
148
149 @end itemize
150
151
152 @node Large projects
153 @section Large projects
154
155 When working on a large project, having a clear structure to your
156 lilypond input files becomes vital.
157
158 @itemize
159
160 @item @strong{Use a variable for each voice}, with a minimum of
161 structure inside the definition.  The structure of the
162 @code{\score} section is the most likely thing to change;
163 the @code{violin} definition is extremely unlikely to change
164 in a new version of LilyPond.
165
166 @example
167 violin = \relative c'' @{
168 g4 c'8. e16
169 @}
170 ...
171 \score @{
172   \new GrandStaff @{
173     \new Staff @{
174       \violin
175     @}
176   @}
177 @}
178 @end example
179
180 @item @strong{Separate tweaks from music definitions}.  This
181 point was made previously, but for large
182 projects it is absolutely vital.  We might need to change
183 the definition of @code{fthenp}, but then we only need
184 to do this once, and we can still avoid touching anything
185 inside @code{violin}.
186
187 @example
188 fthenp = _\markup@{
189   \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
190 violin = \relative c'' @{
191 g4\fthenp c'8. e16
192 @}
193 @end example
194
195 @end itemize
196
197
198 @node Troubleshooting
199 @section Troubleshooting
200
201 Sooner or later, you will write a file that LilyPond cannot
202 compile.  The messages that LilyPond gives may help
203 you find the error, but in many cases you need to do some
204 investigation to determine the source of the problem.
205
206 The most powerful tools for this purpose are the
207 single line comment (indicated by @code{%}) and the block
208 comment (indicated by @code{%@{ ... %@}}).  If you don't
209 know where a problem is, start commenting out huge portions
210 of your input file.  After you comment out a section, try
211 compiling the file again.  If it works, then the problem
212 must exist in the portion you just commented.  If it doesn't
213 work, then keep on commenting out material until you have
214 something that works.
215
216 In an extreme case, you might end up with only
217
218 @example
219 \score @{
220   <<
221     % \melody
222     % \harmony
223     % \bass
224   >>
225   \layout@{@}
226 @}
227 @end example
228
229 @noindent
230 (in other words, a file without any music)
231
232 If that happens, don't give up.  Uncomment a bit -- say,
233 the bass part -- and see if it works.  If it doesn't work,
234 then comment out all of the bass music (but leave
235 @code{\bass} in the @code{\score} uncommented.
236
237 @example
238 bass = \relative c' @{
239 %@{
240   c4 c c c
241   d d d d
242 %@}
243 @}
244 @end example
245
246 Now start slowly uncommenting more and more of the
247 @code{bass} part until you find the problem line.
248
249 Another very useful debugging technique is constructing
250 @rweb{Tiny examples}.
251
252
253 @node Make and Makefiles
254 @section Make and Makefiles
255
256 @cindex makefiles
257 @cindex make
258
259 Pretty well all the platforms Lilypond can run on support a software
260 facility called @code{make}. This software reads a special file called a
261 @code{Makefile} that defines what files depend on what others and what
262 commands you need to give the operating system to produce one file from
263 another. For example the makefile would spell out how to produce
264 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
265 running Lilypond.
266
267 There are times when it is a good idea to create a @code{Makefile}
268 for your project, either for your own convenience or
269 as a courtesy to others who might have access to your source files.
270 This is true for very large projects with many included files and
271 different output options (e.g. full score, parts, conductor's
272 score, piano reduction, etc.), or for projects that
273 require difficult commands to build them (such as
274 @code{lilypond-book} projects). Makefiles vary greatly in
275 complexity and flexibility, according to the needs and skills of
276 the authors. The program GNU Make comes installed on GNU/Linux
277 distributions and on MacOS X, and it is also available for Windows.
278
279 See the @strong{GNU Make Manual} for full details on using
280 @code{make}, as what follows here gives only a glimpse of what it
281 can do.
282
283 The commands to define rules in a makefile differ
284 according to platform; for instance the various forms of Linux and
285 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
286 MacOS X, you need to configure the system to use the command-line
287 intepreter. Here are some example makefiles, with versions for both
288 Linux/MacOS and Windows.
289
290 The first example is for an orchestral work in four
291 movements with a directory structure as follows:
292
293 @example
294 Symphony/
295 |-- MIDI/
296 |-- Makefile
297 |-- Notes/
298 |   |-- cello.ily
299 |   |-- figures.ily
300 |   |-- horn.ily
301 |   |-- oboe.ily
302 |   |-- trioString.ily
303 |   |-- viola.ily
304 |   |-- violinOne.ily
305 |   `-- violinTwo.ily
306 |-- PDF/
307 |-- Parts/
308 |   |-- symphony-cello.ly
309 |   |-- symphony-horn.ly
310 |   |-- symphony-oboes.ly
311 |   |-- symphony-viola.ly
312 |   |-- symphony-violinOne.ly
313 |   `-- symphony-violinTwo.ly
314 |-- Scores/
315 |   |-- symphony.ly
316 |   |-- symphonyI.ly
317 |   |-- symphonyII.ly
318 |   |-- symphonyIII.ly
319 |   `-- symphonyIV.ly
320 `-- symphonyDefs.ily
321 @end example
322
323 The @code{.ly} files in the @code{Scores} and
324 @code{Parts} directories get their notes from @code{.ily}
325 files in the @code{Notes} directory:
326
327 @example
328 %%% top of file "symphony-cello.ly"
329 \include ../definitions.ily
330 \include ../Notes/cello.ily
331 @end example
332
333 The makefile will have targets of @code{score} (entire piece in
334 full score), @code{movements} (individual movements in full score),
335 and @code{parts} (individual parts for performers). There
336 is also a target @code{archive} that will create a tarball of
337 the source files, suitable for sharing via web or email. Here is
338 the makefile for GNU/Linux or MacOS X. It should be saved with the
339 name @code{Makefile} in the top directory of the project:
340
341 @warning{When a target or pattern rule is defined, the
342 subsequent lines must begin with tabs, not spaces.}
343
344 @example
345 # the name stem of the output files
346 piece = symphony
347 # determine how many processors are present
348 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
349 # The command to run lilypond
350 LILY_CMD = lilypond -ddelete-intermediate-files \
351                     -dno-point-and-click -djob-count=$(CPU_CORES)
352
353 # The suffixes used in this Makefile.
354 .SUFFIXES: .ly .ily .pdf .midi
355
356 # Input and output files are searched in the directories listed in
357 # the VPATH variable.  All of them are subdirectories of the current
358 # directory (given by the GNU make variable `CURDIR').
359 VPATH = \
360   $(CURDIR)/Scores \
361   $(CURDIR)/PDF \
362   $(CURDIR)/Parts \
363   $(CURDIR)/Notes
364
365 # The pattern rule to create PDF and MIDI files from a LY input file.
366 # The .pdf output files are put into the `PDF' subdirectory, and the
367 # .midi files go into the `MIDI' subdirectory.
368 %.pdf %.midi: %.ly
369         $(LILY_CMD) $<; \           # this line begins with a tab
370         if test -f "$*.pdf"; then \
371             mv "$*.pdf" PDF/; \
372         fi; \
373         if test -f "$*.midi"; then \
374             mv "$*.midi" MIDI/; \
375         fi
376
377 notes = \
378   cello.ily \
379   horn.ily \
380   oboe.ily \
381   viola.ily \
382   violinOne.ily \
383   violinTwo.ily
384
385 # The dependencies of the movements.
386 $(piece)I.pdf: $(piece)I.ly $(notes)
387 $(piece)II.pdf: $(piece)II.ly $(notes)
388 $(piece)III.pdf: $(piece)III.ly $(notes)
389 $(piece)IV.pdf: $(piece)IV.ly $(notes)
390
391 # The dependencies of the full score.
392 $(piece).pdf: $(piece).ly $(notes)
393
394 # The dependencies of the parts.
395 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
396 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
397 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
398 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
399 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
400 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
401
402 # Type `make score' to generate the full score of all four
403 # movements as one file.
404 .PHONY: score
405 score: $(piece).pdf
406
407 # Type `make parts' to generate all parts.
408 # Type `make foo.pdf' to generate the part for instrument `foo'.
409 # Example: `make symphony-cello.pdf'.
410 .PHONY: parts
411 parts: $(piece)-cello.pdf \
412        $(piece)-violinOne.pdf \
413        $(piece)-violinTwo.pdf \
414        $(piece)-viola.pdf \
415        $(piece)-oboes.pdf \
416        $(piece)-horn.pdf
417
418 # Type `make movements' to generate files for the
419 # four movements separately.
420 .PHONY: movements
421 movements: $(piece)I.pdf \
422            $(piece)II.pdf \
423            $(piece)III.pdf \
424            $(piece)IV.pdf
425
426 all: score parts movements
427
428 archive:
429         tar -cvvf stamitz.tar \       # this line begins with a tab
430         --exclude=*pdf --exclude=*~ \
431         --exclude=*midi --exclude=*.tar \
432         ../Stamitz/*
433 @end example
434
435
436 There are special complications on the Windows platform. After
437 downloading and installing GNU Make for Windows, you must set the
438 correct path in the system's environment variables so that the
439 DOS shell can find the Make program. To do this, right-click on
440 "My Computer," then choose @code{Properties} and
441 @code{Advanced}. Click @code{Environment Variables}, and then
442 in the @code{System Variables} pane, highlight @code{Path}, click
443 @code{edit}, and add the path to the GNU Make executable file, which
444  will look something like this:
445
446 @example
447 C:\Program Files\GnuWin32\bin
448 @end example
449
450 The makefile itself has to be altered to handle different shell
451 commands and to deal with spaces that are present
452 in some default system directories. The @code{archive} target
453 is eliminated since Windows does not have the @code{tar} command,
454 and Windows also has a different default extension for midi files.
455
456
457 @example
458 ## WINDOWS VERSION
459 ##
460 piece = symphony
461 LILY_CMD = lilypond -ddelete-intermediate-files \
462                     -dno-point-and-click \
463                     -djob-count=$(NUMBER_OF_PROCESSORS)
464
465 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
466 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
467           do @@echo %%~sb)
468
469 .SUFFIXES: .ly .ily .pdf .mid
470
471 VPATH = \
472   $(workdir)/Scores \
473   $(workdir)/PDF \
474   $(workdir)/Parts \
475   $(workdir)/Notes
476
477 %.pdf %.mid: %.ly
478         $(LILY_CMD) $<      # this line begins with a tab
479         if exist "$*.pdf"  move /Y "$*.pdf"  PDF/ # begin with tab
480         if exist "$*.mid" move /Y "$*.mid" MIDI/  # begin with tab
481
482 notes = \
483   cello.ily \
484   figures.ily \
485   horn.ily \
486   oboe.ily \
487   trioString.ily \
488   viola.ily \
489   violinOne.ily \
490   violinTwo.ily
491
492 $(piece)I.pdf: $(piece)I.ly $(notes)
493 $(piece)II.pdf: $(piece)II.ly $(notes)
494 $(piece)III.pdf: $(piece)III.ly $(notes)
495 $(piece)IV.pdf: $(piece)IV.ly $(notes)
496
497 $(piece).pdf: $(piece).ly $(notes)
498
499 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
500 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
501 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
502 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
503 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
504 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
505
506 .PHONY: score
507 score: $(piece).pdf
508
509 .PHONY: parts
510 parts: $(piece)-cello.pdf \
511        $(piece)-violinOne.pdf \
512        $(piece)-violinTwo.pdf \
513        $(piece)-viola.pdf \
514        $(piece)-oboes.pdf \
515        $(piece)-horn.pdf
516
517 .PHONY: movements
518 movements: $(piece)I.pdf \
519            $(piece)II.pdf \
520            $(piece)III.pdf \
521            $(piece)IV.pdf
522
523 all: score parts movements
524 @end example
525
526
527 The next Makefile is for a @command{lilypond-book} document done in
528 LaTeX. This project has an index, which requires that the
529 @command{latex} command be run twice to update links. Output files are
530 all stored in the @code{out} directory for .pdf output and in the
531 @code{htmlout} directory for the html output.
532
533 @example
534 SHELL=/bin/sh
535 FILE=myproject
536 OUTDIR=out
537 WEBDIR=htmlout
538 VIEWER=acroread
539 BROWSER=firefox
540 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
541 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
542 PDF=cd $(OUTDIR) && pdflatex $(FILE)
543 HTML=cd $(WEBDIR) && latex2html $(FILE)
544 INDEX=cd $(OUTDIR) && makeindex $(FILE)
545 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
546
547 all: pdf web keep
548
549 pdf:
550         $(LILYBOOK_PDF)  # begin with tab
551         $(PDF)           # begin with tab
552         $(INDEX)         # begin with tab
553         $(PDF)           # begin with tab
554         $(PREVIEW)       # begin with tab
555
556 web:
557         $(LILYBOOK_HTML) # begin with tab
558         $(HTML)          # begin with tab
559         cp -R $(WEBDIR)/$(FILE)/ ./  # begin with tab
560         $(BROWSER) $(FILE)/$(FILE).html &  # begin with tab
561
562 keep: pdf
563         cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf  # begin with tab
564
565 clean:
566         rm -rf $(OUTDIR) # begin with tab
567
568 web-clean:
569         rm -rf $(WEBDIR) # begin with tab
570
571 archive:
572         tar -cvvf myproject.tar \ # begin this line with tab
573         --exclude=out/* \
574         --exclude=htmlout/* \
575         --exclude=myproject/* \
576         --exclude=*midi \
577         --exclude=*pdf \
578         --exclude=*~ \
579         ../MyProject/*
580 @end example
581
582 TODO: make this thing work on Windows
583
584 The previous makefile does not work on Windows. An alternative
585 for Windows users would be to create a simple batch file
586 containing the build commands. This will not
587 keep track of dependencies the way a makefile does, but it at
588 least reduces the build process to a single command. Save the
589 following code as @command{build.bat} or @command{build.cmd}.
590 The batch file can be run at the DOS prompt or by simply
591 double-clicking its icon.
592
593 @example
594 lilypond-book --output=out --pdf myproject.lytex
595 cd out
596 pdflatex myproject
597 makeindex myproject
598 pdflatex myproject
599 cd ..
600 copy out\myproject.pdf MyProject.pdf
601 @end example
602
603
604 @seealso
605
606 This manual:
607 @ref{Command-line usage},
608 @ref{lilypond-book}
609