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