1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node General input and output
14 @chapter General input and output
16 This section deals with general LilyPond input and output issues,
17 rather than specific notation.
21 * Titles and headers::
22 * Working with input files::
23 * Controlling output::
25 * Extracting musical information::
30 @section Input structure
32 The main format of input for LilyPond are text files. By convention,
33 these files end with @file{.ly}.
36 * Structure of a score::
37 * Multiple scores in a book::
38 * Multiple output files from one input file::
44 @node Structure of a score
45 @subsection Structure of a score
49 A @code{\score} block must contain a single music expression
50 delimited by curly brackets:
58 @warning{There must be @strong{only one} outer music expression in
59 a @code{\score} block, and it @strong{must} be surrounded by
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:
70 @lilypond[verbatim,quote]
77 @lilypond[verbatim,quote]
79 \new Staff { c'4 c' c' c' }
80 \new Staff { d'4 d' d' d' }
88 \new Staff @{ \flute @}
89 \new Staff @{ \oboe @}
92 \new Staff @{ \violinI @}
93 \new Staff @{ \violinII @}
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{%@{ .. %@}} 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
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}.
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}.)
119 @rlearning{Working on input files},
120 @rlearning{Music expressions explained},
121 @rlearning{Score is a (single) compound musical expression}.
124 @node Multiple scores in a book
125 @subsection Multiple scores in a book
128 @cindex movements, multiple
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,
140 and texts are entered with a @code{\markup} block,
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.
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.
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.
177 title = "Eight miniatures"
178 composer = "Igor Stravinsky"
182 \header @{ piece = "Romanze" @}
185 ..text of second verse..
188 ..text of third verse..
192 \header @{ piece = "Menuetto" @}
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.
206 subtitle = "First part"
213 subtitle = "Second part"
220 @node Multiple output files from one input file
221 @subsection Multiple output files from one input file
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}.
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
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
240 The default behaviour is to append a version-number suffix for each
241 name which may clash, so
246 \layout @{ @dots{} @}
250 \layout @{ @dots{} @}
254 \layout @{ @dots{} @}
258 in source file @file{eightminiatures.ly}
263 @file{eightminiatures.pdf},
265 @file{eightminiatures-1.pdf} and
267 @file{eightminiatures-2.pdf}.
270 @node Output file names
271 @subsection Output file names
273 @funindex \bookOutputSuffix
274 @funindex \bookOutputName
276 Lilypond provides facilities to allow you to control what file names
277 are used by the various back-ends when producing output files.
279 In the previous section, we saw how Lilypond prevents name-clashes when
280 producing several ouputs 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.
289 \bookOutputSuffix "Romanze"
291 \layout @{ @dots{} @}
294 \bookOutputSuffix "Menuetto"
296 \layout @{ @dots{} @}
299 \bookOutputSuffix "Nocturne"
301 \layout @{ @dots{} @}
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
310 \bookOutputName "Romanze"
312 \layout @{ @dots{} @}
315 \bookOutputName "Menuetto"
317 \layout @{ @dots{} @}
320 \bookOutputName "Nocturne"
322 \layout @{ @dots{} @}
326 The file above will produce these output files:
332 @file{Menuetto.pdf} and
339 @subsection File structure
349 A @file{.ly} file may contain any number of toplevel expressions, where a
350 toplevel expression is one of the following:
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}.
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)}.
368 A @code{\header} block. This sets the global header block. This
369 is the block containing the definitions for book-wide settings, like
370 composer, title, etc.
373 A @code{\score} block. This score will be collected with other
374 toplevel scores, and combined as a single @code{\book}.
375 This behavior can be changed by setting the variable
376 @code{toplevel-score-handler} at toplevel. The default handler is
377 defined in the init file @file{../scm/lily.scm}.
380 A @code{\book} block logically combines multiple movements
381 (i.e., multiple @code{\score} blocks) in one document. If there
382 are a number of @code{\score}s, one output file will be created
383 for each @code{\book} block, in which all corresponding movements
384 are concatenated. The only reason to explicitly specify
385 @code{\book} blocks in a @file{.ly} file is if you wish to create
386 multiple output files from a single input file. One exception is
387 within lilypond-book documents, where you explicitly have to add
388 a @code{\book} block if you want more than a single @code{\score}
389 or @code{\markup} in the same example. This behavior can be
390 changed by setting the variable @code{toplevel-book-handler} at
391 toplevel. The default handler is defined in the init file
392 @file{../scm/lily.scm}.
395 A @code{\bookpart} block. A book may be divided into several parts,
396 using @code{\bookpart} blocks, in order to ease the page breaking,
397 or to use different @code{\paper} settings in different parts.
400 A compound music expression, such as
405 This will add the piece in a @code{\score} and format it in a
406 single book together with all other toplevel @code{\score}s and music
407 expressions. In other words, a file containing only the above
408 music expression will be translated into
425 This behavior can be changed by setting the variable
426 @code{toplevel-music-handler} at toplevel. The default handler is
427 defined in the init file @file{../scm/lily.scm}.
430 A markup text, a verse for example
433 2. The first line verse two.
437 Markup texts are rendered above, between or below the scores or music
438 expressions, wherever they appear.
448 This can be used later on in the file by entering @code{\foo}. The
449 name of a variable should have alphabetic characters only; no
450 numbers, underscores or dashes.
454 The following example shows three things that may be entered at
459 % Don't justify the output
471 At any point in a file, any of the following lexical instructions can
475 @item @code{\version}
476 @item @code{\include}
477 @item @code{\sourcefilename}
478 @item @code{\sourcefileline}
480 A single-line comment, introduced by a leading @code{%} sign.
483 A multi-line comment delimited by @code{%@{ .. %@}}.
489 Whitespace between items in the input stream is generally ignored,
490 and may be freely omitted or extended to enhance readability.
491 However, whitespace should always be used in the following
492 circumstances to avoid errors:
495 @item Around every opening and closing curly bracket.
496 @item After every command or variable, i.e. every item that
497 begins with a @code{\} sign.
498 @item After every item that is to be interpreted as a Scheme
499 expression, i.e. every item that begins with a @code{#}@tie{}sign.
500 @item To separate all elements of a Scheme expression.
501 @item In @code{lyricmode} to separate all the terms in both
502 @code{\override} and @code{\set} commands. In particular, spaces
503 must be used around the dot and the equals sign in commands like
504 @code{\override Score . LyricText #'font-size = #5} and before and
505 after the entire command.
511 @rlearning{How LilyPond input files work}.
514 @ref{The \layout block}.
517 @node Titles and headers
518 @section Titles and headers
520 Almost all printed music includes a title and the composer's name;
521 some pieces include a lot more information.
524 * Creating titles headers and footers::
525 * Custom headers footers and titles::
526 * Creating footnotes::
527 * Reference to page numbers::
528 * Table of contents::
532 @node Creating titles headers and footers
533 @subsection Creating titles headers and footers
536 * Title blocks explained::
537 * Default layout of book and score title blocks::
538 * Default layout of headers and footers::
542 @node Title blocks explained
543 @unnumberedsubsubsec Title blocks explained
545 @c TODO: figure out how \bookpart titles work
547 There are two types of title blocks: the main title block that appears
548 above of the first @code{\score} of a book, and individual title
549 blocks that appear within each @code{\score} block. Text fields for
550 both types are entered using a @code{\header} block.
552 If the book only has a single score, the @code{\header} block may be
553 placed inside or outside of the @code{\score} block.
555 @warning{Remember when adding a @bs{}@code{header} block inside a
556 @bs{}@code{score} block, that the music expression must come before the
557 @bs{}@code{header} block.}
559 @lilypond[papersize=a5,quote,verbatim,noragged-right]
562 composer = "J. S. Bach."
566 \new Staff \relative g, {
569 \repeat unfold 2 { g16( d' b') a b d, b' d, } |
570 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
578 \new Staff \relative b {
582 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
583 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
591 Text fields from the main title block of a book can be displayed in all
592 @code{\score} blocks, or manually suppressed:
594 @lilypond[papersize=a5,quote,verbatim,noragged-right]
597 print-all-headers = ##t
600 title = "DAS WOHLTEMPERIRTE CLAVIER"
602 % Do not display the tagline for this book
605 \markup { \vspace #1 }
609 \new Staff { \clef "bass" s1 }
612 title = "PRAELUDIUM I"
614 % Do not display the subtitle for this score
621 \new Staff { \clef "bass" s1 }
625 subsubtitle = "A 4 VOCI"
627 % Do not display the subtitle for this score
636 @ref{File structure},
637 @ref{Custom layout for title blocks}.
640 @node Default layout of book and score title blocks
641 @unnumberedsubsubsec Default layout of book and score title blocks
643 This example demonstrates all @code{\header} variables:
645 @lilypond[papersize=a7,quote,verbatim,noragged-right]
648 % The following fields are centered
649 dedication = "Dedication"
651 subtitle = "Subtitle"
652 subsubtitle = "Subsubtitle"
653 % The following fields are evenly spread on one line
654 % the field "instrument" also appears on following pages
655 instrument = \markup \with-color #green "Instrument"
657 composer = "Composer"
658 % The following fields are placed at opposite ends of the same line
660 arranger = "Arranger"
661 % The following fields are centered at the bottom
662 tagline = "tagline goes at the bottom of the last page"
663 copyright = "copyright goes at the bottom of the first page"
668 % The following fields are placed at opposite ends of the same line
676 % The following fields are placed at opposite ends of the same line
677 piece = "Piece 2 on the same page"
685 % The following fields are placed at opposite ends of the same line
686 piece = "Piece 3 on a new page"
697 The instrument name will be repeated on every page.
700 Only @code{piece} and @code{opus} are printed in a @code{\score}
701 when the paper variable @code{print-all-headers} is set to
702 @code{##f} (the default).
705 @c Is the bit about \null markups true? -mp
706 Text fields left unset in a @code{\header} block are replaced with
707 @code{\null} markups so that the space is not wasted.
710 The default settings for @code{scoreTitleMarkup} place the @code{piece}
711 and @code{opus} text fields at opposite ends of the same line.
715 To change the default layout see @ref{Custom layout for title blocks}.
719 Use the @code{breakbefore} variable inside a @code{\header} block
720 that is itself in a @code{\score} block, to make the top-level
721 @code{\header} block titles appear on the first page on their own, with
722 the music (defined in the @code{\score} block) starting on the next.
724 @lilypond[papersize=a8landscape,verbatim,noragged-right]
727 title = "This is my Title"
728 subtitle = "This is my Subtitle"
729 copyright = "This is the bottom of the first page"
732 \repeat unfold 4 { e'' e'' e'' e'' }
734 piece = "This is the Music"
743 @rlearning{How LilyPond input files work},
746 @ref{Custom layout for title blocks},
747 @ref{File structure}.
750 @file{ly/titling-init.ly}.
753 @node Default layout of headers and footers
754 @unnumberedsubsubsec Default layout of headers and footers
756 @emph{Headers} and @emph{footers} are lines of text appearing at
757 the top and bottom of pages, separate from the main text of a book.
758 They are controlled by the following @code{\paper} variables:
761 @item @code{oddHeaderMarkup}
762 @item @code{evenHeaderMarkup}
763 @item @code{oddFooterMarkup}
764 @item @code{evenFooterMarkup}
767 These markup variables can only access text fields from top-level
768 @code{\header} blocks (which apply to all scores in the book) and are
769 defined in @file{ly/titling-init.ly}. By default:
774 page numbers are automatically placed on the top far left (if even) or
775 top far right (if odd), starting from the second page.
778 the @code{instrument} text field is placed in the center of every
779 page, starting from the second page.
782 the @code{copyright} text is centered on the bottom of the first page.
785 the @code{tagline} is centered on the bottom of the last page, and below
786 the @code{copyright} text if there is only a single page.
790 @lilypond[papersize=a8landscape]
800 The default tagline can be changed by adding a @code{tagline} in the
801 top-level @code{\header} block.
803 @lilypond[papersize=a8landscape,verbatim]
806 tagline = "... music notation for Everyone"
816 To remove the @code{tagline} set the value to @code{##f}.
819 @node Custom headers footers and titles
820 @subsection Custom headers footers and titles
822 @c TODO: somewhere put a link to header spacing info
823 @c (you'll have to explain it more in NR 4).
826 * Custom text formatting for title blocks::
827 * Custom layout for title blocks::
828 * Custom layout for headers and footers::
832 @node Custom text formatting for title blocks
833 @unnumberedsubsubsec Custom text formatting for title blocks
835 Standard @code{\markup} commands can be used to customize any header,
836 footer and title text within the @code{\header} block.
838 @lilypond[quote,verbatim,noragged-right]
842 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
843 subtitle = \markup { \italic "(Excerpt)" }
850 @ref{Formatting text}.
853 @node Custom layout for title blocks
854 @unnumberedsubsubsec Custom layout for title blocks
856 @cindex bookTitleMarkup
857 @cindex scoreTitleMarkup
858 @funindex bookTitleMarkup
859 @funindex scoreTitleMarkup
861 @code{\markup} commands in the @code{\header} block are useful for
862 simple text formatting, but they do not allow precise control over the
863 placement of titles. To customize the placement of the text fields,
864 change either or both of the following @code{\paper} variables:
867 @item @code{bookTitleMarkup}
868 @item @code{scoreTitleMarkup}
871 The placement of titles when using the default values of these
872 @code{\markup} variables is shown in the examples in
873 @ref{Default layout of book and score title blocks}.
875 The default settings for @code{scoreTitleMarkup} as defined in
876 @file{ly/titling-init.ly} are:
879 scoreTitleMarkup = \markup @{ \column @{
880 \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
882 \fromproperty #'header:piece
883 \fromproperty #'header:opus
889 This places the @code{piece} and @code{opus} text fields at opposite
890 ends of the same line:
892 @lilypond[quote,verbatim,noragged-right]
896 piece = "PRAELUDIUM I"
902 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
903 text field is centered and in a large, bold font.
905 @lilypond[papersize=a5,quote,verbatim,noragged-right]
909 scoreTitleMarkup = \markup {
912 \fontsize #4 \bold \fromproperty #'header:piece
913 \fromproperty #'header:opus
917 \header { tagline = ##f }
921 piece = "PRAELUDIUM I"
928 Text fields normally reserved for the main title block can be included
929 in individual score title blocks with the @code{print-all-headers}
930 placed inside the @code{\paper} block. A disadvantage of using this
931 method is that the text fields that are intended specifically for the
932 top-level @code{\header} block need to be manually suppressed in every
933 @code{\score} block. See @ref{Title blocks explained}.
935 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
936 definition. In the following example, the @code{composer} text field
937 (normally associated with @code{bookTitleMarkup}) is added to
938 @code{scoreTitleMarkup}, allowing each score to list a different
941 @lilypond[papersize=a5,quote,verbatim,noragged-right]
945 scoreTitleMarkup = \markup {
948 \fontsize #4 \bold \fromproperty #'header:piece
949 \fromproperty #'header:composer
953 \header { tagline = ##f }
958 composer = "Christian Petzold"
965 composer = "François Couperin"
971 It is also possible to create your own custom text fields, and refer to
972 them in the markup definition.
974 @lilypond[papersize=a5,quote,verbatim,noragged-right]
978 scoreTitleMarkup = \markup {
981 \override #`(direction . ,UP) {
983 \center-align \fontsize #-1 \bold
984 \fromproperty #'header:mycustomtext %% User-defined field
985 \center-align \fontsize #4 \bold
986 \fromproperty #'header:piece
989 \fromproperty #'header:opus
993 \header { tagline = ##f }
998 mycustomtext = "A 4 VOCI" %% User-defined field
1007 @ref{Title blocks explained}.
1010 @node Custom layout for headers and footers
1011 @unnumberedsubsubsec Custom layout for headers and footers
1013 @c can make-header and make-footer be removed from
1014 @c paper-defaults-init.ly? -mp
1016 @code{\markup} commands in the @code{\header} block are useful for
1017 simple text formatting, but they do not allow precise control over the
1018 placement of headers and footers. To customize the placement of
1019 the text fields, use either or both of the following @code{\paper}
1023 @item @code{oddHeaderMarkup}
1024 @item @code{evenHeaderMarkup}
1025 @item @code{oddFooterMarkup}
1026 @item @code{evenFooterMarkup}
1029 @cindex markup, conditional
1031 @funindex \on-the-fly
1033 The @code{\markup} command @code{\on-the-fly} can be used to add
1034 markup conditionally to header and footer text defined within the
1035 @code{\paper} block, using the following syntax:
1038 @code{variable} = @code{\markup} @{
1040 @code{\on-the-fly} #@var{procedure} @var{markup}
1045 The @var{procedure} is called each time the @code{\markup} command
1046 in which it appears is evaluated. The @var{procedure} should test
1047 for a particular condition and interpret (i.e. print) the
1048 @var{markup} argument if and only if the condition is true.
1050 A number of ready-made procedures for testing various conditions are
1054 @multitable {print-page-number-check-first-----} {should this page be printed-----}
1056 @headitem Procedure name @tab Condition tested
1058 @item print-page-number-check-first @tab should this page number be printed?
1059 @item create-page-number-stencil @tab 'print-page-numbers true?
1060 @item print-all-headers @tab 'print-all-headers true?
1061 @item first-page @tab first page in the book?
1062 @item (on-page nmbr) @tab page number = nmbr?
1063 @item last-page @tab last page in the book?
1064 @item not-first-page @tab not first page in the book?
1065 @item part-first-page @tab first page in the book part?
1066 @item part-last-page @tab last page in the book part?
1067 @item not-single-page @tab pages in book part > 1?
1072 The following example centers page numbers at the bottom of every
1073 page. First, the default settings for @code{oddHeaderMarkup} and
1074 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1075 markup. Then, @code{oddFooterMarkup} is redefined with the page
1076 number centered. Finally, @code{evenFooterMarkup} is given the
1077 same layout by defining it as @code{\oddFooterMarkup}:
1079 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1082 print-page-number = ##t
1083 print-first-page-number = ##t
1084 oddHeaderMarkup = \markup \null
1085 evenHeaderMarkup = \markup \null
1086 oddFooterMarkup = \markup {
1088 \on-the-fly #print-page-number-check-first
1089 \fromproperty #'page:page-number-string
1092 evenFooterMarkup = \oddFooterMarkup
1095 \new Staff { s1 \break s1 \break s1 }
1100 Several @code{\on-the-fly} conditions can be combined with an
1101 @q{and} operation, for example,
1104 @code{\on-the-fly #first-page}
1105 @code{\on-the-fly #last-page}
1106 @code{@{ \markup ... \fromproperty #'header: ... @}}
1109 determines if the output is a single page.
1113 @ref{Title blocks explained},
1114 @ref{Default layout of book and score title blocks}.
1117 @file{../ly/titling-init.ly}.
1120 @node Creating footnotes
1121 @subsection Creating footnotes
1123 There are two types of footnotes that can be created; automatic
1124 footnotes and manual footnotes.
1127 * Footnotes overview::
1128 * Automatic footnotes::
1129 * Manual footnotes::
1132 @node Footnotes overview
1133 @unnumberedsubsubsec Footnotes overview
1135 Automatic footnotes create incrementing numerical indicators and manual
1136 footnotes allow a custom indicator to be created instead. Footnotes are
1137 normally applied like @code{\tweak} and consequently can be placed
1138 directly on grobs (graphical objects) created by most music elements and
1139 post-events. In cases where this does not work (like with bar lines and
1140 meter changes, where the grobs are produced as a consequence of property
1141 changes), footnotes can also be specified as a standalone music event
1142 affecting all grobs of a given type at a particular time step.
1144 The full form of a footnote command is
1147 \footnote @var{mark} @var{offset} @var{grob-name} @var{footnote}
1151 The elements are as follows:
1155 is a markup or string specifying the footnote mark which is used for
1156 both marking the reference point as well as the footnote itself at the
1157 bottom of the page. It can be omitted (or equivalently replaced with
1158 @code{\default}) in which case a number in sequence will be generated.
1160 is a number pair such as @samp{#(2 . 1)} specifying the X and Y offset
1161 from the reference point where the mark will be placed.
1163 specifies a type of grob to mark (like @samp{#'Flag}). If it is given,
1164 the respective grob will be used as a reference point even in case that
1165 its @q{cause} is not the referenced @var{music} itself but a grob
1166 created from it. It can be omitted (or replaced with @code{\default}),
1167 and then only a directly created grob will be annotated.
1169 This markup or string specifies the footnote text to use at the bottom
1172 This is the item, a music event or chord constituent or post-event, that
1173 is being annotated. While it cannot be omitted, it @emph{can} be
1174 replaced by @code{\default} in which case the footnote is not attached
1175 to a music expression in particular, but rather to a moment of time. It
1176 is mandatory in this case to use the @var{grob-name} argument for
1177 selecting an affected grob type, like @samp{#'TimeSignature}.
1180 Like with @code{\tweak}, if your @code{\footnote} is applied to a
1181 post-event or articulation, it will itself have to be preceded with
1182 @code{-} to make the parser attach the result to the preceding note or
1185 @node Automatic footnotes
1186 @unnumberedsubsubsec Automatic footnotes
1188 Automatic footnotes take four arguments: the @samp{(x . y)} position of
1189 the indicator, the optional @var{grob-name} specifying the layout object
1190 to be annotated, the @var{footnote} markup itself that will appear at
1191 the bottom of the page, and of course the @var{music} to attach the
1194 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1196 \header { tagline = ##f }
1198 \footnote #'(0.5 . -2)
1199 \markup { The first note }
1201 \footnote #'(0.5 . 1) #'Flag
1202 \markup { The third note }
1208 Chorded notes pose no particular difficulty:
1210 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1212 \header { tagline = ##f }
1215 \footnote #'(1 . -1.25) "Here is a C" c
1216 \footnote #'(2 . -0.25) \markup { \italic "An E-flat" } es
1217 \footnote #'(2 . 3) \markup { \bold "This is a G" } g
1223 @warning {When footnotes have the same vertical position, the footnotes
1224 are printed in order of descendancy; the higher the footnote, the
1225 higher up in the list.}
1227 Here are some more examples of footnoted grobs, also showing the
1228 relative position of the footnotes to the tagline and copyright.
1230 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1232 \header { copyright = \markup { "Copyright 1970" } }
1234 a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
1235 -\footnote #'(0 . 1.5) \markup { A slur } (
1236 b8)-\footnote #'(0 . -2) \markup { Beam } [ e]
1237 \footnote #'(1 . -1) #'Stem
1238 \markup { \teeny { This is a stem } }
1240 \footnote #'(0 . 0.5) #'AccidentalCautionary
1241 \markup \italic { A cautionary accidental }
1242 \footnote #'(1 . 1) "The note itself"
1243 dis?4-\footnote #'(0.5 . -0.5) \markup \italic { Slow Down }
1249 For top-level @code{\markup}, the @code{\auto-footnote} command is
1252 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1254 \header { tagline = ##f }
1255 \markup { \auto-footnote "A simple tune" \italic "By me" }
1263 @node Manual footnotes
1264 @unnumberedsubsubsec Manual footnotes
1266 @cindex footnotes, manual
1268 Manually marked footnotes take an additional first markup argument
1269 @var{mark} for making the reference mark. In contrast to automatically
1270 generated footnote marks, they will not appear before the @var{footnote}
1271 markup at the bottom of the page: establishing the visual connection is
1272 left to the user. LilyPond will only make sure that the corresponding
1273 markup appears on the bottom of the same page.
1275 Other than that, the use is identical to that of automatically numbered
1278 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1280 \header { tagline = ##f }
1284 \markup { \italic "1. The first note" }
1288 \markup { \bold "2" } #'(0.5 . 1)
1289 "2. The second note"
1292 d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
1297 To annotate chorded notes with manual footnotes:
1299 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1301 \header { tagline = ##f }
1304 \footnote "1" #'(1 . -1.25) "1. C" c
1306 \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
1307 \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
1313 @warning {When footnotes have the same vertical position, the footnotes
1314 are printed in order of descendancy; the higher the footnote, the
1315 higher up in the list.}
1317 Here are some examples of manually footnoted grobs, also showing
1318 the relative position of the footnotes to the tagline and copyright
1320 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1322 \header { tagline = ##f }
1325 \markup { \teeny 1 } #'(-3 . 0)
1326 \markup { 1. \bold Forte } \f
1328 \markup { \teeny b } #'(0 . 1.5)
1329 \markup { b. A slur } (
1331 \markup { \teeny 3 } #'(0 . -2)
1332 \markup { 3. Beam } [
1335 \markup { 4 } #'(1 . -1) #'Stem
1336 \markup { \bold 4. { This is a stem } }
1339 \markup \concat \teeny { "sharp (v)" }
1340 #'(0 . 0.5) #'AccidentalCautionary
1341 \markup \italic { v. A cautionary accidental }
1343 \markup \concat \teeny { "a" } #'(0.5 . -0.5)
1344 \markup \italic { a. Slow Down } _"rit."
1346 \markup { \teeny \musicglyph #"rests.4" }
1348 \markup { \null } \breathe
1353 To manually footnote a top-level @code{\markup}:
1355 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1357 \header { tagline = ##f }
1358 \markup { "A simple tune" \footnote "*" \italic "* By me" }
1367 @rlearning{Objects and interfaces}.
1374 @ref{Titles and headers}.
1376 Internals Reference:
1377 @rinternals{FootnoteEvent},
1378 @rinternals{FootnoteItem},
1379 @rinternals{FootnoteSpanner},
1380 @rinternals{Footnote_engraver}.
1383 Multiple footnotes for the same page can only be stacked, one on top of
1384 the other, and cannot be printed on the same line. Footnotes cannot be
1385 attached to @code{MultiMeasureRests} and may collide with @code{Staff},
1386 @code{\markup} objects and other @code{footnote} annotations. When
1387 using any manual @code{footnote} command a @code{\paper} block
1388 containing @code{footnote-auto-number = ##f} is required.
1391 @node Reference to page numbers
1392 @subsection Reference to page numbers
1394 A particular place of a score can be marked using the @code{\label}
1395 command, either at top-level or inside music. This label can then be
1396 referred to in a markup, to get the number of the page where the marked
1397 point is placed, using the @code{\page-ref} markup command.
1399 @lilypond[verbatim,papersize=a8landscape]
1400 \header { tagline = ##f }
1406 \pageBreak \mark A \label #'markA
1410 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1411 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1415 The @code{\page-ref} markup command takes three arguments:
1417 @item the label, a scheme symbol, eg. @code{#'firstScore};
1418 @item a markup that will be used as a gauge to estimate the dimensions
1420 @item a markup that will be used in place of the page number if the label
1424 The reason why a gauge is needed is that, at the time markups are
1425 interpreted, the page breaking has not yet occurred, so the page numbers
1426 are not yet known. To work around this issue, the actual markup
1427 interpretation is delayed to a later time; however, the dimensions of
1428 the markup have to be known before, so a gauge is used to decide these
1429 dimensions. If the book has between 10 and 99 pages, it may be "00",
1430 ie. a two digit number.
1441 @node Table of contents
1442 @subsection Table of contents
1443 A table of contents is included using the @code{\markuplist \table-of-contents}
1444 command. The elements which should appear in the table of contents are
1445 entered with the @code{\tocItem} command, which may be used either at
1446 top-level, or inside a music expression.
1449 \markuplist \table-of-contents
1452 \tocItem \markup "First score"
1456 \tocItem \markup "Some particular point in the first score"
1461 \tocItem \markup "Second score"
1469 The markups which are used to format the table of contents are defined
1470 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1471 for formatting the title of the table, and @code{tocItemMarkup}, for
1472 formatting the toc elements, composed of the element title and page
1473 number. These variables may be changed by the user:
1477 %% Translate the toc title into French:
1478 tocTitleMarkup = \markup \huge \column {
1479 \fill-line { \null "Table des matières" \null }
1482 %% use larger font size
1483 tocItemMarkup = \markup \large \fill-line {
1484 \fromproperty #'toc:text \fromproperty #'toc:page
1489 Note how the toc element text and page number are referred to in
1490 the @code{tocItemMarkup} definition.
1492 New commands and markups may also be defined to build more elaborated
1495 @item first, define a new markup variable in the @code{\paper} block
1496 @item then, define a music function which aims at adding a toc element
1497 using this markup paper variable.
1500 In the following example, a new style is defined for entering act names
1501 in the table of contents of an opera:
1505 tocActMarkup = \markup \large \column {
1507 \fill-line { \null \italic \fromproperty #'toc:text \null }
1513 #(define-music-function (parser location text) (markup?)
1514 (add-toc-item! 'tocActMarkup text))
1517 @lilypond[line-width=10.0\cm]
1518 \header { tagline = ##f }
1520 tocActMarkup = \markup \large \column {
1522 \fill-line { \null \italic \fromproperty #'toc:text \null }
1528 #(define-music-function (parser location text) (markup?)
1529 (add-toc-item! 'tocActMarkup text))
1532 \markuplist \table-of-contents
1533 \tocAct \markup { Atto Primo }
1534 \tocItem \markup { Coro. Viva il nostro Alcide }
1535 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1536 \tocAct \markup { Atto Secondo }
1537 \tocItem \markup { Sinfonia }
1538 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1543 Dots can be added to fill the line between an item and its page number:
1545 @lilypond[verbatim,line-width=10.0\cm]
1546 \header { tagline = ##f }
1548 tocItemMarkup = \tocItemWithDotsMarkup
1552 \markuplist \table-of-contents
1553 \tocItem \markup { Allegro }
1554 \tocItem \markup { Largo }
1561 @file{ly/toc-init.ly}.
1564 @funindex \table-of-contents
1565 @code{\table-of-contents},
1571 @node Working with input files
1572 @section Working with input files
1575 * Including LilyPond files::
1576 * Different editions from one source::
1577 * Special characters::
1581 @node Including LilyPond files
1582 @subsection Including LilyPond files
1585 @cindex including files
1587 A large project may be split up into separate files. To refer to
1591 \include "otherfile.ly"
1594 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1595 contents of @file{otherfile.ly} into the current file at the place
1596 where the @code{\include} appears. For example, in a large
1597 project you might write separate files for each instrument part
1598 and create a @qq{full score} file which brings together the
1599 individual instrument files. Normally the included file will
1600 define a number of variables which then become available
1601 for use in the full score file. Tagged sections can be
1602 marked in included files to assist in making them usable in
1603 different places in a score, see @ref{Different editions from
1606 Files in the current working directory may be referenced by
1607 specifying just the file name after the @code{\include} command.
1608 Files in other locations may be included by giving either a full
1609 path reference or a relative path reference (but use the UNIX
1610 forward slash, /, rather than the DOS/Windows back slash, \, as the
1611 directory separator.) For example, if @file{stuff.ly} is located
1612 one directory higher than the current working directory, use
1615 \include "../stuff.ly"
1619 or if the included orchestral parts files are all located in a
1620 subdirectory called @file{parts} within the current directory, use
1623 \include "parts/VI.ly"
1624 \include "parts/VII.ly"
1628 Files which are to be included can also contain @code{\include}
1629 statements of their own. By default, these second-level
1630 @code{\include} statements are not interpreted until they have
1631 been brought into the main file, so the file names they specify
1632 must all be relative to the directory containing the main file,
1633 not the directory containing the included file. However,
1634 this behavior can be changed by passing the option
1635 @option{-drelative-includes} option at the command line
1636 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1637 at the top of the main input file). With @code{relative-includes}
1638 set, the path for each @code{\include} command will be taken
1639 relative to the file containing that command. This behavior is
1640 recommended and it will become the default behavior in a future
1641 version of lilypond.
1643 Files can also be included from a directory in a search path
1644 specified as an option when invoking LilyPond from the command
1645 line. The included files are then specified using just their
1646 file name. For example, to compile @file{main.ly} which includes
1647 files located in a subdirectory called @file{parts} by this method,
1648 cd to the directory containing @file{main.ly} and enter
1651 lilypond --include=parts main.ly
1654 and in main.ly write
1662 Files which are to be included in many scores may be placed in
1663 the LilyPond directory @file{../ly}. (The location of this
1664 directory is installation-dependent - see
1665 @rlearning{Other sources of information}). These files can then
1666 be included simply by naming them on an @code{\include} statement.
1667 This is how the language-dependent files like @file{english.ly} are
1670 LilyPond includes a number of files by default when you start
1671 the program. These includes are not apparent to the user, but the
1672 files may be identified by running @code{lilypond --verbose} from
1673 the command line. This will display a list of paths and files that
1674 LilyPond uses, along with much other information. Alternatively,
1675 the more important of these files are discussed in
1676 @rlearning{Other sources of information}. These files may be
1677 edited, but changes to them will be lost on installing a new
1678 version of LilyPond.
1680 Some simple examples of using @code{\include} are shown in
1681 @rlearning{Scores and parts}.
1685 @rlearning{Other sources of information},
1686 @rlearning{Scores and parts}.
1689 If an included file is given a name which is the same as one in
1690 LilyPond's installation files, LilyPond's file from the
1691 installation files takes precedence.
1694 @node Different editions from one source
1695 @subsection Different editions from one source
1697 Several methods can be used to generate different versions of a score
1698 from the same music source. Variables are perhaps the most useful for
1699 combining lengthy sections of music and/or annotation. Tags are more
1700 useful for selecting one section from several alternative shorter
1701 sections of music, and can also be used for splicing pieces of music
1702 together at different points.
1704 Whichever method is used, separating the notation from the structure of
1705 the score will make it easier to change the structure while leaving the
1711 * Using global settings::
1714 @node Using variables
1715 @unnumberedsubsubsec Using variables
1717 @cindex variables, use of
1719 If sections of the music are defined in variables they can be
1720 reused in different parts of the score, see @rlearning{Organizing
1721 pieces with variables}. For example, an @notation{a cappella}
1722 vocal score frequently includes a piano reduction of the parts
1723 for rehearsal purposes which is identical to the vocal music, so
1724 the music need be entered only once. Music from two variables
1725 may be combined on one staff, see @ref{Automatic part combining}.
1728 @lilypond[verbatim,quote]
1729 sopranoMusic = \relative c'' { a4 b c b8( a) }
1730 altoMusic = \relative g' { e4 e e f }
1731 tenorMusic = \relative c' { c4 b e d8( c) }
1732 bassMusic = \relative c' { a4 gis a d, }
1733 allLyrics = \lyricmode {King of glo -- ry }
1735 \new Staff = "Soprano" \sopranoMusic
1736 \new Lyrics \allLyrics
1737 \new Staff = "Alto" \altoMusic
1738 \new Lyrics \allLyrics
1739 \new Staff = "Tenor" {
1743 \new Lyrics \allLyrics
1744 \new Staff = "Bass" {
1748 \new Lyrics \allLyrics
1751 \set Staff.printPartCombineTexts = ##f
1757 \set Staff.printPartCombineTexts = ##f
1767 Separate scores showing just the vocal parts or just the piano
1768 part can be produced by changing just the structural statements,
1769 leaving the musical notation unchanged.
1771 For lengthy scores, the variable definitions may be placed in
1772 separate files which are then included, see @ref{Including
1776 @unnumberedsubsubsec Using tags
1779 @funindex \keepWithTag
1780 @funindex \removeWithTag
1781 @funindex \pushToTag
1782 @funindex \appendToTag
1784 @cindex keep tagged music
1785 @cindex remove tagged music
1786 @cindex splice into tagged music
1788 The @code{\tag #'@var{partA}} command marks a music expression
1789 with the name @var{partA}.
1790 Expressions tagged in this way can be selected or filtered out by
1791 name later, using either @code{\keepWithTag #'@var{name}} or
1792 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1793 to tagged music is as follows:
1794 @multitable @columnfractions .5 .5
1798 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1799 @tab Untagged music and music tagged with @var{name} is included;
1800 music tagged with any other tag name is excluded.
1802 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1803 @tab Untagged music and music tagged with any tag name other than
1804 @var{name} is included; music tagged with @var{name} is
1807 Tagged music not preceded by either @code{\keepWithTag} or
1808 @code{\removeWithTag}
1809 @tab All tagged and untagged music is included.
1812 The arguments of the @code{\tag}, @code{\keepWithTag} and
1813 @code{\removeWithTag} commands should be a symbol
1814 (such as @code{#'score} or @code{#'part}), followed
1815 by a music expression.
1817 In the following example, we see two versions of a piece of music,
1818 one showing trills with the usual notation, and one with trills
1819 explicitly expanded:
1821 @lilypond[verbatim,quote]
1822 music = \relative g' {
1824 \tag #'trills { d8.\trill }
1825 \tag #'expand { \repeat unfold 3 { e32 d } }
1830 \keepWithTag #'trills \music
1833 \keepWithTag #'expand \music
1838 Alternatively, it is sometimes easier to exclude sections of music:
1840 @lilypond[verbatim,quote]
1841 music = \relative g' {
1843 \tag #'trills { d8.\trill }
1844 \tag #'expand {\repeat unfold 3 { e32 d } }
1849 \removeWithTag #'expand
1853 \removeWithTag #'trills
1858 Tagged filtering can be applied to articulations, texts, etc. by
1862 -\tag #'@var{your-tag}
1865 to an articulation. For example, this would define a note with a
1866 conditional fingering indication and a note with a conditional
1871 c1-\tag #'warn ^"Watch!"
1874 Multiple tags may be placed on expressions with multiple
1875 @code{\tag} entries:
1877 @lilypond[quote,verbatim]
1878 music = \relative c'' {
1879 \tag #'a \tag #'both { a4 a a a }
1880 \tag #'b \tag #'both { b4 b b b }
1883 \keepWithTag #'a \music
1884 \keepWithTag #'b \music
1885 \keepWithTag #'both \music
1889 Multiple @code{\removeWithTag} filters may be applied to a single
1890 music expression to remove several differently named tagged sections:
1892 @lilypond[verbatim,quote]
1893 music = \relative c'' {
1894 \tag #'A { a4 a a a }
1895 \tag #'B { b4 b b b }
1896 \tag #'C { c4 c c c }
1897 \tag #'D { d4 d d d }
1906 Two or more @code{\keepWithTag} filters applied to a single music
1907 expression will cause @emph{all} tagged sections to be removed, as
1908 the first filter will remove all tagged sections except the one
1909 named, and the second filter will remove even that tagged section.
1911 Sometimes you want to splice some music at a particular place in an
1912 existing music expression. You can use @code{\pushToTag} and
1913 @code{\appendToTag} for adding material at the front or end of the
1914 @code{elements} of an existing music construct. Not every music
1915 construct has @code{elements}, but sequential and simultaneous music are
1918 @lilypond[verbatim,quote]
1919 test = { \tag #'here { \tag #'here <<c''>> } }
1922 \pushToTag #'here c'
1923 \pushToTag #'here e'
1924 \pushToTag #'here g' \test
1925 \appendToTag #'here c'
1926 \appendToTag #'here e'
1927 \appendToTag #'here g' \test
1931 Both commands get a tag, the material to splice in at every occurence of
1932 the tag, and the tagged expression. The commands make sure to
1933 copy everything that they change so that the original @code{\test}
1934 retains its meaning.
1938 @rlearning{Organizing pieces with variables}.
1941 @ref{Automatic part combining},
1942 @ref{Including LilyPond files}.
1945 @c This warning is more general than this placement implies.
1946 @c Rests are not merged whether or not they come from tagged sections.
1947 @c Should be deleted? -td
1950 Multiple rests are not merged if you create a score with more
1951 than one tagged section at the same place.
1956 @node Using global settings
1957 @unnumberedsubsubsec Using global settings
1959 @cindex include-settings
1961 Global settings can be included from a separate file:
1964 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
1967 Groups of settings such as page size, font or type face can be stored
1968 in separate files. This allows different editions from the same score
1969 as well as standard settings to be applied to many scores, simply by
1970 specifying the proper settings file.
1972 This technique also works well with the use of style sheets, as
1973 discussed in @rlearning{Style sheets}.
1977 @rlearning{Organizing pieces with variables},
1978 @rlearning{Style sheets}.
1981 @ref{Including LilyPond files}.
1984 @node Special characters
1985 @subsection Special characters
1987 @cindex special characters
1988 @cindex non-ASCII characters
1998 @unnumberedsubsubsec Text encoding
2002 LilyPond uses the character repertoire defined by the Unicode
2003 consortium and ISO/IEC 10646. This defines a unique name and
2004 code point for the character sets used in virtually all modern
2005 languages and many others too. Unicode can be implemented using
2006 several different encodings. LilyPond uses the UTF-8 encoding
2007 (UTF stands for Unicode Transformation Format) which represents
2008 all common Latin characters in one byte, and represents other
2009 characters using a variable length format of up to four bytes.
2011 The actual appearance of the characters is determined by the
2012 glyphs defined in the particular fonts available - a font defines
2013 the mapping of a subset of the Unicode code points to glyphs.
2014 LilyPond uses the Pango library to layout and render multi-lingual
2017 LilyPond does not perform any input-encoding conversions. This
2018 means that any text, be it title, lyric text, or musical
2019 instruction containing non-ASCII characters, must be encoded in
2020 UTF-8. The easiest way to enter such text is by using a
2021 Unicode-aware editor and saving the file with UTF-8 encoding. Most
2022 popular modern editors have UTF-8 support, for example, vim, Emacs,
2023 jEdit, and GEdit do. All MS Windows systems later than NT use
2024 Unicode as their native character encoding, so even Notepad can
2025 edit and save a file in UTF-8 format. A more functional
2026 alternative for Windows is BabelPad.
2028 If a LilyPond input file containing a non-ASCII character is not
2029 saved in UTF-8 format the error message
2032 FT_Get_Glyph_Name () error: invalid argument
2037 Here is an example showing Cyrillic, Hebrew and Portuguese
2041 %c No verbatim here as the code does not display correctly in PDF
2043 bulgarian = \lyricmode {
2044 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
2048 hebrew = \lyricmode {
2049 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
2053 portuguese = \lyricmode {
2054 à vo -- cê uma can -- ção legal
2060 \addlyrics { \bulgarian }
2061 \addlyrics { \hebrew }
2062 \addlyrics { \portuguese }
2067 @unnumberedsubsubsec Unicode
2071 To enter a single character for which the Unicode code point is
2072 known but which is not available in the editor being used, use
2073 either @code{\char ##xhhhh} or @code{\char #dddd} within a
2074 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
2075 the character required and @code{dddd} is the corresponding decimal
2076 value. Leading zeroes may be omitted, but it is usual to specify
2077 all four characters in the hexadecimal representation. (Note that
2078 the UTF-8 encoding of the code point should @emph{not} be used
2079 after @code{\char}, as UTF-8 encodings contain extra bits indicating
2080 the number of octets.) Unicode code charts and a character name
2081 index giving the code point in hexadecimal for any character can be
2082 found on the Unicode Consortium website,
2083 @uref{http://www.unicode.org/}.
2085 For example, @code{\char ##x03BE} and @code{\char #958} would both
2086 enter the Unicode U+03BE character, which has the Unicode name
2087 @qq{Greek Small Letter Xi}.
2089 Any Unicode code point may be entered in this way and if all special
2090 characters are entered in this format it is not necessary to save
2091 the input file in UTF-8 format. Of course, a font containing all
2092 such encoded characters must be installed and available to LilyPond.
2094 The following example shows Unicode hexadecimal values being entered
2095 in four places -- in a rehearsal mark, as articulation text, in
2096 lyrics and as stand-alone text below the score:
2098 @lilypond[quote,verbatim]
2101 c1 \mark \markup { \char ##x03EE }
2102 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
2104 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
2106 \markup { "Copyright 2008--2012" \char ##x00A9 }
2109 @cindex copyright sign
2111 To enter the copyright sign in the copyright notice use:
2115 copyright = \markup @{ \char ##x00A9 "2008" @}
2121 @unnumberedsubsubsec ASCII aliases
2123 A list of ASCII aliases for special characters can be included:
2125 @lilypond[quote,verbatim]
2127 #(include-special-characters)
2130 \markup "&flqq; – &OE;uvre incomplète… &frqq;"
2133 \new Staff { \repeat unfold 9 a'4 }
2135 This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
2140 "The replacement can be disabled:"
2141 "– &OE; …"
2142 \override #'(replacement-alist . ()) "– &OE; …"
2146 You can also make your own aliases, either globally:
2148 @lilypond[quote,verbatim]
2150 #(add-text-replacements!
2151 '(("100" . "hundred")
2152 ("dpi" . "dots per inch")))
2154 \markup "A 100 dpi."
2159 @lilypond[quote,verbatim]
2160 \markup \replace #'(("100" . "hundred")
2161 ("dpi" . "dots per inch")) "A 100 dpi."
2166 @ref{List of special characters}.
2169 @file{ly/text-replacements.ly}.
2172 @node Controlling output
2173 @section Controlling output
2176 * Extracting fragments of music::
2177 * Skipping corrected music::
2178 * Alternative output formats::
2179 * Replacing the notation font::
2182 @node Extracting fragments of music
2183 @subsection Extracting fragments of music
2185 It is possible to quote small fragments of a large score directly from
2186 the output. This can be compared to clipping a piece of a paper score
2189 This is done by defining the measures that need to be cut out
2190 separately. For example, including the following definition
2198 (make-rhythmic-location 5 1 2)
2199 (make-rhythmic-location 7 3 4)))
2204 will extract a fragment starting halfway the fifth measure, ending in
2205 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
2206 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
2208 More clip regions can be defined by adding more pairs of
2209 rhythmic-locations to the list.
2211 In order to use this feature, LilyPond must be invoked with
2212 @option{-dclip-systems}. The clips are output as EPS files, and are
2213 converted to PDF and PNG if these formats are switched on as well.
2215 For more information on output formats, see @rprogram{Invoking lilypond}.
2217 @node Skipping corrected music
2218 @subsection Skipping corrected music
2221 @funindex skipTypesetting
2222 @funindex showFirstLength
2223 @funindex showLastLength
2225 When entering or copying music, usually only the music near the end (where
2227 are adding notes) is interesting to view and correct. To speed up
2228 this correction process, it is possible to skip typesetting of all but
2229 the last few measures. This is achieved by putting
2232 showLastLength = R1*5
2237 in your source file. This will render only the last 5 measures
2238 (assuming 4/4 time signature) of every @code{\score} in the input
2239 file. For longer pieces, rendering only a small part is often an order
2240 of magnitude quicker than rendering it completely. When working on the
2241 beginning of a score you have already typeset (e.g. to add a new part),
2242 the @code{showFirstLength} property may be useful as well.
2244 Skipping parts of a score can be controlled in a more fine-grained
2245 fashion with the property @code{Score.skipTypesetting}. When it is
2246 set, no typesetting is performed at all.
2248 This property is also used to control output to the MIDI file. Note that
2249 it skips all events, including tempo and instrument changes. You have
2252 @lilypond[quote,relative=2,ragged-right,verbatim]
2254 \set Score.skipTypesetting = ##t
2256 \set Score.skipTypesetting = ##f
2260 In polyphonic music, @code{Score.skipTypesetting} will affect all
2261 voices and staves, saving even more time.
2263 @node Alternative output formats
2264 @subsection Alternative output formats
2266 @cindex scalable vector graphics output
2268 @cindex encapsulated postscript output
2271 The default output formats for the printed score are Portable
2272 Document Format (PDF) and PostScript (PS). Scalable Vector
2273 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
2274 Network Graphics (PNG) output formats are also available through
2275 command line options, see
2276 @rprogram{Basic command line options for LilyPond}.
2279 @node Replacing the notation font
2280 @subsection Replacing the notation font
2282 Gonville is an alternative to the Feta font used in LilyPond and can
2285 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2288 Here are a few sample bars of music set in Gonville:
2290 @c NOTE: these images are a bit big, but that's important
2291 @c for the font comparison. -gp
2292 @sourceimage{Gonville_after,,,}
2294 Here are a few sample bars of music set in LilyPond's Feta font:
2296 @sourceimage{Gonville_before,,,}
2298 @subsubheading Installation Instructions for MacOS
2300 Download and extract the zip file. Copy the @code{lilyfonts}
2301 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2302 information, see @rlearning{Other sources of information}. Rename the
2303 existing @code{fonts} directory to @code{fonts_orig} and the
2304 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
2305 reverse the process.
2309 @rlearning{Other sources of information}.
2312 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2313 likely newer glyphs in later releases of LilyPond may not exist in the
2314 Gonville font family. Please refer to the author's website for more
2315 information on these and other specifics, including licensing of
2320 @section MIDI output
2325 MIDI (Musical Instrument Digital Interface) is a standard for
2326 connecting and controlling digital instruments. A MIDI file is a
2327 series of notes in a number of tracks. It is not an actual
2328 sound file; you need special software to translate between the
2329 series of notes and actual sounds.
2331 Pieces of music can be converted to MIDI files, so you can listen to
2332 what was entered. This is convenient for checking the music; octaves
2333 that are off or accidentals that were mistyped stand out very much
2334 when listening to the MIDI output.
2336 Standard MIDI output is somewhat crude; optionally, an enhanced and
2337 more realistic MIDI output is available by means of
2338 @ref{The Articulate script}.
2340 The MIDI output allocates a channel for each staff, and reserves channel
2341 10 for drums. There are only 16 MIDI channels per device, so if the
2342 score contains more than 15 staves, MIDI channels will be reused.
2345 * Creating MIDI files::
2347 * What goes into the MIDI output?::
2349 * Controlling MIDI dynamics::
2350 * Percussion in MIDI::
2351 * The Articulate script::
2354 @node Creating MIDI files
2355 @subsection Creating MIDI files
2357 To create a MIDI output file from a LilyPond input file, add a
2358 @code{\midi} block to a score, for example,
2367 If there is a @code{\midi} block in a @code{\score} with no
2368 @code{\layout} block, only MIDI output will be produced. When
2369 notation is needed too, a @code{\layout} block must also be
2380 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
2381 and translated correctly to the MIDI output. Dynamic marks,
2382 crescendi and decrescendi translate into MIDI volume levels.
2383 Dynamic marks translate to a fixed fraction of the available MIDI
2384 volume range. Crescendi and decrescendi make the volume vary
2385 linearly between their two extremes. The effect of dynamic markings
2386 on the MIDI output can be removed completely, see @ref{MIDI block}.
2388 The initial tempo and later tempo changes can be specified
2389 with the @code{\tempo} command within the music notation. These
2390 are reflected in tempo changes in the MIDI output. This command
2391 will normally result in the metronome mark being printed, but this
2392 can be suppressed, see @ref{Metronome marks}. An alternative way
2393 of specifying the initial or overall MIDI tempo is described below,
2394 see @ref{MIDI block}.
2396 Due to some limitations on Windows, the default extension for
2397 MIDI files on Windows is @code{.mid}. Other operating systems still
2398 use the extension @code{.midi}. If a different extension is preferred,
2399 insert the following line at the top-level of the input file,
2400 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
2403 #(ly:set-option 'midi-extension "midi")
2406 The line above will set the default extension for MIDI files to
2409 Alternatively, this option can also be supplied on the command line:
2412 lilypond … -dmidi-extension=midi lilyFile.ly
2416 @unnumberedsubsubsec Instrument names
2418 @cindex instrument names
2419 @funindex Staff.midiInstrument
2421 The MIDI instrument to be used is specified by setting the
2422 @code{Staff.midiInstrument} property to the instrument name.
2423 The name should be chosen from the list in @ref{MIDI instruments}.
2427 \set Staff.midiInstrument = #"glockenspiel"
2433 \new Staff \with @{midiInstrument = #"cello"@} @{
2438 If the selected instrument does not exactly match an instrument from
2439 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2445 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2446 {changing-midi-output-to-one-channel-per-voice.ly}
2450 @c In 2.11 the following no longer seems to be a problem -td
2452 Unterminated (de)crescendos will not render properly in the midi file,
2453 resulting in silent passages of music. The workaround is to explicitly
2454 terminate the (de)crescendo. For example,
2461 will not work properly but
2464 @{ a4\< b c d\!\f @}
2471 Changes in the MIDI volume take place only on starting a note, so
2472 crescendi and decrescendi cannot affect the volume of a
2475 Not all midi players correctly handle tempo changes in the midi
2476 output. Players that are known to work include MS Windows Media
2477 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2480 @subsection MIDI block
2483 A @code{\midi} block must appear within a score block if MIDI output
2484 is required. It is analogous to the layout block, but somewhat
2485 simpler. Often, the @code{\midi} block is left empty, but it
2486 can contain context rearrangements, new context definitions or code
2487 to set the values of properties. For example, the following will
2488 set the initial tempo exported to a MIDI file without causing a tempo
2489 indication to be printed:
2500 In this example the tempo is set to 72 quarter note
2501 beats per minute. @code{\tempo} is actually a music command for
2502 setting properties during the interpretation of music: in the
2503 context of output definitions like a @code{\midi} block, as a matter of
2504 courtesy those are reinterpreted as if they were context modifications.
2506 @cindex MIDI context definitions
2508 Context definitions follow precisely the same syntax as those
2509 within a @code{\layout} block. Translation modules for sound are
2510 called performers. The contexts for MIDI output are defined in
2511 @file{../ly/performer-init.ly},
2512 see @rlearning{Other sources of information}.
2513 For example, to remove the effect of dynamics
2514 from the MIDI output, insert the following lines in the
2515 @code{\midi@{ @}} block.
2522 \remove "Dynamic_performer"
2527 MIDI output is created only when a @code{\midi} block is included
2528 within a score block defined with a @code{\score} command.
2532 @{ @dots{}notes@dots{} @}
2537 @node What goes into the MIDI output?
2538 @subsection What goes into the MIDI output?
2540 @c TODO Check grace notes - timing is suspect?
2542 @unnumberedsubsubsec Supported in MIDI
2544 @cindex Pitches in MIDI
2545 @cindex MIDI, Pitches
2546 @cindex Quarter tones in MIDI
2547 @cindex MIDI, quarter tones
2548 @cindex Microtones in MIDI
2549 @cindex MIDI, microtones
2550 @cindex Chord names in MIDI
2551 @cindex MIDI, chord names
2552 @cindex Rhythms in MIDI
2553 @cindex MIDI, Rhythms
2554 @cindex Articlulate scripts
2555 @cindex MIDI, articulations
2556 @cindex articulations in MIDI
2557 @cindex trills in MIDI
2558 @cindex turns in MIDI
2559 @cindex rallentando in MIDI
2560 @cindex accelerando in MIDI
2563 The following items of notation are reflected in the MIDI output:
2567 @item Microtones (See @ref{Accidentals}. Rendering needs a
2568 player that supports pitch bend.)
2569 @item Chords entered as chord names
2570 @item Rhythms entered as note durations, including tuplets
2571 @item Tremolos entered without @q{@code{:}[@var{number}]}
2574 @item Crescendi, decrescendi over multiple notes
2575 @item Tempo changes entered with a tempo marking
2579 Using @ref{The Articulate script}, a number of items are added to the
2583 @item Articulations (slurs, staccato, etc)
2585 @item Rallentando and accelerando
2589 @unnumberedsubsubsec Unsupported in MIDI
2591 @c TODO index as above
2593 The following items of notation have no effect on the MIDI output,
2594 unless you use @ref{The Articulate script}:
2597 @item Rhythms entered as annotations, e.g. swing
2598 @item Tempo changes entered as annotations with no tempo marking
2599 @item Staccato and other articulations and ornamentations
2600 @item Slurs and Phrasing slurs
2601 @item Crescendi, decrescendi over a single note
2602 @item Tremolos entered with @q{@code{:}[@var{number}]}
2604 @item Microtonal chords
2608 @node Repeats in MIDI
2609 @subsection Repeats in MIDI
2611 @cindex repeats in MIDI
2612 @funindex \unfoldRepeats
2614 With a few minor additions, all types of repeats can be represented
2615 in the MIDI output. This is achieved by applying the
2616 @code{\unfoldRepeats} music function. This function changes all
2617 repeats to unfold repeats.
2619 @lilypond[quote,verbatim]
2621 \repeat tremolo 8 { c'32 e' }
2622 \repeat percent 2 { c''8 d'' }
2623 \repeat volta 2 { c'4 d' e' f' }
2632 In scores containing multiple voices, unfolding of repeats in MIDI
2633 output will only occur correctly if @emph{each} voice contains fully
2634 notated repeat indications.
2636 When creating a score file using @code{\unfoldRepeats} for MIDI,
2637 it is necessary to make two @code{\score} blocks: one for MIDI
2638 (with unfolded repeats) and one for notation (with volta, tremolo,
2639 and percent repeats). For example,
2647 \unfoldRepeats @var{..music..}
2652 @node Controlling MIDI dynamics
2653 @subsection Controlling MIDI dynamics
2655 MIDI dynamics are implemented by the Dynamic_performer which lives
2656 by default in the Voice context. It is possible to control the
2657 overall MIDI volume, the relative volume of dynamic markings and
2658 the relative volume of different instruments.
2660 @unnumberedsubsubsec Dynamic marks
2662 Dynamic marks are translated to a fixed fraction of the available
2663 MIDI volume range. The default fractions range from 0.25 for
2664 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
2665 marks and the associated fractions can be seen in
2666 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2667 This set of fractions may be changed or extended by providing a
2668 function which takes a dynamic mark as its argument and returns the
2669 required fraction, and setting
2670 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
2672 For example, if a @notation{rinforzando} dynamic marking,
2673 @code{\rfz}, is required, this will not by default
2674 have any effect on the MIDI volume, as this dynamic marking is not
2675 included in the default set. Similarly, if a new dynamic marking
2676 has been defined with @code{make-dynamic-script} that too will not
2677 be included in the default set. The following example shows how the
2678 MIDI volume for such dynamic markings might be added. The Scheme
2679 function sets the fraction to 0.9 if a dynamic mark of rfz is
2680 found, or calls the default function otherwise.
2682 @lilypond[verbatim,quote]
2683 #(define (myDynamics dynamic)
2684 (if (equal? dynamic "rfz")
2686 (default-dynamic-absolute-volume dynamic)))
2690 \set Staff.midiInstrument = #"cello"
2691 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
2703 Alternatively, if the whole table of fractions needs to be
2704 redefined, it would be better to use the
2705 @notation{default-dynamic-absolute-volume} procedure in
2706 @file{../scm/midi.scm} and the associated table as a model.
2707 The final example in this section shows how this might be done.
2709 @unnumberedsubsubsec Overall MIDI volume
2711 The minimum and maximum overall volume of MIDI dynamic markings is
2712 controlled by setting the properties @code{midiMinimumVolume} and
2713 @code{midiMaximumVolume} at the @code{Score} level. These
2714 properties have an effect only on dynamic marks, so if they
2715 are to apply from the start of the score a dynamic mark must be
2716 placed there. The fraction corresponding to each dynamic mark is
2717 modified with this formula
2720 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2723 In the following example the dynamic range of the overall MIDI
2724 volume is limited to the range 0.2 - 0.5.
2726 @lilypond[verbatim,quote]
2732 \set Staff.midiInstrument = #"flute"
2733 \new Voice \relative c''' {
2741 \set Staff.midiInstrument = #"clarinet"
2742 \new Voice \relative c'' {
2754 midiMinimumVolume = #0.2
2755 midiMaximumVolume = #0.5
2761 @unnumberedsubsubsec Equalizing different instruments (i)
2763 If the minimum and maximum MIDI volume properties are set in
2764 the @code{Staff} context the relative volumes of the MIDI
2765 instruments can be controlled. This gives a basic instrument
2766 equalizer, which can enhance the quality of the MIDI output
2769 In this example the volume of the clarinet is reduced relative
2770 to the volume of the flute. There must be a dynamic
2771 mark on the first note of each instrument for this to work
2774 @lilypond[verbatim,quote]
2780 \set Staff.midiInstrument = #"flute"
2781 \set Staff.midiMinimumVolume = #0.7
2782 \set Staff.midiMaximumVolume = #0.9
2783 \new Voice \relative c''' {
2791 \set Staff.midiInstrument = #"clarinet"
2792 \set Staff.midiMinimumVolume = #0.3
2793 \set Staff.midiMaximumVolume = #0.6
2794 \new Voice \relative c'' {
2808 @unnumberedsubsubsec Equalizing different instruments (ii)
2810 If the MIDI minimum and maximum volume properties are not set
2811 LilyPond will, by default, apply a small degree of equalization
2812 to a few instruments. The instruments and the equalization
2813 applied are shown in the table @notation{instrument-equalizer-alist}
2814 in @file{../scm/midi.scm}.
2816 This basic default equalizer can be replaced by setting
2817 @code{instrumentEqualizer} in the @code{Score} context to a new
2818 Scheme procedure which accepts a MIDI instrument name as its only
2819 argument and returns a pair of fractions giving the minimum and
2820 maximum volumes to be applied to that instrument. This replacement
2821 is done in the same way as shown for resetting the
2822 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
2823 The default equalizer, @notation{default-instrument-equalizer}, in
2824 @file{../scm/midi.scm} shows how such a procedure might be written.
2826 The following example sets the relative flute and clarinet volumes
2827 to the same values as the previous example.
2829 @lilypond[verbatim,quote]
2830 #(define my-instrument-equalizer-alist '())
2832 #(set! my-instrument-equalizer-alist
2835 ("flute" . (0.7 . 0.9))
2836 ("clarinet" . (0.3 . 0.6)))
2837 my-instrument-equalizer-alist))
2839 #(define (my-instrument-equalizer s)
2840 (let ((entry (assoc s my-instrument-equalizer-alist)))
2849 \set Score.instrumentEqualizer = #my-instrument-equalizer
2850 \set Staff.midiInstrument = #"flute"
2851 \new Voice \relative c''' {
2859 \set Staff.midiInstrument = #"clarinet"
2860 \new Voice \relative c'' {
2875 @c Delete when satisfied this is adequately covered elsewhere -td
2877 @n ode Microtones in MIDI
2878 @s ubsection Microtones in MIDI
2880 @cindex microtones in MIDI
2882 Microtones consisting of half sharps and half flats are exported
2883 to the MIDI file and render correctly in MIDI players which support
2884 pitch bending. See @ref{Note names in other languages}. Here is
2885 an example showing all the half sharps and half flats. It can be
2886 copied out and compiled to test microtones in your MIDI player.
2888 @lilypond[verbatim,quote]
2905 @node Percussion in MIDI
2906 @subsection Percussion in MIDI
2908 Percussion instruments are generally notated in a @code{DrumStaff}
2909 context and when notated in this way they are outputted correctly
2910 to MIDI channel@tie{}10, but some pitched percussion instruments,
2911 like the xylophone, marimba, vibraphone, timpani, etc., are
2912 treated like @qq{normal} instruments and music for these instruments
2913 should be entered in a normal @code{Staff} context, not a
2914 @code{DrumStaff} context, to obtain the correct MIDI output.
2916 Some non-pitched percussion sounds included in the general MIDI
2917 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2918 be reached via MIDI channel@tie{}10, so the notation for such
2919 instruments should also be entered in a normal @code{Staff}
2920 context, using suitable normal pitches.
2922 Many percussion instruments are not included in the general MIDI
2923 standard, e.g. castanets. The easiest, although unsatisfactory,
2924 method of producing some MIDI output when writing for such
2925 instruments is to substitute the nearest sound from the standard
2928 @c TODO Expand with examples, and any other issues
2932 Because the general MIDI standard does not contain rim shots, the
2933 sidestick is used for this purpose instead.
2935 @node The Articulate script
2936 @subsection The Articulate script
2938 A more realistic MIDI output is possible when using the Articulate
2939 script. It tries to take articulations (slurs, staccato, etc) into
2940 account, by replacing notes with sequential music of suitably
2941 time-scaled note plus skip. It also tries to unfold trills turns
2942 etc., and take rallentando and accelerando into account.
2944 To use the Articulate script, you have to include it at the top of
2948 \include "articulate.ly"
2951 and in the @code{\score} section do
2954 \unfoldRepeats \articulate <<
2955 all the rest of the score...
2959 After altering your input file this way, the visual output is heavily
2960 altered, but the standard @code{\midi} block will produce a better
2963 Although not essential for the Articulate script to work, you may want
2964 to insert the @code{\unfoldRepeats} command as it appears in the
2965 example shown above as it enables performing abbreviatures such as
2970 Articulate shortens chords and some music (esp. organ music) could
2974 @node Extracting musical information
2975 @section Extracting musical information
2977 In addition to creating graphical output and MIDI, LilyPond can
2978 display musical information as text.
2981 * Displaying LilyPond notation::
2982 * Displaying scheme music expressions::
2983 * Saving music events to a file::
2986 @node Displaying LilyPond notation
2987 @subsection Displaying LilyPond notation
2989 @funindex \displayLilyMusic
2990 Displaying a music expression in LilyPond notation can be
2991 done with the music function @code{\displayLilyMusic}. To see the
2992 output, you will typically want to call LilyPond using the command
2997 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3004 @{ a,4 cis e fis g @}
3007 By default, LilyPond will print these messages to the console
3008 along with all the other LilyPond compilation messages. To split
3009 up these messages and save the results of @code{\display@{STUFF@}},
3010 redirect the output to a file.
3013 lilypond file.ly >display.txt
3017 Note that Lilypond does not just display the music expression, but
3018 also interprets it (since @code{\displayLilyMusic} returns it in
3019 addition to displaying it). This is convenient since you can just
3020 insert @code{\displayLilyMusic} into existing music in order to get
3021 information about it. If you don't actually want Lilypond to
3022 interpret the displayed music as well as display it, use @code{\void}
3023 in order to have it ignored:
3027 \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3032 @node Displaying scheme music expressions
3033 @subsection Displaying scheme music expressions
3035 See @rextend{Displaying music expressions}.
3038 @node Saving music events to a file
3039 @subsection Saving music events to a file
3041 Music events can be saved to a file on a per-staff basis by
3042 including a file in your main score.
3045 \include "event-listener.ly"
3048 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
3049 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
3050 you have multiple unnamed staves, the events for all staves will
3051 be mixed together in the same file. The output looks like this:
3054 0.000 note 57 4 p-c 2 12
3056 0.250 note 62 4 p-c 7 12
3057 0.500 note 66 8 p-c 9 12
3058 0.625 note 69 8 p-c 14 12
3063 The syntax is a tab-delimited line, with two fixed fields on each
3064 line followed by optional parameters.
3067 @var{time} @var{type} @var{...params...}
3070 This information can easily be read into other programs such as
3071 python scripts, and can be very useful for researchers wishing to
3072 perform musical analysis or playback experiments with LilyPond.
3077 Not all lilypond music events are supported by
3078 @file{event-listener.ly}. It is intended to be a well-crafted
3079 @qq{proof of concept}. If some events that you want to see are
3080 not included, copy @file{event-listener.ly} into your lilypond
3081 directory and modify the file so that it outputs the information