]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/input.itely
2c8df57890e245772a2abb30b41dd2e3fdd891fa
[lilypond.git] / Documentation / notation / input.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.19.22"
12
13 @node General input and output
14 @chapter General input and output
15
16 This section deals with general LilyPond input and output issues,
17 rather than specific notation.
18
19 @menu
20 * Input structure::
21 * Titles and headers::
22 * Working with input files::
23 * Controlling output::
24 * Creating MIDI output::
25 * Extracting musical information::
26 @end menu
27
28
29 @node Input structure
30 @section Input structure
31
32 The main format of input for LilyPond are text files.  By convention,
33 these files end with @file{.ly}.
34
35 @menu
36 * Structure of a score::
37 * Multiple scores in a book::
38 * Multiple output files from one input file::
39 * Output file names::
40 * File structure::
41 @end menu
42
43
44 @node Structure of a score
45 @subsection Structure of a score
46
47 @funindex \score
48
49 A @code{\score} block must contain a single music expression
50 delimited by curly brackets:
51
52 @example
53 \score @{
54   @dots{}
55 @}
56 @end example
57
58 @warning{There must be @strong{only one} outer music expression in
59 a @code{\score} block, and it @strong{must} be surrounded by
60 curly brackets.}
61
62 This single music expression may be of any size, and may contain
63 other music expressions to any complexity.  All of these examples
64 are music expressions:
65
66 @example
67 @{ c'4 c' c' c' @}
68 @end example
69
70 @lilypond[verbatim,quote]
71 {
72   { c'4 c' c' c' }
73   { d'4 d' d' d' }
74 }
75 @end lilypond
76
77 @lilypond[verbatim,quote]
78 <<
79   \new Staff { c'4 c' c' c' }
80   \new Staff { d'4 d' d' d' }
81 >>
82 @end lilypond
83
84 @example
85 @{
86   \new GrandStaff <<
87     \new StaffGroup <<
88       \new Staff @{ \flute @}
89       \new Staff @{ \oboe @}
90     >>
91     \new StaffGroup <<
92       \new Staff @{ \violinI @}
93       \new Staff @{ \violinII @}
94     >>
95   >>
96 @}
97 @end example
98
99 Comments are one exception to this general rule.  (For others see
100 @ref{File structure}.)  Both single-line comments and comments
101 delimited by @code{%@{ @dots{} %@}} may be placed anywhere within an
102 input file.  They may be placed inside or outside a @code{\score}
103 block, and inside or outside the single music expression within a
104 @code{\score} block.
105
106 Remember that even in a file containing only a @code{\score} block, it
107 is implicitly enclosed in a \book block.  A \book block in a source
108 file produces at least one output file, and by default the name of the
109 output file produced is derived from the name of the input file, so
110 @file{fandangoforelephants.ly} will produce
111 @file{fandangoforelephants.pdf}.
112
113 (For more details  about @code{\book} blocks, see
114 @ref{Multiple scores in a book},
115 @ref{Multiple output files from one input file} @ref{File structure}.)
116
117 @seealso
118 Learning Manual:
119 @rlearning{Working on input files},
120 @rlearning{Music expressions explained},
121 @rlearning{Score is a (single) compound musical expression}.
122
123
124 @node Multiple scores in a book
125 @subsection Multiple scores in a book
126
127 @funindex \book
128 @cindex movements, multiple
129
130 A document may contain multiple pieces of music and text.  Examples
131 of these are an etude book, or an orchestral part with multiple
132 movements.  Each movement is entered with a @code{\score} block,
133
134 @example
135 \score @{
136   @var{@dots{}music@dots{}}
137 @}
138 @end example
139
140 and texts are entered with a @code{\markup} block,
141
142 @example
143 \markup @{
144   @var{@dots{}text@dots{}}
145 @}
146 @end example
147
148 @funindex \book
149
150 All the movements and texts which appear in the same @file{.ly} file
151 will normally be typeset in the form of a single output file.
152
153 @example
154 \score @{
155   @var{@dots{}}
156 @}
157 \markup @{
158   @var{@dots{}}
159 @}
160 \score @{
161   @var{@dots{}}
162 @}
163 @end example
164
165 One important exception is within lilypond-book documents,
166 where you explicitly have to add a @code{\book} block, otherwise only
167 the first @code{\score} or @code{\markup} will appear in the output.
168
169 The header for each piece of music can be put inside the @code{\score}
170 block.  The @code{piece} name from the header will be printed before
171 each movement.  The title for the entire book can be put inside the
172 @code{\book}, but if it is not present, the @code{\header} which is at
173 the top of the file is inserted.
174
175 @example
176 \header @{
177   title = "Eight miniatures"
178   composer = "Igor Stravinsky"
179 @}
180 \score @{
181   @dots{}
182   \header @{ piece = "Romanze" @}
183 @}
184 \markup @{
185    @dots{}text of second verse@dots{}
186 @}
187 \markup @{
188    @dots{}text of third verse@dots{}
189 @}
190 \score @{
191   @dots{}
192   \header @{ piece = "Menuetto" @}
193 @}
194 @end example
195
196 @funindex \bookpart
197
198 Pieces of music may be grouped into book parts using @code{\bookpart}
199 blocks.  Book parts are separated by a page break, and can start with a
200 title, like the book itself, by specifying a @code{\header} block.
201
202 @example
203 \bookpart @{
204   \header @{
205     title = "Book title"
206     subtitle = "First part"
207   @}
208   \score @{ @dots{} @}
209   @dots{}
210 @}
211 \bookpart @{
212   \header @{
213     subtitle = "Second part"
214   @}
215   \score @{ @dots{} @}
216   @dots{}
217 @}
218 @end example
219
220 @node Multiple output files from one input file
221 @subsection Multiple output files from one input file
222
223 If you want multiple output files from the same @file{.ly} file,
224 then you can add multiple @code{\book} blocks, where each
225 such \book block will result in a separate output file.
226 If you do not specify any @code{\book} block in the
227 input file, LilyPond will implicitly treat the whole
228 file as a single \book block, see
229 @ref{File structure}.
230
231 When producing multiple files from a single source file, LilyPond
232 ensures that none of the output files from any @code{\book} block
233 overwrites the output file produced by a preceding @code{\book} from
234 the same input file.
235
236 It does this by adding a suffix to the output name for each
237 @code{\book} which uses the default output file name derived from the
238 input source file.
239
240 The default behaviour is to append a version-number suffix for each
241 name which may clash, so
242
243 @example
244 \book @{
245   \score @{ @dots{} @}
246   \paper @{ @dots{} @}
247 @}
248 \book @{
249   \score @{ @dots{} @}
250   \paper @{ @dots{} @}
251 @}
252 \book @{
253   \score @{ @dots{} @}
254   \paper @{ @dots{} @}
255 @}
256 @end example
257
258 in source file @file{eightminiatures.ly}
259 will produce
260
261 @itemize
262 @item
263 @file{eightminiatures.pdf},
264 @item
265 @file{eightminiatures-1.pdf} and
266 @item
267 @file{eightminiatures-2.pdf}.
268 @end itemize
269
270 @node Output file names
271 @subsection Output file names
272
273 @funindex \bookOutputSuffix
274 @funindex \bookOutputName
275
276 LilyPond provides facilities to allow you to control what file names
277 are used by the various back-ends when producing output files.
278
279 In the previous section, we saw how LilyPond prevents name-clashes when
280 producing several outputs from a single source file.  You also have the
281 ability to specify your own suffixes for each @code{\book} block, so
282 for example you can produce files called
283 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
284 and @file{eightminiatures-Nocturne.pdf} by adding a
285 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
286
287 @example
288 \book @{
289   \bookOutputSuffix "Romanze"
290   \score @{ @dots{} @}
291   \paper @{ @dots{} @}
292 @}
293 \book @{
294   \bookOutputSuffix "Menuetto"
295   \score @{ @dots{} @}
296   \paper @{ @dots{} @}
297 @}
298 \book @{
299   \bookOutputSuffix "Nocturne"
300   \score @{ @dots{} @}
301   \paper @{ @dots{} @}
302 @}
303 @end example
304
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
307
308 @example
309 \book @{
310   \bookOutputName "Romanze"
311   \score @{ @dots{} @}
312   \paper @{ @dots{} @}
313 @}
314 \book @{
315   \bookOutputName "Menuetto"
316   \score @{ @dots{} @}
317   \paper @{ @dots{} @}
318 @}
319 \book @{
320   \bookOutputName "Nocturne"
321   \score @{ @dots{} @}
322   \paper @{ @dots{} @}
323 @}
324 @end example
325
326 The file above will produce these output files:
327
328 @itemize
329 @item
330 @file{Romanze.pdf},
331 @item
332 @file{Menuetto.pdf} and
333 @item
334 @file{Nocturne.pdf}.
335 @end itemize
336
337
338 @node File structure
339 @subsection File structure
340
341 @funindex \paper
342 @funindex \midi
343 @funindex \layout
344 @funindex \header
345 @funindex \score
346 @funindex \book
347 @funindex \bookpart
348
349 A @file{.ly} file may contain any number of toplevel expressions, where a
350 toplevel expression is one of the following:
351
352 @itemize
353 @item
354 An output definition, such as @code{\paper}, @code{\midi}, and
355 @code{\layout}.  Such a definition at the toplevel changes the default
356 book-wide settings.  If more than one such definition of the same type
357 is entered at the top level the definitions are combined, but in
358 conflicting situations the later definitions take precedence.  For
359 details of how this affects the @code{\layout} block see
360 @ref{The layout block,,The @code{@bs{}layout} block}.
361
362 @item
363 A direct scheme expression, such as
364 @code{#(set-default-paper-size "a7" 'landscape)} or
365 @code{#(ly:set-option 'point-and-click #f)}.
366
367 @item
368 A @code{\header} block.  This sets the global (i.e., the top of
369 file) header block.  This is the block containing the default
370 settings of titling fields like composer, title, etc., for all
371 books within the file (see @ref{Titles explained}).
372
373 @item
374 A @code{\score} block.  This score will be collected with other
375 toplevel scores, and combined as a single @code{\book}.
376 This behavior can be changed by setting the variable
377 @code{toplevel-score-handler} at toplevel.  (The default handler is
378 defined in the file @file{../scm/lily-library.scm} and set in the file
379 @file{../ly/declarations-init.ly}.)
380
381 @item
382 A @code{\book} block logically combines multiple movements
383 (i.e., multiple @code{\score} blocks) in one document.  If there
384 are a number of @code{\score}s, one output file will be created
385 for each @code{\book} block, in which all corresponding movements
386 are concatenated.  The only reason to explicitly specify
387 @code{\book} blocks in a @file{.ly} file is if you wish to create
388 multiple output files from a single input file.  One exception is
389 within lilypond-book documents, where you explicitly have to add
390 a @code{\book} block if you want more than a single @code{\score}
391 or @code{\markup} in the same example.  This behavior can be
392 changed by setting the variable @code{toplevel-book-handler} at
393 toplevel.  The default handler is defined in the init file
394 @file{../scm/lily.scm}.
395
396 @item
397 A @code{\bookpart} block.  A book may be divided into several parts,
398 using @code{\bookpart} blocks, in order to ease the page breaking,
399 or to use different @code{\paper} settings in different parts.
400
401 @item
402 A compound music expression, such as
403 @example
404 @{ c'4 d' e'2 @}
405 @end example
406
407 This will add the piece in a @code{\score} and format it in a
408 single book together with all other toplevel @code{\score}s and music
409 expressions.  In other words, a file containing only the above
410 music expression will be translated into
411
412 @example
413 \book @{
414   \score @{
415     \new Staff @{
416       \new Voice @{
417         @{ c'4 d' e'2 @}
418       @}
419     @}
420     \layout @{ @}
421   @}
422   \paper @{ @}
423   \header @{ @}
424 @}
425 @end example
426
427 This behavior can be changed by setting the variable
428 @code{toplevel-music-handler} at toplevel.  The default handler is
429 defined in the init file @file{../scm/lily.scm}.
430
431 @item
432 A markup text, a verse for example
433 @example
434 \markup @{
435    2.  The first line verse two.
436 @}
437 @end example
438
439 Markup texts are rendered above, between or below the scores or music
440 expressions, wherever they appear.
441
442 @cindex variables
443
444 @item
445 A variable, such as
446 @example
447 foo = @{ c4 d e d @}
448 @end example
449
450 This can be used later on in the file by entering @code{\foo}.  The
451 name of a variable should have alphabetic characters only; no
452 numbers, underscores or dashes.
453
454 @end itemize
455
456 The following example shows three things that may be entered at
457 toplevel
458
459 @example
460 \layout @{
461   % Don't justify the output
462   ragged-right = ##t
463 @}
464
465 \header @{
466    title = "Do-re-mi"
467 @}
468
469 @{ c'4 d' e2 @}
470 @end example
471
472
473 At any point in a file, any of the following lexical instructions can
474 be entered:
475
476 @itemize
477 @item @code{\version}
478 @item @code{\include}
479 @item @code{\sourcefilename}
480 @item @code{\sourcefileline}
481 @item
482 A single-line comment, introduced by a leading @code{%} sign.
483
484 @item
485 A multi-line comment delimited by @code{%@{ @dots{} %@}}.
486
487 @end itemize
488
489 @cindex whitespace
490
491 Whitespace between items in the input stream is generally ignored,
492 and may be freely omitted or extended to enhance readability.
493 However, whitespace should always be used in the following
494 circumstances to avoid errors:
495
496 @itemize
497
498 @item Around every opening and closing curly bracket.
499
500 @item After every command or variable, i.e., every item that
501 begins with a @code{\} sign.
502
503 @item After every item that is to be interpreted as a Scheme
504 expression, i.e., every item that begins with a @code{#}@tie{}sign.
505
506 @item To separate all elements of a Scheme expression.
507
508 @item In @code{lyricmode} before and after @code{\set} and
509 @code{\override} commands.
510
511 @end itemize
512
513 @seealso
514 Learning Manual:
515 @rlearning{How LilyPond input files work}.
516
517 Notation Reference:
518 @ref{Titles explained},
519 @ref{The layout block,,The @code{@bs{}layout} block}.
520
521
522 @node Titles and headers
523 @section Titles and headers
524
525 @cindex titles
526 @cindex headers
527 @cindex footers
528
529 Almost all printed music includes a title and the composer's name;
530 some pieces include a lot more information.
531
532 @menu
533 * Creating titles headers and footers::
534 * Custom titles headers and footers::
535 * Creating output file metadata::
536 * Creating footnotes::
537 * Reference to page numbers::
538 * Table of contents::
539 @end menu
540
541
542 @node Creating titles headers and footers
543 @subsection Creating titles headers and footers
544
545 @menu
546 * Titles explained::
547 * Default layout of bookpart and score titles::
548 * Default layout of headers and footers::
549 @end menu
550
551
552 @node Titles explained
553 @unnumberedsubsubsec Titles explained
554
555 Each @code{\book} block in a single input file produces a separate
556 output file, see @ref{File structure}.  Within each output file
557 three types of titling areas are provided: @emph{Book Titles} at the
558 beginning of each book, @emph{Bookpart Titles} at the beginning of
559 each bookpart and @emph{Score Titles} at the beginning of each score.
560
561 Values of titling fields such as @code{title} and @code{composer}
562 are set in @code{\header} blocks.  (For the syntax of @code{\header}
563 blocks and a complete list of the fields available by default see
564 @ref{Default layout of bookpart and score titles}).  Book Titles,
565 Bookpart Titles and Score Titles can all contain the same fields,
566 although by default the fields in Score Titles are limited to
567 @code{piece} and @code{opus}.
568
569 @code{\header} blocks may be placed in four different places to form
570 a descending hierarchy of @code{\header} blocks:
571
572 @itemize
573
574 @item
575 At the top of the input file, before all @code{\book},
576 @code{\bookpart}, and @code{\score} blocks.
577
578 @item
579 Within a @code{\book} block but outside all the @code{\bookpart} and
580 @code{\score} blocks within that book.
581
582 @item
583 Within a @code{\bookpart} block but outside all @code{\score} blocks
584 within that bookpart.
585
586 @item
587 After the music expression in a @code{\score} block.
588
589 @end itemize
590
591 The values of the fields filter down this hierarchy, with the values
592 set higher in the hierarchy persisting unless they are over-ridden
593 by a value set lower in the hierarchy, so:
594
595 @itemize
596
597 @item
598 A Book Title is derived from fields set at the top of the input file,
599 modified by fields set in the @code{\book} block.  The resulting
600 fields are used to print the Book Title for that book, providing that
601 there is other material which generates a page at the start of the
602 book, before the first bookpart.  A single @code{\pageBreak} will
603 suffice.
604
605 @item
606 A Bookpart Title is derived from fields set at the top of the input
607 file, modified by fields set in the @code{\book} block, and further
608 modified by fields set in the @code{\bookpart} block.  The resulting
609 values are used to print the Bookpart Title for that bookpart.
610
611 @item
612 A Score Title is derived from fields set at the top of the input
613 file, modified by fields set in the @code{\book} block, further
614 modified by fields set in the @code{\bookpart} block and finally
615 modified by fields set in the @code{\score} block.  The resulting
616 values are used to print the Score Title for that score.  Note,
617 though, that only @code{piece} and @code{opus} fields are printed
618 by default in Score Titles unless the @code{\paper} variable,
619 @code{print-all-headers}, is set to @code{#t}.
620
621 @end itemize
622
623 @warning{Remember when placing a @bs{}@code{header} block inside a
624 @bs{}@code{score} block, that the music expression must come before the
625 @bs{}@code{header} block.}
626
627 It is not necessary to provide @code{\header} blocks in all four
628 places: any or even all of them may be omitted.  Similarly, simple
629 input files may omit the @code{\book} and @code{\bookpart} blocks,
630 leaving them to be created implicitly.
631
632 If the book has only a single score, the @code{\header} block should
633 normally be placed at the top of the file so that just a Bookpart
634 Title is produced, making all the titling fields available for use.
635
636 If the book has multiple scores a number of different arrangements
637 of @code{\header} blocks are possible, corresponding to the various
638 types of musical publications.  For example, if the publication
639 contains several pieces by the same composer a @code{\header} block
640 placed at the top of the file specifying the book title and the
641 composer with @code{\header} blocks in each @code{\score} block
642 specifying the @code{piece} and/or @code{opus} would be most
643 suitable, as here:
644
645 @lilypond[papersize=a5,quote,verbatim,noragged-right]
646 \header {
647   title = "SUITE I."
648   composer = "J. S. Bach."
649 }
650
651 \score {
652   \new Staff \relative {
653     \clef bass
654     \key g \major
655     \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
656     \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
657   }
658   \header {
659     piece = "Prélude."
660   }
661 }
662
663 \score {
664   \new Staff \relative {
665     \clef bass
666     \key g \major
667     \partial 16 b16 |
668     <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
669     d16( b g fis) g( e d c) b(c d e) fis( g a b) |
670   }
671   \header {
672     piece = "Allemande."
673   }
674 }
675 @end lilypond
676
677 More complicated arrangements are possible.  For example, text
678 fields from the @code{\header} block in a book can be displayed in
679 all Score Titles, with some fields over-ridden and some manually
680 suppressed:
681
682 @lilypond[papersize=a5,quote,verbatim,noragged-right]
683 \book {
684   \paper {
685     print-all-headers = ##t
686   }
687   \header {
688     title = "DAS WOHLTEMPERIRTE CLAVIER"
689     subtitle = "TEIL I"
690     % Do not display the default LilyPond footer for this book
691     tagline = ##f
692   }
693   \markup { \vspace #1 }
694   \score {
695     \new PianoStaff <<
696       \new Staff { s1 }
697       \new Staff { \clef "bass" s1 }
698     >>
699     \header {
700       title = "PRAELUDIUM I"
701       opus = "BWV 846"
702       % Do not display the subtitle for this score
703       subtitle = ##f
704     }
705   }
706   \score {
707     \new PianoStaff <<
708       \new Staff { s1 }
709       \new Staff { \clef "bass" s1 }
710     >>
711     \header {
712       title = "FUGA I"
713       subsubtitle = "A 4 VOCI"
714       opus = "BWV 846"
715       % Do not display the subtitle for this score
716       subtitle = ##f
717     }
718   }
719 }
720 @end lilypond
721
722 @seealso
723 Notation Reference:
724 @ref{File structure},
725 @ref{Default layout of bookpart and score titles},
726 @ref{Custom layout for titles}.
727
728
729 @node Default layout of bookpart and score titles
730 @unnumberedsubsubsec Default layout of bookpart and score titles
731
732 This example demonstrates all printed @code{\header} variables:
733
734 @lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
735 \book {
736   \header {
737       % The following fields are centered
738     dedication = "Dedication"
739     title = "Title"
740     subtitle = "Subtitle"
741     subsubtitle = "Subsubtitle"
742       % The following fields are evenly spread on one line
743       % the field "instrument" also appears on following pages
744     instrument = \markup \with-color #green "Instrument"
745     poet = "Poet"
746     composer = "Composer"
747       % The following fields are placed at opposite ends of the same line
748     meter = "Meter"
749     arranger = "Arranger"
750       % The following fields are centered at the bottom
751     tagline = "The tagline goes at the bottom of the last page"
752     copyright = "The copyright goes at the bottom of the first page"
753   }
754   \score {
755     { s1 }
756     \header {
757         % The following fields are placed at opposite ends of the same line
758       piece = "Piece 1"
759       opus = "Opus 1"
760     }
761   }
762   \score {
763     { s1 }
764     \header {
765         % The following fields are placed at opposite ends of the same line
766       piece = "Piece 2 on the same page"
767       opus = "Opus 2"
768     }
769   }
770   \pageBreak
771   \score {
772     { s1 }
773     \header {
774         % The following fields are placed at opposite ends of the same line
775       piece = "Piece 3 on a new page"
776       opus = "Opus 3"
777     }
778   }
779 }
780 @end lilypond
781
782 Note that
783
784 @itemize
785 @item
786 The instrument name will be repeated on every page.
787
788 @item
789 Only @code{piece} and @code{opus} are printed in a @code{\score}
790 when the paper variable @code{print-all-headers} is set to
791 @code{##f} (the default).
792
793 @item
794 @c Is the bit about \null markups true? -mp
795 Text fields left unset in a @code{\header} block are replaced with
796 @code{\null} markups so that the space is not wasted.
797
798 @item
799 The default settings for @code{scoreTitleMarkup} place the @code{piece}
800 and @code{opus} text fields at opposite ends of the same line.
801
802 @end itemize
803
804 To change the default layout see @ref{Custom layout for titles}.
805
806 @cindex breakbefore
807
808 If a @code{\book} block starts immediately with a @code{\bookpart}
809 block, no Book Title will be printed, as there is no page on which
810 to print it.  If a Book Title is required, begin the @code{\book}
811 block with some markup material or a @code{\pageBreak} command.
812
813 Use the @code{breakbefore} variable inside a @code{\header} block
814 that is itself in a @code{\score} block, to make the higher-level
815 @code{\header} block titles appear on the first page on their own, with
816 the music (defined in the @code{\score} block) starting on the next.
817
818 @lilypond[papersize=c7landscape,verbatim,noragged-right]
819 \book {
820   \header {
821     title = "This is my Title"
822     subtitle = "This is my Subtitle"
823     copyright = "This is the bottom of the first page"
824   }
825   \score {
826     \repeat unfold 4 { e'' e'' e'' e'' }
827     \header {
828       piece = "This is the Music"
829       breakbefore = ##t
830     }
831   }
832 }
833 @end lilypond
834
835 @seealso
836 Learning Manual:
837 @rlearning{How LilyPond input files work},
838
839 Notation Reference:
840 @ref{Custom layout for titles},
841 @ref{File structure}.
842
843 Installed Files:
844 @file{ly/titling-init.ly}.
845
846
847 @node Default layout of headers and footers
848 @unnumberedsubsubsec Default layout of headers and footers
849
850 @emph{Headers} and @emph{footers} are lines of text appearing at
851 the top and bottom of pages, separate from the main text of a book.
852 They are controlled by the following @code{\paper} variables:
853
854 @itemize
855 @item @code{oddHeaderMarkup}
856 @item @code{evenHeaderMarkup}
857 @item @code{oddFooterMarkup}
858 @item @code{evenFooterMarkup}
859 @end itemize
860
861 These markup variables can only access text fields from top-level
862 @code{\header} blocks (which apply to all scores in the book) and are
863 defined in @file{ly/titling-init.ly}.  By default:
864
865 @itemize
866
867 @item
868 page numbers are automatically placed on the top far left (if even) or
869 top far right (if odd), starting from the second page.
870
871 @item
872 the @code{instrument} text field is placed in the center of every
873 page, starting from the second page.
874
875 @item
876 the @code{copyright} text is centered on the bottom of the first page.
877
878 @item
879 the @code{tagline} is centered on the bottom of the last page, and below
880 the @code{copyright} text if there is only a single page.
881
882 @end itemize
883
884 The default LilyPond footer text can be changed by adding a
885 @code{tagline} in the top-level @code{\header} block.
886
887 @lilypond[papersize=a8landscape,verbatim]
888 \book {
889   \header {
890     tagline = "... music notation for Everyone"
891   }
892   \score {
893     \relative {
894       c'4 d e f
895     }
896   }
897 }
898 @end lilypond
899
900 To remove the default LilyPond footer text, the @code{tagline} can be
901 set to @code{##f}.
902
903
904 @node Custom titles headers and footers
905 @subsection Custom titles headers and footers
906
907 @c TODO: somewhere put a link to header spacing info
908 @c       (you'll have to explain it more in NR 4).
909
910 @menu
911 * Custom text formatting for titles::
912 * Custom layout for titles::
913 * Custom layout for headers and footers::
914 @end menu
915
916
917 @node Custom text formatting for titles
918 @unnumberedsubsubsec Custom text formatting for titles
919
920 Standard @code{\markup} commands can be used to customize any header,
921 footer and title text within the @code{\header} block.
922
923 @lilypond[quote,verbatim,noragged-right]
924 \score {
925   { s1 }
926   \header {
927     piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
928     opus = \markup { \italic "BWV 846" }
929   }
930 }
931 @end lilypond
932
933 @seealso
934 Notation Reference:
935 @ref{Formatting text}.
936
937
938 @node Custom layout for titles
939 @unnumberedsubsubsec Custom layout for titles
940
941 @cindex bookTitleMarkup
942 @cindex scoreTitleMarkup
943 @funindex bookTitleMarkup
944 @funindex scoreTitleMarkup
945
946 @code{\markup} commands in the @code{\header} block are useful for
947 simple text formatting, but they do not allow precise control over the
948 placement of titles.  To customize the placement of the text fields,
949 change either or both of the following @code{\paper} variables:
950
951 @itemize
952 @item @code{bookTitleMarkup}
953 @item @code{scoreTitleMarkup}
954 @end itemize
955
956 The placement of titles when using the default values of these
957 @code{\markup} variables is shown in the examples in
958 @ref{Default layout of bookpart and score titles}.
959
960 The default settings for @code{scoreTitleMarkup} as defined in
961 @file{ly/titling-init.ly} are:
962
963 @example
964 scoreTitleMarkup = \markup @{ \column @{
965   \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
966   \fill-line @{
967     \fromproperty #'header:piece
968     \fromproperty #'header:opus
969   @}
970 @}
971 @}
972 @end example
973
974 This places the @code{piece} and @code{opus} text fields at opposite
975 ends of the same line:
976
977 @lilypond[quote,verbatim,noragged-right]
978 \score {
979   { s1 }
980   \header {
981     piece = "PRAELUDIUM I"
982     opus = "BWV 846"
983   }
984 }
985 @end lilypond
986
987 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
988 text field is centered and in a large, bold font.
989
990 @lilypond[papersize=a5,quote,verbatim,noragged-right]
991 \book {
992   \paper {
993     indent = 0\mm
994     scoreTitleMarkup = \markup {
995       \fill-line {
996         \null
997         \fontsize #4 \bold \fromproperty #'header:piece
998         \fromproperty #'header:opus
999       }
1000     }
1001   }
1002   \header { tagline = ##f }
1003   \score {
1004     { s1 }
1005     \header {
1006       piece = "PRAELUDIUM I"
1007       opus = "BWV 846"
1008     }
1009   }
1010 }
1011 @end lilypond
1012
1013 Text fields not normally effective in score @code{\header} blocks
1014 can be printed in the Score Title area if @code{print-all-headers} is
1015 placed inside the @code{\paper} block.  A disadvantage of using this
1016 method is that text fields that are intended specifically for the
1017 Bookpart Title area need to be manually suppressed in every
1018 @code{\score} block.  See @ref{Titles explained}.
1019
1020 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
1021 definition.  In the following example, the @code{composer} text field
1022 (normally associated with @code{bookTitleMarkup}) is added to
1023 @code{scoreTitleMarkup}, allowing each score to list a different
1024 composer:
1025
1026 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1027 \book {
1028   \paper {
1029     indent = 0\mm
1030     scoreTitleMarkup = \markup {
1031       \fill-line {
1032         \null
1033         \fontsize #4 \bold \fromproperty #'header:piece
1034         \fromproperty #'header:composer
1035       }
1036     }
1037   }
1038   \header { tagline = ##f }
1039   \score {
1040     { s1 }
1041     \header {
1042       piece = "MENUET"
1043       composer = "Christian Petzold"
1044     }
1045   }
1046   \score {
1047     { s1 }
1048     \header {
1049       piece = "RONDEAU"
1050       composer = "François Couperin"
1051     }
1052   }
1053 }
1054 @end lilypond
1055
1056 It is also possible to create your own custom text fields, and refer to
1057 them in the markup definition.
1058
1059 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1060 \book {
1061   \paper {
1062     indent = 0\mm
1063     scoreTitleMarkup = \markup {
1064       \fill-line {
1065         \null
1066         \override #`(direction . ,UP) {
1067           \dir-column {
1068             \center-align \fontsize #-1 \bold
1069               \fromproperty #'header:mycustomtext %% User-defined field
1070             \center-align \fontsize #4 \bold
1071               \fromproperty #'header:piece
1072           }
1073         }
1074         \fromproperty #'header:opus
1075       }
1076     }
1077   }
1078   \header { tagline = ##f }
1079   \score {
1080     { s1 }
1081     \header {
1082       piece = "FUGA I"
1083       mycustomtext = "A 4 VOCI" %% User-defined field
1084       opus = "BWV 846"
1085     }
1086   }
1087 }
1088 @end lilypond
1089
1090 @seealso
1091 Notation Reference:
1092 @ref{Titles explained}.
1093
1094
1095 @node Custom layout for headers and footers
1096 @unnumberedsubsubsec Custom layout for headers and footers
1097
1098 @c can make-header and make-footer be removed from
1099 @c paper-defaults-init.ly? -mp
1100
1101 @code{\markup} commands in the @code{\header} block are useful for
1102 simple text formatting, but they do not allow precise control over the
1103 placement of headers and footers.  To customize the placement of
1104 the text fields, use either or both of the following @code{\paper}
1105 variables:
1106
1107 @itemize
1108 @item @code{oddHeaderMarkup}
1109 @item @code{evenHeaderMarkup}
1110 @item @code{oddFooterMarkup}
1111 @item @code{evenFooterMarkup}
1112 @end itemize
1113
1114 @cindex markup, conditional
1115 @cindex on-the-fly
1116 @funindex \on-the-fly
1117
1118 The @code{\markup} command @code{\on-the-fly} can be used to add
1119 markup conditionally to header and footer text defined within the
1120 @code{\paper} block, using the following syntax:
1121
1122 @example
1123 variable = \markup @{
1124   @dots{}
1125   \on-the-fly  \@var{procedure}  @var{markup}
1126   @dots{}
1127 @}
1128 @end example
1129
1130 The @var{procedure} is called each time the @code{\markup} command
1131 in which it appears is evaluated.  The @var{procedure} should test
1132 for a particular condition and interpret (i.e., print) the
1133 @var{markup} argument if and only if the condition is true.
1134
1135 A number of ready-made procedures for testing various conditions are
1136 provided:
1137
1138 @quotation
1139 @multitable {print-page-number-check-first-----} {should this page be printed-----}
1140
1141 @headitem  Procedure name           @tab  Condition tested
1142
1143 @item print-page-number-check-first @tab  should this page number be printed?
1144 @item create-page-number-stencil    @tab  print-page-numbers true?
1145 @item print-all-headers             @tab  print-all-headers true?
1146 @item first-page                    @tab  first page in the book?
1147 @item not-first-page                @tab  not first page in the book?
1148 @item (on-page nmbr)                @tab  page number = nmbr?
1149 @item last-page                     @tab  last page in the book?
1150 @item part-first-page               @tab  first page in the book part?
1151 @item not-part-first-page           @tab  not first page in the book part?
1152 @item part-last-page                @tab  last page in the book part?
1153 @item not-single-page               @tab  pages in book part > 1?
1154
1155 @end multitable
1156 @end quotation
1157
1158 The following example centers page numbers at the bottom of every
1159 page.  First, the default settings for @code{oddHeaderMarkup} and
1160 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1161 markup.  Then, @code{oddFooterMarkup} is redefined with the page
1162 number centered.  Finally, @code{evenFooterMarkup} is given the
1163 same layout by defining it as @code{\oddFooterMarkup}:
1164
1165 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1166 \book {
1167   \paper {
1168     print-page-number = ##t
1169     print-first-page-number = ##t
1170     oddHeaderMarkup = \markup \null
1171     evenHeaderMarkup = \markup \null
1172     oddFooterMarkup = \markup {
1173       \fill-line {
1174         \on-the-fly \print-page-number-check-first
1175         \fromproperty #'page:page-number-string
1176       }
1177     }
1178     evenFooterMarkup = \oddFooterMarkup
1179   }
1180   \score {
1181     \new Staff { s1 \break s1 \break s1 }
1182   }
1183 }
1184 @end lilypond
1185
1186 Several @code{\on-the-fly} conditions can be combined with an
1187 @q{and} operation, for example,
1188
1189 @example
1190   \on-the-fly \first-page
1191   \on-the-fly \last-page
1192   @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
1193 @end example
1194
1195 determines if the output is a single page.
1196
1197 @seealso
1198 Notation Reference:
1199 @ref{Titles explained},
1200 @ref{Default layout of bookpart and score titles}.
1201
1202 Installed Files:
1203 @file{../ly/titling-init.ly}.
1204
1205 @node Creating output file metadata
1206 @subsection Creating output file metadata
1207
1208 @cindex PDF metadata
1209 @cindex MIDI metadata
1210
1211 In addition to being shown in the printed output, @code{\header} variables
1212 are also used to set metadata for output files.  For example, with PDF
1213 files, this metadata could be displayed by PDF readers as the
1214 @code{properties} of the PDF file.  For each type of output file, only the
1215 @code{\header} definitions of blocks that define separate files of that
1216 type, and blocks higher in the block hierarchy, will be consulted.
1217 Therefore, for PDF files, only the @code{\book} level and the top level
1218 @code{\header} definitions affect the document-wide PDF metadata, whereas
1219 for MIDI files, all headers above or at the @code{\score} level are used.
1220
1221 For example, setting the @code{title} property of the @code{header} block
1222 to @q{Symphony I} will also give this title to the PDF document, and use
1223 it as the sequence name of the MIDI file.
1224
1225 @example
1226 \header@{
1227   title = "Symphony I"
1228 @}
1229 @end example
1230
1231 If you want to set the title of the printed output to one value, but have the
1232 title property of the PDF to have a different value, you can use
1233 @code{pdftitle}, as below.
1234
1235 @example
1236 \header@{
1237   title = "Symphony I"
1238   pdftitle = "Symphony I by Beethoven"
1239 @}
1240 @end example
1241
1242 The variables @code{title}, @code{subject}, @code{keywords},
1243 @code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
1244 and @code{copyright} all set PDF properties and can all be prefixed with
1245 @q{pdf} to set a PDF property to a value different from the printed output.
1246
1247 The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
1248 the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
1249 both set to the current date and time.  @code{ModDate} can be overridden by
1250 setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
1251 valid PDF date string.
1252
1253 The @code{title} variable sets also the sequence name for MIDI.  The
1254 @code{midititle} variable can be used to set the sequence name
1255 independently of the value used for typeset output.
1256
1257 @node Creating footnotes
1258 @subsection Creating footnotes
1259
1260 @cindex footnotes
1261
1262 Footnotes may be used in many different situations.  In all cases,
1263 a @q{footnote mark} is placed as a reference in text or music, and
1264 the corresponding @q{footnote text} appears at the bottom of the
1265 same page.
1266
1267 Footnotes within music expressions and footnotes in stand-alone text
1268 outside music expressions are created in different ways.
1269
1270 @menu
1271 * Footnotes in music expressions::
1272 * Footnotes in stand-alone text::
1273 @end menu
1274
1275 @node Footnotes in music expressions
1276 @unnumberedsubsubsec Footnotes in music expressions
1277
1278 @cindex footnotes in music expressions
1279 @funindex \footnote
1280
1281 @subsubsubheading Music footnotes overview
1282
1283 Footnotes in music expressions fall into two categories:
1284
1285 @table @emph
1286 @item Event-based footnotes
1287 are attached to a particular event.  Examples for such events are
1288 single notes, articulations (like fingering indications, accents,
1289 dynamics), and post-events (like slurs and manual beams).  The
1290 general form for event-based footnotes is as follows:
1291
1292 @example
1293 [@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1294 @end example
1295
1296 @item Time-based footnotes
1297 are bound to a particular point of time in a musical context.  Some
1298 commands like @code{\time} and @code{\clef} don't actually use events
1299 for creating objects like time signatures and clefs.  Neither does a
1300 chord create an event of its own: its stem or flag is created at the
1301 end of a time step (nominally through one of the note events inside).
1302 Exactly which of a chord's multiple note events will be deemed the
1303 root cause of a stem or flag is undefined.  So for annotating those,
1304 time-based footnotes are preferable as well.
1305
1306 A time-based footnote allows such layout objects to be annotated
1307 without referring to an event.  The general form for Time-based
1308 footnotes is:
1309
1310 @example
1311 \footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
1312 @end example
1313
1314 @end table
1315
1316 The elements for both forms are:
1317
1318 @table @var
1319
1320 @item direction
1321 If (and only if) the @code{\footnote} is being applied to a
1322 post-event or articulation, it must be preceded with a direction
1323 indicator (@code{-, _, ^}) in order to attach @var{music} (with
1324 a footnote mark) to the preceding note or rest.
1325
1326 @item mark
1327 is a markup or string specifying the footnote mark which is used for
1328 marking both the reference point and the footnote itself at the
1329 bottom of the page.  It may be omitted (or equivalently replaced with
1330 @code{\default}) in which case a number in sequence will be generated
1331 automatically.  Such numerical sequences restart on each page
1332 containing a footnote.
1333
1334 @item offset
1335 is a number pair such as @samp{#(2 . 1)} specifying the X and
1336 Y@tie{}offsets in units of staff-spaces from the boundary of the
1337 object where the mark should be placed.  Positive values of the
1338 offsets are taken from the right/top edge, negative values from the
1339 left/bottom edge and zero implies the mark is centered on the edge.
1340
1341 @item Context
1342 is the context in which the grob being footnoted is created.  It
1343 may be omitted if the grob is in a bottom context, e.g., a
1344 @code{Voice} context.
1345
1346 @item GrobName
1347 specifies a type of grob to mark (like @samp{Flag}).  If it is
1348 specified, the footnote is not attached to a music expression in
1349 particular, but rather to all grobs of the type specified which
1350 occur at that moment of musical time.
1351
1352 @item footnote
1353 is the markup or string specifying the footnote text to use at the
1354 bottom of the page.
1355
1356 @item music
1357 is the music event or post-event or articulation
1358 that is being annotated.
1359
1360 @end table
1361
1362 @subsubsubheading Event-based footnotes
1363
1364 @cindex footnotes, event-based
1365
1366 A footnote may be attached to a layout object directly caused
1367 by the event corresponding to @var{music} with the syntax:
1368
1369 @example
1370 \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1371 @end example
1372
1373 @lilypond[quote,verbatim,papersize=a8landscape]
1374 \book {
1375   \header { tagline = ##f }
1376   \relative c'' {
1377     \footnote #'(-1 . 3) "A note" a4
1378     a4
1379     \footnote #'(2 . 2) "A rest" r4
1380     a4
1381   }
1382 }
1383 @end lilypond
1384
1385 Marking a @emph{whole} chord with an event-based footnote is not
1386 possible: a chord, even one containing just a single note, does
1387 not produce an actual event of its own.  However, individual
1388 notes @emph{inside} of the chord can be marked:
1389
1390 @lilypond[quote,verbatim,papersize=a8landscape]
1391 \book {
1392   \header { tagline = ##f }
1393   \relative c'' {
1394     \footnote #'(2 . 3) "Does not work" <a-3>2
1395     <\footnote #'(-2 . -3) "Does work" a-3>4
1396     <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
1397   }
1398 }
1399 @end lilypond
1400
1401 If the footnote is to be attached to a post-event or articulation
1402 the @code{\footnote} command @emph{must} be preceded by a direction
1403 indicator, @code{-, _, ^}, and followed by the post-event or
1404 articulation to be annotated as the @var{music} argument.  In this
1405 form the @code{\footnote} can be considered to be simply a copy of
1406 its last argument with a footnote mark attached to it.  The syntax
1407 is:
1408
1409 @example
1410 @var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1411 @end example
1412
1413 @lilypond[quote,verbatim,papersize=a8landscape]
1414 \book {
1415   \header { tagline = ##f }
1416   \relative {
1417     a'4_\footnote #'(0 . -1) "A slur forced down" (
1418     b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
1419     b8 ]
1420     c4 )
1421     c-\footnote #'(1 . 1) "Tenuto" --
1422   }
1423 }
1424 @end lilypond
1425
1426 @subsubsubheading Time-based footnotes
1427
1428 @cindex footnotes, time-based
1429
1430 If the layout object being footmarked is @emph{indirectly} caused by
1431 an event (like an @code{Accidental} or @code{Stem} caused by a
1432 @code{NoteHead} event), the @var{GrobName} of the layout object
1433 is required after the footnote text instead of @var{music}:
1434
1435 @lilypond[quote,verbatim,papersize=a8landscape]
1436 \book {
1437   \header { tagline = ##f }
1438   \relative c'' {
1439     \footnote #'(-1 . -3) "A flat" Accidental
1440     aes4 c
1441     \footnote #'(-1 . 0.5) "Another flat" Accidental
1442     ees
1443     \footnote #'(1 . -2) "A stem" Stem
1444     aes
1445   }
1446 }
1447 @end lilypond
1448
1449 Note, however, that when a GrobName is specified, a footnote
1450 will be attached to all grobs of that type at the current time step:
1451
1452 @lilypond[quote,verbatim,papersize=a8landscape]
1453 \book {
1454   \header { tagline = ##f }
1455   \relative c' {
1456     \footnote #'(-1 . 3) "A flat" Accidental
1457     <ees ges bes>4
1458     \footnote #'(2 . 0.5) "Articulation" Script
1459     c'->-.
1460   }
1461 }
1462 @end lilypond
1463
1464 A note inside of a chord can be given an individual (event-based)
1465 footnote.  A @samp{NoteHead} is the only grob directly caused
1466 from a chord note, so an event-based footnote command is
1467 @emph{only} suitable for adding a footnote to the @samp{NoteHead}
1468 within a chord.  All other chord note grobs are indirectly caused.
1469 The @code{\footnote} command itself offers no syntax for
1470 specifying @emph{both} a particular grob type @emph{as well as} a
1471 particular event to attach to.  However, one can use a time-based
1472 @code{\footnote} command for specifying the grob type, and then
1473 prefix this command with @code{\single} in order to have it
1474 applied to just the following event:
1475
1476 @lilypond[quote,verbatim,papersize=a8landscape]
1477 \book {
1478   \header { tagline = ##f }
1479   \relative c'' {
1480     < \footnote #'(1 . -2) "An A" a
1481       \single \footnote #'(-1 . -1) "A sharp" Accidental
1482       cis
1483       \single \footnote #'(0.5 . 0.5) "A flat" Accidental
1484       ees fis
1485     >2
1486   }
1487 }
1488 @end lilypond
1489
1490 @warning {When footnotes are attached to several musical elements at
1491 the same musical moment, as they are in the example above, the
1492 footnotes are numbered from the higher to the lower elements as they
1493 appear in the printed output, not in the order in which they are
1494 written in the input stream.}
1495
1496 Layout objects like clefs and key-change signatures are mostly caused
1497 as a consequence of changed properties rather than actual events.
1498 Others, like bar lines and bar numbers, are a direct consequence of
1499 timing.  For this reason, footnotes on such objects have to be based
1500 on their musical timing.  Time-based footnotes are also preferable
1501 when marking features like stems and beams on @emph{chords}: while
1502 such per-chord features are nominally assigned to @emph{one} event
1503 inside the chord, relying on a particular choice would be imprudent.
1504
1505 The layout object in question must always be explicitly specified
1506 for time-based footnotes, and the appropriate context must be
1507 specified if the grob is created in a context other than the bottom
1508 context.
1509
1510 @lilypond[quote,verbatim,papersize=a8landscape]
1511 \book {
1512   \header { tagline = ##f }
1513   \relative c'' {
1514     r1 |
1515     \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
1516     \time 3/4
1517     \footnote #'(1 . -1) "Chord stem" Stem
1518     <c e g>4 q q
1519     \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
1520     q q
1521     \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
1522     \key c \minor
1523     q
1524   }
1525 }
1526 @end lilypond
1527
1528 Custom marks can be used as alternatives to numerical marks, and the
1529 annotation line joining the marked object to the mark can be
1530 suppressed:
1531
1532 @lilypond[quote,verbatim,papersize=a8landscape]
1533 \book {
1534   \header { tagline = ##f }
1535   \relative c' {
1536     \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
1537     b8
1538     \footnote \markup { \super "$" } #'(0.5 . 1)
1539       \markup { \super "$" \italic " The second note" } e
1540     c4
1541     \once \override Score.FootnoteItem.annotation-line = ##f
1542     b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
1543       \markup { \super "+" \italic " Editorial" } \p
1544   }
1545 }
1546 @end lilypond
1547
1548 More examples of custom marks are shown in
1549 @ref{Footnotes in stand-alone text}.
1550
1551
1552 @node Footnotes in stand-alone text
1553 @unnumberedsubsubsec Footnotes in stand-alone text
1554
1555 @cindex footnotes in stand-alone text
1556
1557 These are for use in markup outside of music expressions.  They do
1558 not have a line drawn to their point of reference: their marks simply
1559 follow the referenced markup.  Marks can be inserted automatically,
1560 in which case they are numerical.  Alternatively, custom marks can be
1561 provided manually.
1562
1563 Footnotes to stand-alone text with automatic and custom marks are
1564 created in different ways.
1565
1566 @subsubsubheading Footnotes in stand-alone text with automatic marks
1567
1568 The syntax of a footnote in stand-alone text with automatic marks is
1569
1570 @example
1571 \markup @{ @dots{} \auto-footnote @var{text} @var{footnote} @dots{} @}
1572 @end example
1573
1574 The elements are:
1575
1576 @table @var
1577
1578 @item text
1579 is the markup or string to be marked.
1580
1581 @item footnote
1582 is the markup or string specifying the footnote text to use at the bottom
1583 of the page.
1584
1585 @end table
1586
1587 For example:
1588
1589 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1590 \book {
1591   \header { tagline = ##f }
1592   \markup {
1593     "A simple"
1594     \auto-footnote "tune" \italic " By me"
1595     "is shown below.  It is a"
1596     \auto-footnote "recent" \italic " Aug 2012"
1597     "composition."
1598   }
1599   \relative {
1600     a'4 b8 e c4 d
1601   }
1602 }
1603 @end lilypond
1604
1605 @subsubsubheading Footnotes in stand-alone text with custom marks
1606
1607 The syntax of a footnote in stand-alone text with custom marks is
1608
1609 @example
1610 \markup @{ @dots{} \footnote @var{mark} @var{footnote} @dots{} @}
1611 @end example
1612
1613 The elements are:
1614
1615 @table @var
1616
1617 @item mark
1618 is a markup or string specifying the footnote mark which is used for
1619 marking the reference point.  Note that this mark is @emph{not}
1620 inserted automatically before the footnote itself.
1621
1622 @item footnote
1623 is the markup or string specifying the footnote text to use at the
1624 bottom of the page, preceded by the @var{mark}.
1625
1626 @end table
1627
1628 Any easy-to-type character such as * or + may be used as a mark, as
1629 shown in @ref{Footnotes in music expressions}.  Alteratively, ASCII
1630 aliases may be used (see @ref{ASCII aliases}):
1631
1632 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1633 \book {
1634   \paper { #(include-special-characters) }
1635   \header { tagline = ##f }
1636   \markup {
1637     "A simple tune"
1638     \footnote "*" \italic "* By me"
1639     "is shown below.  It is a recent"
1640     \footnote \super &dagger; \concat {
1641       \super &dagger; \italic " Aug 2012"
1642     }
1643     "composition."
1644   }
1645   \relative {
1646     a'4 b8 e c4 d
1647   }
1648 }
1649 @end lilypond
1650
1651 Unicode character codes may also be used to specify marks
1652 (see @ref{Unicode}):
1653
1654 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1655 \book {
1656   \header { tagline = ##f }
1657   \markup {
1658     "A simple tune"
1659     \footnote \super \char##x00a7 \concat {
1660       \super \char##x00a7 \italic " By me"
1661     }
1662     "is shown below.  It is a recent"
1663     \footnote \super \char##x00b6 \concat {
1664       \super \char##x00b6 \italic " Aug 2012"
1665     }
1666     "composition."
1667   }
1668   \relative {
1669     a'4 b8 e c4 d
1670   }
1671 }
1672 @end lilypond
1673
1674 @seealso
1675 Learning Manual:
1676 @rlearning{Objects and interfaces}.
1677
1678 Notation Reference:
1679 @ref{ASCII aliases},
1680 @ref{Balloon help},
1681 @ref{List of special characters},
1682 @ref{Text marks},
1683 @ref{Text scripts},
1684 @ref{Unicode}.
1685
1686 Internals Reference:
1687 @rinternals{FootnoteEvent},
1688 @rinternals{FootnoteItem},
1689 @rinternals{FootnoteSpanner},
1690 @rinternals{Footnote_engraver}.
1691
1692 @knownissues
1693 Multiple footnotes for the same page can only be stacked, one above
1694 the other; they cannot be printed on the same line.
1695
1696 Footnotes cannot be attached to @code{MultiMeasureRests} or
1697 automatic beams or lyrics.
1698
1699 Footnote marks may collide with staves, @code{\markup} objects, other
1700 footnote marks and annotation lines.
1701
1702
1703 @node Reference to page numbers
1704 @subsection Reference to page numbers
1705
1706 A particular place of a score can be marked using the @code{\label}
1707 command, either at top-level or inside music.  This label can then be
1708 referred to in a markup, to get the number of the page where the marked
1709 point is placed, using the @code{\page-ref} markup command.
1710
1711 @lilypond[verbatim,papersize=a8landscape]
1712 \header { tagline = ##f }
1713 \book {
1714   \label #'firstScore
1715   \score {
1716     {
1717       c'1
1718       \pageBreak \mark A \label #'markA
1719       c'1
1720     }
1721   }
1722   \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1723   \markup { Mark A is on page \page-ref #'markA "0" "?" }
1724 }
1725 @end lilypond
1726
1727 The @code{\page-ref} markup command takes three arguments:
1728 @enumerate
1729 @item the label, a scheme symbol, eg. @code{#'firstScore};
1730 @item a markup that will be used as a gauge to estimate the dimensions
1731 of the markup;
1732 @item a markup that will be used in place of the page number if the label
1733 is not known;
1734 @end enumerate
1735
1736 The reason why a gauge is needed is that, at the time markups are
1737 interpreted, the page breaking has not yet occurred, so the page numbers
1738 are not yet known.  To work around this issue, the actual markup
1739 interpretation is delayed to a later time; however, the dimensions of
1740 the markup have to be known before, so a gauge is used to decide these
1741 dimensions.  If the book has between 10 and 99 pages, it may be "00",
1742 ie. a two digit number.
1743
1744
1745 @predefined
1746 @funindex \label
1747 @code{\label},
1748 @funindex \page-ref
1749 @code{\page-ref}.
1750 @endpredefined
1751
1752
1753 @node Table of contents
1754 @subsection Table of contents
1755 A table of contents is included using the
1756 @code{\markuplist \table-of-contents} command.  The elements which
1757 should appear in the table of contents are entered with the
1758 @code{\tocItem} command, which may be used either at top-level, or
1759 inside a music expression.
1760
1761 @verbatim
1762 \markuplist \table-of-contents
1763 \pageBreak
1764
1765 \tocItem \markup "First score"
1766 \score {
1767   {
1768     c'4  % ...
1769     \tocItem \markup "Some particular point in the first score"
1770     d'4  % ...
1771   }
1772 }
1773
1774 \tocItem \markup "Second score"
1775 \score {
1776   {
1777     e'4 % ...
1778   }
1779 }
1780 @end verbatim
1781
1782 Markups used for formatting the table of contents are defined in the
1783 @code{\paper} block.  There are two @q{pre-defined} markups already
1784 available;
1785
1786 @itemize
1787
1788 @item
1789 @code{tocTitleMarkup}
1790
1791 @noindent
1792 Used for formatting the title of the table of contents.
1793
1794 @verbatim
1795 tocTitleMarkup = \markup \huge \column {
1796   \fill-line { \null "Table of Contents" \null }
1797   \null
1798 }
1799 @end verbatim
1800
1801 @item
1802 @code{tocItemMarkup}
1803
1804 @noindent
1805 Used for formatting the elements within the table of contents.
1806
1807 @verbatim
1808 tocItemMarkup = \markup \fill-line {
1809   \fromproperty #'toc:text \fromproperty #'toc:page
1810 }
1811 @end verbatim
1812
1813 @end itemize
1814
1815 @noindent
1816 Both of these variables can be changed.
1817
1818 Here is an example changing the table of contents' title into French;
1819
1820 @verbatim
1821 \paper {
1822   tocTitleMarkup = \markup \huge \column {
1823     \fill-line { \null "Table des matières" \null }
1824     \hspace #1
1825   }
1826 @end verbatim
1827
1828 Here is an example changing the font-size of the elements in the table
1829 of contents;
1830
1831 @verbatim
1832 tocItemMarkup = \markup \large \fill-line {
1833   \fromproperty #'toc:text \fromproperty #'toc:page
1834 }
1835 @end verbatim
1836
1837 Note how the element text and page numbers are referred to in the
1838 @code{tocItemMarkup} definition.
1839
1840 The @code{\tocItemWithDotsMarkup} command can be included within the
1841 @code{tocItemMarkup} to fill the line, between a table of contents item
1842 and its corresponding page number, with dots;
1843
1844 @lilypond[verbatim,line-width=10.0\cm]
1845 \header { tagline = ##f }
1846 \paper {
1847   tocItemMarkup = \tocItemWithDotsMarkup
1848 }
1849
1850 \book {
1851   \markuplist \table-of-contents
1852   \tocItem \markup { Allegro }
1853   \tocItem \markup { Largo }
1854   \markup \null
1855 }
1856 @end lilypond
1857
1858 Custom commands with their own markups can also be defined to build a
1859 more complex table of contents.  In the following example, a new style
1860 is defined for entering act names in a table of contents of an opera;
1861
1862 @noindent
1863 A new markup variable (called @code{tocActMarkup}) is defined in the
1864 @code{\paper} block;
1865
1866 @verbatim
1867 \paper {
1868   tocActMarkup = \markup \large \column {
1869     \hspace #1
1870     \fill-line { \null \italic \fromproperty #'toc:text \null }
1871     \hspace #1
1872   }
1873 }
1874 @end verbatim
1875
1876 @noindent
1877 A custom music function (@code{tocAct}) is then created -- which uses
1878 the new @code{tocActMarkup} markup definition.
1879
1880 @verbatim
1881 tocAct =
1882   #(define-music-function (text) (markup?)
1883      (add-toc-item! 'tocActMarkup text))
1884 @end verbatim
1885
1886 @noindent
1887 A LilyPond input file, using these customer definitions, could look
1888 something like this;
1889
1890 @lilypond[line-width=10.0\cm]
1891 \header { tagline = ##f }
1892 \paper {
1893   tocActMarkup = \markup \large \column {
1894     \hspace #1
1895     \fill-line { \null \italic \fromproperty #'toc:text \null }
1896     \hspace #1
1897   }
1898 }
1899
1900 tocAct =
1901 #(define-music-function (text) (markup?)
1902    (add-toc-item! 'tocActMarkup text))
1903
1904 \book {
1905   \markuplist \table-of-contents
1906   \tocAct \markup { Atto Primo }
1907   \tocItem \markup { Coro. Viva il nostro Alcide }
1908   \tocItem \markup { Cesare. Presti omai l'Egizia terra }
1909   \tocAct \markup { Atto Secondo }
1910   \tocItem \markup { Sinfonia }
1911   \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1912   \markup \null
1913 }
1914 @end lilypond
1915
1916
1917 Here is an example of the @code{\fill-with-pattern} command used within
1918 the context of a table of contents;
1919
1920 @verbatim
1921 \paper {
1922   tocItemMarkup = \markup { \fill-line {
1923     \override #'(line-width . 70)
1924     \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
1925     }
1926   }
1927 }
1928 @end verbatim
1929
1930 @seealso
1931 Installed Files:
1932 @file{ly/toc-init.ly}.
1933
1934 @predefined
1935 @funindex \table-of-contents
1936 @code{\table-of-contents},
1937 @funindex \tocItem
1938 @code{\tocItem}.
1939 @endpredefined
1940
1941
1942 @node Working with input files
1943 @section Working with input files
1944
1945 @menu
1946 * Including LilyPond files::
1947 * Different editions from one source::
1948 * Special characters::
1949 @end menu
1950
1951
1952 @node Including LilyPond files
1953 @subsection Including LilyPond files
1954
1955 @funindex \include
1956 @cindex including files
1957
1958 A large project may be split up into separate files.  To refer to
1959 another file, use
1960
1961 @example
1962 \include "otherfile.ly"
1963 @end example
1964
1965 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1966 contents of @file{otherfile.ly} into the current file at the place
1967 where the @code{\include} appears.  For example, in a large
1968 project you might write separate files for each instrument part
1969 and create a @qq{full score} file which brings together the
1970 individual instrument files.  Normally the included file will
1971 define a number of variables which then become available
1972 for use in the full score file.  Tagged sections can be
1973 marked in included files to assist in making them usable in
1974 different places in a score, see @ref{Different editions from
1975 one source}.
1976
1977 Files in the current working directory may be referenced by
1978 specifying just the file name after the @code{\include} command.
1979 Files in other locations may be included by giving either a full
1980 path reference or a relative path reference (but use the UNIX
1981 forward slash, /, rather than the DOS/Windows back slash, \, as the
1982 directory separator.)  For example, if @file{stuff.ly} is located
1983 one directory higher than the current working directory, use
1984
1985 @example
1986 \include "../stuff.ly"
1987 @end example
1988
1989 @noindent
1990 or if the included orchestral parts files are all located in a
1991 subdirectory called @file{parts} within the current directory, use
1992
1993 @example
1994 \include "parts/VI.ly"
1995 \include "parts/VII.ly"
1996 @dots{} etc
1997 @end example
1998
1999 Files which are to be included can also contain @code{\include}
2000 statements of their own.  By default, these second-level
2001 @code{\include} statements are not interpreted until they have
2002 been brought into the main file, so the file names they specify
2003 must all be relative to the directory containing the main file,
2004 not the directory containing the included file.  However,
2005 this behavior can be changed globally by passing the option
2006 @option{-drelative-includes} option at the command line
2007 (or by adding @code{#(ly:set-option 'relative-includes #t)}
2008 at the top of the main input file).
2009
2010 When @code{relative-includes} is set to @code{#t}, the path for each
2011 @code{\include} command will be taken relative to the file containing
2012 that command.  This behavior is recommended and it will become the
2013 default behavior in a future version of lilypond.
2014
2015 Files relative to the main directory and files relative to some other
2016 directory may both be @code{\include}d by setting
2017 @code{relative-includes} to @code{#t} or @code{#f} at appropriate
2018 places in the files.  For example, if a general library, libA, has
2019 been created which itself uses sub-files which are @code{\include}d
2020 by the entry file of that library, those @code{\include} statements
2021 will need to be preceded by
2022 @code{#(ly:set-option #relative-includes #t)} so they are interpreted
2023 correctly when brought into the main @code{.ly} file, like this:
2024
2025 @example
2026 libA/
2027   libA.ly
2028   A1.ly
2029   A2.ly
2030   @dots{}
2031 @end example
2032
2033 @noindent
2034 then the entry file, @code{libA.ly}, will contain
2035
2036 @example
2037 #(ly:set-option 'relative-includes #t)
2038 \include "A1.ly"
2039 \include "A2.ly"
2040 @dots{}
2041 % return to default setting
2042 #(ly:set-option 'relative-includes #f)
2043 @end example
2044
2045 Any @file{.ly} file can then include the entire library simply with
2046
2047 @example
2048 \include "~/libA/libA.ly"
2049 @end example
2050
2051 More complex file structures may be devised by switching at
2052 appropriate places.
2053
2054 Files can also be included from a directory in a search path
2055 specified as an option when invoking LilyPond from the command
2056 line.  The included files are then specified using just their
2057 file name.  For example, to compile @file{main.ly} which includes
2058 files located in a subdirectory called @file{parts} by this method,
2059 cd to the directory containing @file{main.ly} and enter
2060
2061 @example
2062 lilypond --include=parts main.ly
2063 @end example
2064
2065 and in main.ly write
2066
2067 @example
2068 \include "VI.ly"
2069 \include "VII.ly"
2070 @dots{} etc
2071 @end example
2072
2073 Files which are to be included in many scores may be placed in
2074 the LilyPond directory @file{../ly}.  (The location of this
2075 directory is installation-dependent - see
2076 @rlearning{Other sources of information}).  These files can then
2077 be included simply by naming them on an @code{\include} statement.
2078 This is how the language-dependent files like @file{english.ly} are
2079 included.
2080
2081 LilyPond includes a number of files by default when you start
2082 the program.  These includes are not apparent to the user, but the
2083 files may be identified by running @code{lilypond --verbose} from
2084 the command line.  This will display a list of paths and files that
2085 LilyPond uses, along with much other information.  Alternatively,
2086 the more important of these files are discussed in
2087 @rlearning{Other sources of information}.  These files may be
2088 edited, but changes to them will be lost on installing a new
2089 version of LilyPond.
2090
2091 Some simple examples of using @code{\include} are shown in
2092 @rlearning{Scores and parts}.
2093
2094 @seealso
2095 Learning Manual:
2096 @rlearning{Other sources of information},
2097 @rlearning{Scores and parts}.
2098
2099 @knownissues
2100 If an included file is given a name which is the same as one in
2101 LilyPond's installation files, LilyPond's file from the
2102 installation files takes precedence.
2103
2104
2105 @node Different editions from one source
2106 @subsection Different editions from one source
2107
2108 Several methods can be used to generate different versions of a score
2109 from the same music source.  Variables are perhaps the most useful for
2110 combining lengthy sections of music and/or annotation.  Tags are more
2111 useful for selecting one section from several alternative shorter
2112 sections of music, and can also be used for splicing pieces of music
2113 together at different points.
2114
2115 Whichever method is used, separating the notation from the structure of
2116 the score will make it easier to change the structure while leaving the
2117 notation untouched.
2118
2119 @menu
2120 * Using variables::
2121 * Using tags::
2122 * Using global settings::
2123 @end menu
2124
2125 @node Using variables
2126 @unnumberedsubsubsec Using variables
2127
2128 @cindex variables, use of
2129
2130 If sections of the music are defined in variables they can be
2131 reused in different parts of the score, see @rlearning{Organizing
2132 pieces with variables}.  For example, an @notation{a cappella}
2133 vocal score frequently includes a piano reduction of the parts
2134 for rehearsal purposes which is identical to the vocal music, so
2135 the music need be entered only once.  Music from two variables
2136 may be combined on one staff, see @ref{Automatic part combining}.
2137 Here is an example:
2138
2139 @lilypond[verbatim,quote]
2140 sopranoMusic = \relative { a'4 b c b8( a) }
2141 altoMusic = \relative { e'4 e e f }
2142 tenorMusic = \relative { c'4 b e d8( c) }
2143 bassMusic = \relative { a4 gis a d, }
2144 allLyrics = \lyricmode { King of glo -- ry }
2145 <<
2146   \new Staff = "Soprano" \sopranoMusic
2147   \new Lyrics \allLyrics
2148   \new Staff = "Alto" \altoMusic
2149   \new Lyrics \allLyrics
2150   \new Staff = "Tenor" {
2151     \clef "treble_8"
2152     \tenorMusic
2153   }
2154   \new Lyrics \allLyrics
2155   \new Staff = "Bass" {
2156     \clef "bass"
2157     \bassMusic
2158   }
2159   \new Lyrics \allLyrics
2160   \new PianoStaff <<
2161     \new Staff = "RH" {
2162       \partcombine \sopranoMusic \altoMusic
2163     }
2164     \new Staff = "LH" {
2165       \clef "bass"
2166       \partcombine \tenorMusic \bassMusic
2167     }
2168   >>
2169 >>
2170 @end lilypond
2171
2172 Separate scores showing just the vocal parts or just the piano
2173 part can be produced by changing just the structural statements,
2174 leaving the musical notation unchanged.
2175
2176 For lengthy scores, the variable definitions may be placed in
2177 separate files which are then included, see @ref{Including
2178 LilyPond files}.
2179
2180 @node Using tags
2181 @unnumberedsubsubsec Using tags
2182
2183 @funindex \tag
2184 @funindex \keepWithTag
2185 @funindex \removeWithTag
2186 @cindex tag
2187 @cindex keep tagged music
2188 @cindex remove tagged music
2189
2190 The @code{\tag #'@var{partA}} command marks a music expression
2191 with the name @var{partA}.
2192 Expressions tagged in this way can be selected or filtered out by
2193 name later, using either @code{\keepWithTag #'@var{name}} or
2194 @code{\removeWithTag #'@var{name}}.  The result of applying these filters
2195 to tagged music is as follows:
2196 @multitable @columnfractions .5 .5
2197 @headitem Filter
2198   @tab Result
2199 @item
2200 Tagged music preceded by @code{\keepWithTag #'@var{name}} or
2201        @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
2202 @tab Untagged music and music tagged with any of the given tag
2203      names is included;
2204      music tagged with any other tag name is excluded.
2205 @item
2206 Tagged music preceded by @code{\removeWithTag #'@var{name}} or
2207        @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
2208 @tab Untagged music and music not tagged with any of the given tag names
2209      is included; music tagged with any of the given tag names is
2210      excluded.
2211 @item
2212 Tagged music not preceded by either @code{\keepWithTag} or
2213 @code{\removeWithTag}
2214 @tab All tagged and untagged music is included.
2215 @end multitable
2216
2217 The arguments of the @code{\tag}, @code{\keepWithTag} and
2218 @code{\removeWithTag} commands should be a symbol or list of
2219 symbols (such as @code{#'score} or @code{#'(violinI violinII}),
2220 followed by a music expression.  If @emph{and only if} the symbols
2221 are valid LilyPond identifiers (alphabetic characters only, no
2222 numbers, underscores, or dashes) which cannot be confused with notes,
2223 the @code{#'} may be omitted and, as a shorthand, a list of symbols
2224 can use the dot separator: i.e., @code{\tag #'(violinI violinII)} can
2225 be written @code{\tag violinI.violinII}.  The same applies to
2226 @code{\keepWithTag} and @code{\removeWithTag}.
2227
2228 In the following example, we see two versions of a piece of music,
2229 one showing trills with the usual notation, and one with trills
2230 explicitly expanded:
2231
2232 @lilypond[verbatim,quote]
2233 music = \relative {
2234   g'8. c32 d
2235   \tag #'trills { d8.\trill }
2236   \tag #'expand { \repeat unfold 3 { e32 d } }
2237   c32 d
2238  }
2239
2240 \score {
2241   \keepWithTag #'trills \music
2242 }
2243 \score {
2244   \keepWithTag #'expand \music
2245 }
2246 @end lilypond
2247
2248 @noindent
2249 Alternatively, it is sometimes easier to exclude sections of music:
2250
2251 @lilypond[verbatim,quote]
2252 music = \relative {
2253   g'8. c32 d
2254   \tag #'trills { d8.\trill }
2255   \tag #'expand {\repeat unfold 3 { e32 d } }
2256   c32 d
2257  }
2258
2259 \score {
2260   \removeWithTag #'expand
2261   \music
2262 }
2263 \score {
2264   \removeWithTag #'trills
2265   \music
2266 }
2267 @end lilypond
2268
2269 Tagged filtering can be applied to articulations, texts, etc., by
2270 prepending
2271
2272 @example
2273 -\tag #'@var{your-tag}
2274 @end example
2275
2276 to an articulation.  For example, this would define a note with a
2277 conditional fingering indication and a note with a conditional
2278 annotation:
2279
2280 @example
2281 c1-\tag #'finger ^4
2282 c1-\tag #'warn ^"Watch!"
2283 @end example
2284
2285 Multiple tags may be placed on expressions with multiple
2286 @code{\tag} entries, or by combining multiple tags into one symbol
2287 list:
2288
2289 @lilypond[quote,verbatim]
2290 music = \relative c'' {
2291   \tag #'a \tag #'both { a4 a a a }
2292   \tag #'(b both) { b4 b b b }
2293 }
2294 <<
2295 \keepWithTag #'a \music
2296 \keepWithTag #'b \music
2297 \keepWithTag #'both \music
2298 >>
2299 @end lilypond
2300
2301 Multiple @code{\removeWithTag} filters may be applied to a single
2302 music expression to remove several differently named tagged
2303 sections.  Alternatively, you can use a single @code{\removeWithTag}
2304 with a list of tags.
2305
2306 @lilypond[verbatim,quote]
2307 music = \relative c'' {
2308   \tag #'A { a4 a a a }
2309   \tag #'B { b4 b b b }
2310   \tag #'C { c4 c c c }
2311   \tag #'D { d4 d d d }
2312 }
2313 \new Voice {
2314   \removeWithTag #'B
2315   \removeWithTag #'C
2316   \music
2317   \removeWithTag #'(B C)
2318   \music
2319 }
2320 @end lilypond
2321
2322 Using two or more @code{\keepWithTag} filters on a single music
2323 expression will cause @emph{all} of the tagged sections to be removed.
2324 The first filter will remove all except the one named and any subsequent
2325 filters will remove the rest.  Using one @code{\keepWithTag} command
2326 with a list of multiple tags will only remove tagged sections that are
2327 not specified in that list.
2328
2329 @lilypond[verbatim,quote]
2330 music = \relative c'' {
2331   \tag #'violinI { a4 a a a }
2332   \tag #'violinII { b4 b b b }
2333   \tag #'viola { c4 c c c }
2334   \tag #'cello { d4 d d d }
2335 }
2336
2337 \new Staff {
2338   \keepWithTag #'(violinI violinII)
2339   \music
2340 }
2341 @end lilypond
2342
2343 @noindent
2344 will print @code{\tag}s @var{violinI} and @var{violinII} but not
2345 @var{viola} or @var{cello}.
2346
2347 @cindex tag groups
2348 @funindex \tagGroup
2349
2350 While @code{\keepWithTag} is convenient when dealing with @emph{one} set
2351 of alternatives, the removal of music tagged with @emph{unrelated} tags
2352 is problematic when using them for more than one purpose.  In that case
2353 @q{groups} of tags can be declared:
2354
2355 @example
2356 \tagGroup #'(violinI violinII viola cello)
2357 @end example
2358
2359 @noindent
2360 Now all the different tags belong to a single @q{tag group}.  Note that
2361 individual tags cannot be members of more than one @emph{tag group}.
2362
2363 @example
2364 \keepWithTag #'violinI @dots{}
2365 @end example
2366
2367 @noindent
2368 will now only show music tagged from @code{violinI}'s tag group and any
2369 music tagged with one of the @emph{other} tags will removed.
2370
2371 @lilypond[verbatim,quote]
2372 music = \relative {
2373   \tagGroup #'(violinI violinII viola cello)
2374   \tag #'violinI { c''4^"violinI" c c c }
2375   \tag #'violinII { a2 a }
2376   \tag #'viola { e8 e e2. }
2377   \tag #'cello { d'2 d4 d }
2378   R1^"untagged"
2379 }
2380
2381 \new Voice {
2382   \keepWithTag #'violinI
2383   \music
2384 }
2385 @end lilypond
2386
2387 When using the @code{\keepWithTag} command, only tags from the tag
2388 groups of the tags given in the command are visible.
2389
2390 @funindex \pushToTag
2391 @funindex \appendToTag
2392 @cindex splice into tagged music
2393
2394 Sometimes you want to splice some music at a particular place in an
2395 existing music expression.  You can use @code{\pushToTag} and
2396 @code{\appendToTag} for adding material at the front or end of the
2397 @code{elements} of an existing music construct.  Not every music
2398 construct has @code{elements}, but sequential and simultaneous music are
2399 safe bets:
2400
2401 @lilypond[verbatim,quote]
2402 music = { \tag #'here { \tag #'here <<c''>> } }
2403
2404 {
2405   \pushToTag #'here c'
2406   \pushToTag #'here e'
2407   \pushToTag #'here g' \music
2408   \appendToTag #'here c'
2409   \appendToTag #'here e'
2410   \appendToTag #'here g' \music
2411 }
2412 @end lilypond
2413
2414 Both commands get a tag, the material to splice in at every occurence of
2415 the tag, and the tagged expression.
2416
2417 @seealso
2418 Learning Manual:
2419 @rlearning{Organizing pieces with variables}.
2420
2421 Notation Reference:
2422 @ref{Automatic part combining},
2423 @ref{Including LilyPond files}.
2424
2425 @knownissues
2426 Calling @code{\relative} on a music expression obtained by filtering
2427 music through @code{\keepWithTag} or @code{\removeWithTag} might cause
2428 the octave relations to change, as only the pitches actually
2429 remaining in the filtered expression will be considered.  Applying
2430 @code{\relative} first, before @code{\keepWithTag} or
2431 @code{\removeWithTag}, avoids this danger as @code{\relative} then
2432 acts on all the pitches as-input.
2433
2434
2435 @node Using global settings
2436 @unnumberedsubsubsec Using global settings
2437
2438 @cindex include-settings
2439
2440 Global settings can be included from a separate file:
2441
2442 @example
2443 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
2444 @end example
2445
2446 Groups of settings such as page size, font or type face can be stored
2447 in separate files. This allows different editions from the same score
2448 as well as standard settings to be applied to many scores, simply by
2449 specifying the proper settings file.
2450
2451 This technique also works well with the use of style sheets, as
2452 discussed in @rlearning{Style sheets}.
2453
2454 @seealso
2455 Learning Manual:
2456 @rlearning{Organizing pieces with variables},
2457 @rlearning{Style sheets}.
2458
2459 Notation Reference:
2460 @ref{Including LilyPond files}.
2461
2462
2463 @node Special characters
2464 @subsection Special characters
2465
2466 @cindex special characters
2467 @cindex non-ASCII characters
2468
2469 @menu
2470 * Text encoding::
2471 * Unicode::
2472 * ASCII aliases::
2473 @end menu
2474
2475
2476 @node Text encoding
2477 @unnumberedsubsubsec Text encoding
2478
2479 @cindex UTF-8
2480
2481 LilyPond uses the character repertoire defined by the Unicode
2482 consortium and ISO/IEC 10646.  This defines a unique name and
2483 code point for the character sets used in virtually all modern
2484 languages and many others too.  Unicode can be implemented using
2485 several different encodings.  LilyPond uses the UTF-8 encoding
2486 (UTF stands for Unicode Transformation Format) which represents
2487 all common Latin characters in one byte, and represents other
2488 characters using a variable length format of up to four bytes.
2489
2490 The actual appearance of the characters is determined by the
2491 glyphs defined in the particular fonts available - a font defines
2492 the mapping of a subset of the Unicode code points to glyphs.
2493 LilyPond uses the Pango library to layout and render multi-lingual
2494 texts.
2495
2496 LilyPond does not perform any input-encoding conversions.  This
2497 means that any text, be it title, lyric text, or musical
2498 instruction containing non-ASCII characters, must be encoded in
2499 UTF-8.  The easiest way to enter such text is by using a
2500 Unicode-aware editor and saving the file with UTF-8 encoding.  Most
2501 popular modern editors have UTF-8 support, for example, vim, Emacs,
2502 jEdit, and Gedit do.  All MS Windows systems later than NT use
2503 Unicode as their native character encoding, so even Notepad can
2504 edit and save a file in UTF-8 format.  A more functional
2505 alternative for Windows is BabelPad.
2506
2507 If a LilyPond input file containing a non-ASCII character is not
2508 saved in UTF-8 format the error message
2509
2510 @example
2511 FT_Get_Glyph_Name () error: invalid argument
2512 @end example
2513
2514 will be generated.
2515
2516 Here is an example showing Cyrillic, Hebrew and Portuguese
2517 text:
2518
2519 @c NOTE: No verbatim in the following example as the code does not
2520 @c display correctly in PDF Font settings for Cyrillic and Hebrew
2521
2522 @lilypond[quote]
2523 % Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
2524 \paper {
2525   #(define fonts
2526     (set-global-fonts
2527      #:roman "Linux Libertine O,serif"
2528      #:sans "Linux Biolinum O,sans-serif"
2529      #:typewriter "Linux Libertine Mono O,monospace"
2530    ))
2531 }
2532
2533 % Cyrillic
2534 bulgarian = \lyricmode {
2535   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
2536 }
2537
2538 % Hebrew
2539 hebrew = \lyricmode {
2540   זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
2541 }
2542
2543 % Portuguese
2544 portuguese = \lyricmode {
2545   à vo -- cê uma can -- ção legal
2546 }
2547
2548 \relative {
2549   c'2 d e f g f e
2550 }
2551 \addlyrics { \bulgarian }
2552 \addlyrics { \hebrew }
2553 \addlyrics { \portuguese }
2554 @end lilypond
2555
2556
2557 @node Unicode
2558 @unnumberedsubsubsec Unicode
2559
2560 @cindex Unicode
2561
2562 To enter a single character for which the Unicode code point is
2563 known but which is not available in the editor being used, use
2564 either @code{\char ##xhhhh} or @code{\char #dddd} within a
2565 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
2566 the character required and @code{dddd} is the corresponding decimal
2567 value.  Leading zeroes may be omitted, but it is usual to specify
2568 all four characters in the hexadecimal representation.  (Note that
2569 the UTF-8 encoding of the code point should @emph{not} be used
2570 after @code{\char}, as UTF-8 encodings contain extra bits indicating
2571 the number of octets.)  Unicode code charts and a character name
2572 index giving the code point in hexadecimal for any character can be
2573 found on the Unicode Consortium website,
2574 @uref{http://www.unicode.org/}.
2575
2576 For example, @code{\char ##x03BE} and @code{\char #958} would both
2577 enter the Unicode U+03BE character, which has the Unicode name
2578 @qq{Greek Small Letter Xi}.
2579
2580 Any Unicode code point may be entered in this way and if all special
2581 characters are entered in this format it is not necessary to save
2582 the input file in UTF-8 format.  Of course, a font containing all
2583 such encoded characters must be installed and available to LilyPond.
2584
2585 The following example shows Unicode hexadecimal values being entered
2586 in four places -- in a rehearsal mark, as articulation text, in
2587 lyrics and as stand-alone text below the score:
2588
2589 @lilypond[quote,verbatim]
2590 \score {
2591   \relative {
2592     c''1 \mark \markup { \char ##x03EE }
2593     c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
2594   }
2595   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
2596 }
2597 \markup { "Copyright 2008--2015" \char ##x00A9 }
2598 @end lilypond
2599
2600 @cindex copyright sign
2601
2602 To enter the copyright sign in the copyright notice use:
2603
2604 @example
2605 \header @{
2606   copyright = \markup @{ \char ##x00A9 "2008" @}
2607 @}
2608 @end example
2609
2610
2611 @node ASCII aliases
2612 @unnumberedsubsubsec ASCII aliases
2613
2614 A list of ASCII aliases for special characters can be included:
2615
2616 @lilypond[quote,verbatim]
2617 \paper {
2618   #(include-special-characters)
2619 }
2620
2621 \markup "&flqq; &ndash; &OE;uvre incomplète&hellip; &frqq;"
2622
2623 \score {
2624   \new Staff { \repeat unfold 9 a'4 }
2625   \addlyrics {
2626     This is al -- so wor -- kin'~in ly -- rics: &ndash;_&OE;&hellip;
2627   }
2628 }
2629
2630 \markup \column {
2631   "The replacement can be disabled:"
2632   "&ndash; &OE; &hellip;"
2633   \override #'(replacement-alist . ()) "&ndash; &OE; &hellip;"
2634 }
2635 @end lilypond
2636
2637 You can also make your own aliases, either globally:
2638
2639 @lilypond[quote,verbatim]
2640 \paper {
2641   #(add-text-replacements!
2642     '(("100" . "hundred")
2643       ("dpi" . "dots per inch")))
2644 }
2645 \markup "A 100 dpi."
2646 @end lilypond
2647
2648 or locally:
2649
2650 @lilypond[quote,verbatim]
2651 \markup \replace #'(("100" . "hundred")
2652                     ("dpi" . "dots per inch")) "A 100 dpi."
2653 @end lilypond
2654
2655 @seealso
2656 Notation Reference:
2657 @ref{List of special characters}.
2658
2659 Installed Files:
2660 @file{ly/text-replacements.ly}.
2661
2662
2663 @node Controlling output
2664 @section Controlling output
2665
2666 @menu
2667 * Extracting fragments of music::
2668 * Skipping corrected music::
2669 * Alternative output formats::
2670 * Replacing the notation font::
2671 @end menu
2672
2673 @funindex clip-regions
2674 @cindex Fragments, music
2675 @cindex Music fragments
2676
2677 @node Extracting fragments of music
2678 @subsection Extracting fragments of music
2679
2680 It is possible to output one or more fragments of a score by defining
2681 the explicit location of the music to be extracted within the
2682 @code{\layout} block of the input file using the @code{clip-regions}
2683 function, and then running LilyPond with the @option{-dclip-systems}
2684 option;
2685
2686 @example
2687 \layout @{
2688   clip-regions
2689   = #(list
2690       (cons
2691        (make-rhythmic-location 5 1 2)
2692        (make-rhythmic-location 7 3 4)))
2693 @}
2694 @end example
2695
2696 @noindent
2697 This example will extract a single fragment of the input file
2698 @emph{starting} after a half-note duration in fifth measure
2699 (@code{5 1 2}) and @emph{ending} after the third quarter-note in the
2700 seventh measure (@code{7 3 4}).
2701
2702 Additional fragments can be extracted by adding more pairs of
2703 @code{make-rhythmic-location} entries to the @code{clip-regions} list in
2704 the @code{\layout} block.
2705
2706 By default, each music fragment will be output as a separate @code{EPS}
2707 file, but other formats such as @code{PDF} or @code{PNG} can also be
2708 created if required.  The extracted music is output as if had been
2709 literally @q{cut} from the original printed score so if a fragment runs
2710 over one or more lines, a separate output file for each line will be
2711 generated.
2712
2713 @seealso
2714 Notation Reference:
2715 @ref{The layout block}.
2716
2717 Application Usage:
2718 @rprogram{Command-line usage}.
2719
2720
2721
2722 @node Skipping corrected music
2723 @subsection Skipping corrected music
2724
2725
2726 @funindex skipTypesetting
2727 @funindex showFirstLength
2728 @funindex showLastLength
2729
2730 When entering or copying music, usually only the music near the end (where
2731 you
2732 are adding notes) is interesting to view and correct.  To speed up
2733 this correction process, it is possible to skip typesetting of all but
2734 the last few measures.  This is achieved by putting
2735
2736 @example
2737 showLastLength = R1*5
2738 \score @{ @dots{} @}
2739 @end example
2740
2741 @noindent
2742 in your source file.  This will render only the last 5 measures
2743 (assuming 4/4 time signature) of every @code{\score} in the input
2744 file.  For longer pieces, rendering only a small part is often an order
2745 of magnitude quicker than rendering it completely.  When working on the
2746 beginning of a score you have already typeset (e.g., to add a new part),
2747 the @code{showFirstLength} property may be useful as well.
2748
2749 Skipping parts of a score can be controlled in a more fine-grained
2750 fashion with the property @code{Score.skipTypesetting}.  When it is
2751 set, no typesetting is performed at all.
2752
2753 This property is also used to control output to the MIDI file.  Note that
2754 it skips all events, including tempo and instrument changes.  You have
2755 been warned.
2756
2757 @lilypond[quote,ragged-right,verbatim]
2758 \relative c' {
2759   c1
2760   \set Score.skipTypesetting = ##t
2761   \tempo 4 = 80
2762   c4 c c c
2763   \set Score.skipTypesetting = ##f
2764   d4 d d d
2765 }
2766 @end lilypond
2767
2768 In polyphonic music, @code{Score.skipTypesetting} will affect all
2769 voices and staves, saving even more time.
2770
2771 @node Alternative output formats
2772 @subsection Alternative output formats
2773
2774 @cindex scalable vector graphics output
2775 @cindex SVG output
2776 @cindex encapsulated postscript output
2777 @cindex EPS output
2778
2779 The default output formats for the printed score are Portable
2780 Document Format (PDF) and PostScript (PS).  Portable
2781 Network Graphics (PNG), Scalable Vector Graphics (SVG) and Encapsulated
2782 PostScript (EPS) output is available through the command line option,
2783 see @rprogram{Basic command line options for LilyPond}.
2784
2785
2786 @node Replacing the notation font
2787 @subsection Replacing the notation font
2788
2789 Gonville is an alternative to the Feta font used in LilyPond and can
2790 be downloaded from:
2791 @example
2792 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2793 @end example
2794
2795 Here are a few sample bars of music set in Gonville:
2796
2797 @c NOTE: these images are a bit big, but that's important
2798 @c       for the font comparison.  -gp
2799 @sourceimage{Gonville_after,15cm,,}
2800
2801 Here are a few sample bars of music set in LilyPond's Feta font:
2802
2803 @sourceimage{Gonville_before,15cm,,}
2804
2805 @subsubheading Installation Instructions for MacOS
2806
2807 Download and extract the zip file.  Copy the @code{lilyfonts}
2808 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2809 information, see @rlearning{Other sources of information}.  Rename the
2810 existing @code{fonts} directory to @code{fonts_orig} and the
2811 @code{lilyfonts} directory to @code{fonts}.  To revert back to Feta,
2812 reverse the process.
2813
2814 @seealso
2815 Learning Manual:
2816 @rlearning{Other sources of information}.
2817
2818 @knownissues
2819 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2820 likely newer glyphs in later releases of LilyPond may not exist in the
2821 Gonville font family.  Please refer to the author's website for more
2822 information on these and other specifics, including licensing of
2823 Gonville.
2824
2825
2826 @node Creating MIDI output
2827 @section Creating MIDI output
2828
2829 @cindex Sound
2830 @cindex MIDI
2831
2832 LilyPond can produce files that conform to the MIDI (Musical Instrument
2833 Digital Interface) standard and so allow for the checking of the music
2834 output aurally (with the help of an application or device that
2835 understands MIDI).  Listening to MIDI output may also help in spotting
2836 errors such as notes that have been entered incorrectly or are missing
2837 accidentals and so on.
2838
2839 MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but
2840 require additional software to produce sound from them.
2841
2842 @menu
2843 * Supported notation for MIDI::
2844 * Unsupported notation for MIDI::
2845 * The MIDI block::
2846 * Controlling MIDI dynamics::
2847 * Using MIDI instruments::
2848 * Using repeats with MIDI::
2849 * MIDI channel mapping::
2850 * Context properties for MIDI effects::
2851 * Enhancing MIDI output::
2852 @end menu
2853
2854 @cindex MIDI, Supported notation
2855
2856 @node Supported notation for MIDI
2857 @subsection Supported notation for MIDI
2858
2859 The following musical notation can be used with LilyPond's default
2860 capabilities to produce MIDI output;
2861
2862 @itemize
2863 @item Breath marks
2864 @item Chords entered as chord names
2865 @item Crescendi, decrescendi over multiple notes.  The volume is altered
2866 linearly between the two extremes
2867 @item Dynamic markings from @code{ppppp} to @code{fffff}, including
2868 @code{mp}, @code{mf} and @code{sf}
2869 @item Microtones but @emph{not} microtonal chords.  A MIDI player that
2870 supports pitch bending will also be required.
2871 @item Lyrics
2872 @item Pitches
2873 @item Rhythms entered as note durations, including tuplets
2874 @item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
2875 and portato
2876 @item Tempo changes using the @code{\tempo} function
2877 @item Ties
2878 @item Tremolos that are @emph{not} entered with a
2879 @q{@code{:}[@var{number}]} value
2880 @end itemize
2881
2882 Panning, balance, expression, reverb and chorus effects can also be
2883 controlled by setting context properties,
2884 see @ref{Context properties for MIDI effects}.
2885
2886 When combined with the @file{articulate} script the following,
2887 additional musical notation can be output to MIDI;
2888
2889 @itemize
2890 @item Appoggiaturas.  These are made to take half the value of the note
2891 following (without taking dots into account).  For example;
2892
2893 @example
2894 \appoggiatura c8 d2.
2895 @end example
2896
2897 @noindent
2898 The c will take the value of a crotchet.
2899
2900 @item Ornaments (i.e., mordents, trills and turns et al.)
2901 @item Rallentando, accelerando, ritardando and a tempo
2902 @item Slurs, including phrasing slurs
2903 @item Tenuto
2904 @end itemize
2905
2906 @noindent
2907 See @ref{Enhancing MIDI output}.
2908
2909 @cindex MIDI, Unsupported notation
2910
2911 @node Unsupported notation for MIDI
2912 @subsection Unsupported notation for MIDI
2913
2914 The following items of musical notation cannot be output to MIDI;
2915
2916 @itemize
2917 @item Articulations other than staccato, staccatissimo, accent, marcato
2918 and portato
2919 @item Crescendi and decrescendi over a @emph{single} note
2920 @item Fermata
2921 @item Figured bass
2922 @item Glissandi
2923 @item Falls and doits
2924 @item Microtonal chords
2925 @item Rhythms entered as annotations, e.g., swing
2926 @item Tempo changes without @code{\tempo} (e.g., entered as annotations)
2927 @item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
2928 value
2929 @end itemize
2930
2931
2932 @node The MIDI block
2933 @subsection The MIDI block
2934
2935 @cindex MIDI block
2936
2937 To create a MIDI output file from a LilyPond input file, insert a
2938 @code{\midi} block, which can be empty, within the @code{\score} block;
2939
2940 @example
2941 \score @{
2942   @var{@dots{} music @dots{}}
2943   \layout @{ @}
2944   \midi @{ @}
2945 @}
2946 @end example
2947
2948 @warning{A @code{@bs{}score} block that, as well as the music, contains
2949 only a @code{@bs{}midi} block (i.e., @emph{without} the @code{@bs{}layout}
2950 block), will only produce MIDI output files.  No notation will be
2951 printed.}
2952
2953 The default output file extension (@code{.midi}) can be changed by using
2954 the @code{-dmidi-extension} option with the @code{lilypond} command:
2955
2956 @example
2957 lilypond -dmidi-extension=mid MyFile.ly
2958 @end example
2959
2960 Alternatively, add the following Scheme expression before the start of
2961 either the @code{\book}, @code{\bookpart} or @code{\score} blocks.  See
2962 @ref{File structure}.
2963
2964 @example
2965 #(ly:set-option 'midi-extension "mid")
2966 @end example
2967
2968 @seealso
2969 Notation Reference:
2970 @ref{File structure},
2971 @ref{Creating output file metadata}.
2972
2973 Installed Files:
2974 @file{scm/midi.scm}.
2975
2976 @knownissues
2977 There are fifteen MIDI channels available and one additional channel
2978 (#10) for drums.  Staves are assigned to channels in sequence, so a
2979 score that contains more than fifteen staves will result in the extra
2980 staves sharing (but not overwriting) the same MIDI channel.  This may be
2981 a problem if the sharing staves have conflicting, channel-based, MIDI
2982 properties -- such as different MIDI instruments -- set.
2983
2984
2985 @node Controlling MIDI dynamics
2986 @subsection Controlling MIDI dynamics
2987
2988 It is possible to control the overall MIDI volume, the relative volume
2989 of dynamic markings and the relative volume of different instruments.
2990
2991 Dynamic marks translate automatically into volume levels in the
2992 available MIDI volume range whereas crescendi and decrescendi vary the
2993 volume linearly between their two extremes.  It is possible to control
2994 the relative volume of dynamic markings, and the overall volume levels
2995 of different instruments.
2996
2997 @menu
2998 * Dynamic marks in MIDI::
2999 * Setting MIDI volume::
3000 * Setting MIDI block properties::
3001 @end menu
3002
3003 @cindex MIDI volume
3004 @cindex MIDI equalization
3005 @cindex MIDI dynamics
3006 @cindex Dynamics in MIDI
3007
3008
3009 @node Dynamic marks in MIDI
3010 @unnumberedsubsubsec Dynamic marks in MIDI
3011
3012 Only the dynamic markings from @code{ppppp} to @code{fffff}, including
3013 @code{mp}, @code{mf} and @code{sf} have values assigned to them.  This
3014 value is then applied to the value of the overall MIDI volume range to
3015 obtain the final volume included in the MIDI output for that particular
3016 dynamic marking.  The default fractions range from 0.25 for
3017 @notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
3018 dynamic marks and their associated fractions can be found in
3019 @file{scm/midi.scm}.
3020
3021
3022 @snippets
3023 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3024 {creating-custom-dynamics-in-midi-output.ly}
3025
3026 Installed Files:
3027 @file{ly/script-init.ly}
3028 @file{scm/midi.scm}.
3029
3030 Snippets:
3031 @rlsr{MIDI}.
3032
3033 Internals Reference:
3034 @rinternals{Dynamic_performer}.
3035
3036
3037 @node Setting MIDI volume
3038 @unnumberedsubsubsec Setting MIDI volume
3039
3040 The minimum and maximum overall volume of MIDI dynamic markings is
3041 controlled by setting the properties @code{midiMinimumVolume} and
3042 @code{midiMaximumVolume} at the @code{Score} level.  These properties
3043 have an effect only at the start of a voice and on dynamic marks.  The
3044 fraction corresponding to each dynamic mark is modified with this
3045 formula
3046
3047 @example
3048 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
3049 @end example
3050
3051 In the following example the dynamic range of the overall MIDI
3052 volume is limited to the range @code{0.2} - @code{0.5}.
3053
3054 @example
3055 \score @{
3056   <<
3057     \new Staff @{
3058       \set Staff.midiInstrument = #"flute"
3059       @var{@dots{} music @dots{}}
3060     @}
3061     \new Staff @{
3062       \set Staff.midiInstrument = #"clarinet"
3063       @var{@dots{} music @dots{}}
3064     @}
3065   >>
3066   \midi @{
3067     \context @{
3068       \Score
3069       midiMinimumVolume = #0.2
3070       midiMaximumVolume = #0.5
3071     @}
3072   @}
3073 @}
3074 @end example
3075
3076 Simple MIDI instrument equalization can be achieved by setting
3077 @code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
3078 the @code{Staff} context.
3079
3080 @example
3081 \score @{
3082   \new Staff @{
3083     \set Staff.midiInstrument = #"flute"
3084     \set Staff.midiMinimumVolume = #0.7
3085     \set Staff.midiMaximumVolume = #0.9
3086     @var{@dots{} music @dots{}}
3087   @}
3088   \midi @{ @}
3089 @}
3090 @end example
3091
3092 For scores with multiple staves and multiple MIDI instruments, the
3093 relative volumes of each instrument can be set individually;
3094
3095 @example
3096 \score @{
3097   <<
3098     \new Staff @{
3099       \set Staff.midiInstrument = #"flute"
3100       \set Staff.midiMinimumVolume = #0.7
3101       \set Staff.midiMaximumVolume = #0.9
3102       @var{@dots{} music @dots{}}
3103     @}
3104     \new Staff @{
3105       \set Staff.midiInstrument = #"clarinet"
3106       \set Staff.midiMinimumVolume = #0.3
3107       \set Staff.midiMaximumVolume = #0.6
3108       @var{@dots{} music @dots{}}
3109     @}
3110   >>
3111   \midi @{ @}
3112 @}
3113 @end example
3114
3115 In this example the volume of the clarinet is reduced relative to the
3116 volume of the flute.
3117
3118 If these volumes properties are not set then LilyPond still applies a
3119 @q{small degree} of equalization to certain instruments.  See
3120 @file{scm/midi.scm}.
3121
3122 Installed Files:
3123 @file{scm/midi.scm}.
3124
3125 @seealso
3126 Notation Reference:
3127 @ref{Score layout}.
3128
3129 Internals Reference:
3130 @rinternals{Dynamic_performer}.
3131
3132 @snippets
3133 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3134 {replacing-default-midi-instrument-equalization.ly}
3135
3136 @knownissues
3137 Changes in the MIDI volume take place only on starting a note, so
3138 crescendi and decrescendi cannot affect the volume of a single note.
3139
3140
3141 @node Setting MIDI block properties
3142 @unnumberedsubsubsec Setting MIDI block properties
3143
3144 The @code{\midi} block can contain context rearrangements, new context
3145 definitions or code that sets the values of certain properties.
3146
3147 @example
3148 \score @{
3149   @var{@dots{} music @dots{}}
3150   \midi @{
3151     \tempo 4 = 72
3152   @}
3153 @}
3154 @end example
3155
3156 Here the tempo is set to 72 quarter-note beats per minute.  The tempo
3157 mark in the @code{\midi} block will not appear in the printed score.
3158 Although any other @code{\tempo} indications specified within the
3159 @code{\score} block will also be reflected in the MIDI output.
3160
3161 In a @code{\midi} block the @code{\tempo} command is setting properties
3162 during the interpretation of the music and in the context of output
3163 definitions; so it is interpreted @emph{as if} it were a context
3164 modification.
3165
3166 @cindex MIDI context definitions
3167 @cindex context definitions with MIDI
3168
3169 Context definitions follow the same syntax as those in a @code{\layout}
3170 block;
3171
3172 @example
3173 \score @{
3174   @var{@dots{} music @dots{}}
3175   \midi @{
3176     \context @{
3177       \Voice
3178       \remove "Dynamic_performer"
3179     @}
3180   @}
3181 @}
3182 @end example
3183
3184 This example removes the effect of dynamics from the MIDI output.  Note:
3185 LilyPond's translation modules used for sound are called @q{performers}.
3186
3187 @seealso
3188 Learning Manual:
3189 @rlearning{Other sources of information}.
3190
3191 Notation Reference:
3192 @ref{Expressive marks},
3193 @ref{Score layout}.
3194
3195 Installed Files:
3196 @file{ly/performer-init.ly}.
3197
3198 Snippets:
3199 @rlsr{MIDI}.
3200
3201 Internals Reference:
3202 @rinternals{Dynamic_performer}.
3203
3204 @knownissues
3205 Some MIDI players do not always correctly handle tempo changes in the
3206 midi output.
3207
3208 Changes to the @code{midiInstrument}, as well as some MIDI options, at
3209 the @emph{beginning} of a staff may appear twice in the MIDI output.
3210
3211
3212
3213 @node Using MIDI instruments
3214 @subsection Using MIDI instruments
3215
3216 MIDI instruments are set using the @code{midiInstrument} property within
3217 a @code{Staff} context.
3218
3219 @example
3220 \score @{
3221   \new Staff @{
3222     \set Staff.midiInstrument = #"glockenspiel"
3223     @var{@dots{} music @dots{}}
3224   @}
3225   \midi @{ @}
3226 @}
3227 @end example
3228
3229 or
3230
3231 @example
3232 \score @{
3233   \new Staff \with @{midiInstrument = #"cello"@} @{
3234     @var{@dots{} music @dots{}}
3235   @}
3236   \midi @{ @}
3237 @}
3238 @end example
3239
3240 If the instrument name does not match any of the instruments listed in
3241 the @q{MIDI instruments} section, the @code{acoustic grand} instrument
3242 will be used instead. See @ref{MIDI instruments}.
3243
3244 @seealso
3245 Learning Manual:
3246 @rlearning{Other sources of information}.
3247
3248 Notation Reference:
3249 @ref{MIDI instruments},
3250 @ref{Score layout}.
3251
3252 Installed Files:
3253 @file{scm/midi.scm}.
3254
3255 @knownissues
3256 Percussion instruments that are notated in a @code{DrumStaff}
3257 context will be output, correctly, to MIDI channel@tie{}10 but some
3258 pitched, percussion instruments like the xylophone, marimba, vibraphone
3259 or timpani, are treated as @qq{normal} instruments so the music for
3260 these should be entered in a @code{Staff} (not @code{DrumStaff}) context
3261 to obtain correct MIDI output.  A full list of
3262 @code{channel 10 drum-kits} entries can be found in @file{scm/midi.scm}.
3263 See @rlearning{Other sources of information}.
3264
3265
3266 @node Using repeats with MIDI
3267 @subsection Using repeats with MIDI
3268
3269 @cindex repeats in MIDI
3270 @cindex MIDI using repeats
3271 @funindex \unfoldRepeats
3272
3273 Repeats can be represented in the MIDI output by applying the
3274 @code{\unfoldRepeats} command.
3275
3276 @example
3277 \score @{
3278   \unfoldRepeats @{
3279     \repeat tremolo 8 @{ c'32 e' @}
3280     \repeat percent 2 @{ c''8 d'' @}
3281     \repeat volta 2 @{ c'4 d' e' f' @}
3282     \alternative @{
3283       @{ g' a' a' g' @}
3284       @{ f' e' d' c' @}
3285     @}
3286   @}
3287   \midi @{ @}
3288 @}
3289 @end example
3290
3291 In order to restrict the effect of @code{\unfoldRepeats} to the MIDI
3292 output only, while also generating printable scores, it is necessary to
3293 make @emph{two} @code{\score} blocks; one for MIDI (with unfolded
3294 repeats) and one for the notation (with volta, tremolo, and percent
3295 repeats);
3296
3297 @example
3298 \score @{
3299   @var{@dots{} music @dots{}}
3300   \layout @{ @}
3301 @}
3302 \score @{
3303   \unfoldRepeats @{
3304     @var{@dots{} music @dots{}}
3305   @}
3306   \midi @{ @}
3307 @}
3308 @end example
3309
3310 When using multiple voices, each of the voices must contain completely
3311 unfolded repeats for correct MIDI output.
3312
3313 @seealso
3314 Notation Reference:
3315 @ref{Repeats}.
3316
3317
3318 @node MIDI channel mapping
3319 @subsection MIDI channel mapping
3320
3321 @cindex MIDI Channels
3322 @cindex MIDI Tracks
3323 @funindex midiChannelMapping
3324
3325 When generating a MIDI file from a score, LilyPond will automatically
3326 assign every note in the score to a MIDI channel, the one on which it
3327 should be played when it is sent to a MIDI device.  A MIDI channel has
3328 a number of controls available to select, for example, the instrument
3329 to be used to play the notes on that channel, or to request the MIDI
3330 device to apply various effects to the sound produced on the channel.
3331 At all times, every control on a MIDI channel can have only a single
3332 value assigned to it (which can be modified, however, for example,
3333 to switch to another instrument in the middle of a score).
3334
3335 The MIDI standard supports only 16 channels per MIDI device.  This
3336 limit on the number of channels also limits the number of different
3337 instruments which can be played at the same time.
3338
3339 LilyPond creates separate MIDI tracks for each staff, (or discrete
3340 instrument or voice, depending on the value of
3341 @code{Score.midiChannelMapping}), and also for each lyrics context.
3342 There is no limit to the number of tracks.
3343
3344 To work around the limited number of MIDI channels, LilyPond supports
3345 a number of different modes for MIDI channel allocation, selected using
3346 the @code{Score.midiChannelMapping} context property.  In each case,
3347 if more MIDI channels than the limit are required, the allocated
3348 channel numbers wrap around back to 0, possibly causing the incorrect
3349 assignment of instruments to some notes.  This context property can be
3350 set to one of the following values:
3351
3352 @table @var
3353
3354 @item @code{'staff}
3355
3356 Allocate a separate MIDI channel to each staff in the score (this is
3357 the default).  All notes in all voices contained within each staff will
3358 share the MIDI channel of their enclosing staff, and all are encoded
3359 in the same MIDI track.
3360
3361 The limit of 16 channels is applied to the total number of staff and
3362 lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.
3363
3364 @item @code{'instrument}
3365
3366 Allocate a separate MIDI channel to each distinct MIDI instrument
3367 specified in the score.  This means that all the notes played with the
3368 same MIDI instrument will share the same MIDI channel (and track), even
3369 if the notes come from different voices or staves.
3370
3371 In this case the lyrics contexts do not count towards the MIDI channel
3372 limit of 16 (as they will not be assigned to a MIDI instrument), so
3373 this setting may allow a better allocation of MIDI channels when the
3374 number of staves and lyrics contexts in a score exceeds 16.
3375
3376 @item @code{'voice}
3377
3378 Allocate a separate MIDI channel to each voice in the score that has a
3379 unique name among the voices in its enclosing staff.  Voices in
3380 different staves are always assigned separate MIDI channels, but any two
3381 voices contained within the same staff will share the same MIDI channel
3382 if they have the same name.  Because @code{midiInstrument} and the
3383 several MIDI controls for effects are properties of the staff context,
3384 they cannot be set separately for each voice.  The first voice will be
3385 played with the instrument and effects specified for the staff, and
3386 voices with a different name from the first will be assigned the default
3387 instrument and effects.
3388
3389 Note: different instruments and/or effects can be assigned to several
3390 voices on the same staff by moving the @code{Staff_performer} from the
3391 @code{Staff} to the @code{Voice} context, and leaving
3392 @code{midiChannelMapping} to default to @code{'staff} or set to
3393 @code{'instrument}; see the snippet below.
3394
3395 @end table
3396
3397 For example, the default MIDI channel mapping of a score can be changed
3398 to the @code{'instrument} setting as shown:
3399
3400 @example
3401 \score @{
3402   ...music...
3403   \midi @{
3404     \context @{
3405       \Score
3406       midiChannelMapping = #'instrument
3407     @}
3408   @}
3409 @}
3410 @end example
3411
3412 @snippets
3413 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3414 {changing-midi-output-to-one-channel-per-voice.ly}
3415
3416
3417 @node Context properties for MIDI effects
3418 @subsection Context properties for MIDI effects
3419
3420 @cindex Effects in MIDI
3421 @cindex Pan position in MIDI
3422 @cindex Stereo balance in MIDI
3423 @cindex Balance in MIDI
3424 @cindex Expression in MIDI
3425 @cindex Reverb in MIDI
3426 @cindex Chorus level in MIDI
3427 @funindex midiPanPosition
3428 @funindex midiBalance
3429 @funindex midiExpression
3430 @funindex midiReverbLevel
3431 @funindex midiChorusLevel
3432
3433 The following context properties can be used to apply various MIDI
3434 effects to notes played on the MIDI channel associated with the
3435 current staff, MIDI instrument or voice (depending on the value of the
3436 @code{Score.midiChannelMapping} context property and the context in
3437 which the @code{Staff_performer} is located; see
3438 @ref{MIDI channel mapping}).
3439
3440 Changing these context properties will affect all notes played on the
3441 channel after the change, however some of the effects may even apply
3442 also to notes which are already playing (depending on the
3443 implementation of the MIDI output device).
3444
3445 The following context properties are supported:
3446
3447 @table @var
3448
3449 @item @code{Staff.midiPanPosition}
3450
3451 The pan position controls how the sound on a MIDI channel is
3452 distributed between left and right stereo outputs.  The context
3453 property accepts a number between -1.0 (@code{#LEFT}) and 1.0
3454 (@code{#RIGHT}); the value -1.0 will put all sound power to the left
3455 stereo output (keeping the right output silent), the value 0.0
3456 (@code{#CENTER}) will distribute the sound evenly between the left and
3457 right stereo outputs, and the value 1.0 will move all sound to the
3458 right stereo output.  Values between -1.0 and 1.0 can be used to obtain
3459 mixed distributions between left and right stereo outputs.
3460
3461 @item @code{Staff.midiBalance}
3462
3463 The stereo balance of a MIDI channel.  Similarly to the pan position,
3464 this context property accepts a number between -1.0 (@code{#LEFT}) and
3465 1.0 (@code{#RIGHT}).  It varies the relative volume sent to the two
3466 stereo speakers without affecting the distribution of the stereo
3467 signals.
3468
3469 @item @code{Staff.midiExpression}
3470
3471 Expression level (as a fraction of the maximum available level) to
3472 apply to a MIDI channel.  A MIDI device combines the MIDI channel's
3473 expression level with a voice's current dynamic level (controlled using
3474 constructs such as @code{\p} or @code{\ff}) to obtain the total volume
3475 of each note within the voice.  The expression control could be used, for
3476 example, to implement crescendo or decrescendo effects over single
3477 sustained notes (not supported automatically by LilyPond).
3478
3479 @c Issue 4059 contains an attached snippet which shows how this might
3480 @c be done, but this is too large and complex for the NR, even as a
3481 @c referenced snippet.  It could be added to the LSR.
3482
3483 The expression level ranges from 0.0 (no expression, meaning zero
3484 volume) to 1.0 (full expression).
3485
3486 @item @code{Staff.midiReverbLevel}
3487
3488 Reverb level (as a fraction of the maximum available level) to apply
3489 to a MIDI channel.  This property accepts numbers between 0.0 (no
3490 reverb) and 1.0 (full effect).
3491
3492 @item @code{Staff.midiChorusLevel}
3493
3494 Chorus level (as a fraction of the maximum available level) to apply to
3495 a MIDI channel.  This property accepts numbers between 0.0 (no chorus
3496 effect) and 1.0 (full effect).
3497
3498 @end table
3499
3500
3501 @knownissues
3502
3503 As MIDI files do not contain any actual audio data, changes in these
3504 context properties translate only to requests for changing MIDI channel
3505 controls in the outputted MIDI files.  Whether a particular MIDI device
3506 (such as a software MIDI player) can actually handle any of these
3507 requests in a MIDI file is entirely up to the implementation of the
3508 device: a device may choose to ignore some or all of these requests.
3509 Also, how a MIDI device will interpret different values for these
3510 controls (generally, the MIDI standard fixes the behavior only at the
3511 endpoints of the value range available for each control), and whether a
3512 change in the value of a control will affect notes already playing on
3513 that MIDI channel or not, is also specific to the MIDI device
3514 implementation.
3515
3516 When generating MIDI files, LilyPond will simply transform the
3517 fractional values within each range linearly into values in a
3518 corresponding (7-bit, or 14-bit for MIDI channel controls which support
3519 fine resolution) integer range (0-127 or 0-32767, respectively),
3520 rounding fractional values towards the nearest integer away from zero.
3521 The converted integer values are stored as-is in the generated MIDI
3522 file.  Please consult the documentation of your MIDI device for
3523 information about how the device interprets these values.
3524
3525
3526 @node Enhancing MIDI output
3527 @subsection Enhancing MIDI output
3528
3529 @menu
3530 * The articulate script::
3531 @end menu
3532
3533 The default MIDI output is basic but can be improved by setting MIDI
3534 instruments, @code{\midi} block properties and/or using the
3535 @file{articulate} script.
3536
3537 @cindex instrument names
3538 @cindex MIDI, instruments
3539 @cindex articulate script
3540 @cindex articulate.ly
3541 @funindex Staff.midiInstrument
3542
3543
3544 @node The articulate script
3545 @unnumberedsubsubsec The @file{articulate} script
3546
3547 To use the @file{articulate} script add the appropriate @code{\include}
3548 command at the top of the input file;
3549
3550 @example
3551 \include "articulate.ly"
3552 @end example
3553
3554 The script creates MIDI output into appropriately @q{time-scaled} notes
3555 to match many articulation and tempo indications.  Engraved output
3556 however, will also be altered to literally match the MIDI output.
3557
3558 @example
3559 \score @{
3560   \articulate <<
3561     @var{@dots{} music @dots{}}
3562   >>
3563   \midi @{ @}
3564 @}
3565 @end example
3566
3567 The @code{\articulate} command enables abbreviatures (such as trills and
3568 turns) to be processed.  A full list of supported items can be found in
3569 the script itself.  See @file{ly/articulate.ly}.
3570
3571 @seealso
3572 Learning Manual:
3573 @rlearning{Other sources of information}.
3574
3575 Notation Reference:
3576 @ref{Score layout}.
3577
3578 Installed Files:
3579 @file{ly/articulate.ly}.
3580
3581 @warning{The @file{articulate} script may shorten chords, which might
3582 not be appropriate for some types of instrument, such as organ music.
3583 Notes that do not have any articulations attached to them may also be
3584 shortened; so to allow for this, restrict the use of the
3585 @code{\articulate} function to shorter segments of music, or modify the
3586 values of the variables defined in the @file{articulate} script to
3587 compensate for the note-shortening behavior.}
3588
3589
3590
3591 @node Extracting musical information
3592 @section Extracting musical information
3593
3594 In addition to creating graphical output and MIDI, LilyPond can
3595 display musical information as text.
3596
3597 @menu
3598 * Displaying LilyPond notation::
3599 * Displaying scheme music expressions::
3600 * Saving music events to a file::
3601 @end menu
3602
3603 @node Displaying LilyPond notation
3604 @subsection Displaying LilyPond notation
3605
3606 @funindex \displayLilyMusic
3607 Displaying a music expression in LilyPond notation can be
3608 done with the music function @code{\displayLilyMusic}.  To see the
3609 output, you will typically want to call LilyPond using the command
3610 line.  For example,
3611
3612 @example
3613 @{
3614   \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3615 @}
3616 @end example
3617
3618 will display
3619
3620 @example
3621 @{ a,4 cis4 e4 fis4 g4 @}
3622 @end example
3623
3624 By default, LilyPond will print these messages to the console
3625 along with all the other LilyPond compilation messages.  To split
3626 up these messages and save the results of @code{\displayLilyMusic},
3627 redirect the output to a file.
3628
3629 @example
3630 lilypond file.ly >display.txt
3631 @end example
3632
3633 @funindex \void
3634 Note that LilyPond does not just display the music expression, but
3635 also interprets it (since @code{\displayLilyMusic} returns it in
3636 addition to displaying it).  Just insert @code{\displayLilyMusic} into
3637 the existing music in order to get information about it.
3638
3639 To interpret and display a music section in the console but, at the same
3640 time, remove it from the output file use the @code{\void} command.
3641
3642 @example
3643 @{
3644   \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3645   c1
3646 @}
3647 @end example
3648
3649
3650 @node Displaying scheme music expressions
3651 @subsection Displaying scheme music expressions
3652
3653 See @rextend{Displaying music expressions}.
3654
3655
3656 @node Saving music events to a file
3657 @subsection Saving music events to a file
3658
3659 Music events can be saved to a file on a per-staff basis by
3660 including a file in your main score.
3661
3662 @example
3663 \include "event-listener.ly"
3664 @end example
3665
3666 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
3667 @file{FILENAME-unnamed-staff.notes} for each staff.  Note that if
3668 you have multiple unnamed staves, the events for all staves will
3669 be mixed together in the same file.  The output looks like this:
3670
3671 @example
3672 0.000   note     57       4   p-c 2 12
3673 0.000   dynamic  f
3674 0.250   note     62       4   p-c 7 12
3675 0.500   note     66       8   p-c 9 12
3676 0.625   note     69       8   p-c 14 12
3677 0.750   rest     4
3678 0.750   breathe
3679 @end example
3680
3681 The syntax is a tab-delimited line, with two fixed fields on each
3682 line followed by optional parameters.
3683
3684 @example
3685 @var{time}  @var{type}  @var{@dots{}params@dots{}}
3686 @end example
3687
3688 This information can easily be read into other programs such as
3689 python scripts, and can be very useful for researchers wishing to
3690 perform musical analysis or playback experiments with LilyPond.
3691
3692
3693 @knownissues
3694
3695 Not all lilypond music events are supported by
3696 @file{event-listener.ly}.  It is intended to be a well-crafted
3697 @qq{proof of concept}.  If some events that you want to see are
3698 not included, copy @file{event-listener.ly} into your lilypond
3699 directory and modify the file so that it outputs the information
3700 you want.