1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
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. See TRANSLATION for details.
15 This section deals with general LilyPond input syntax issues,
16 rather than specific notation.
18 FIXME: don't complain about anything in this chapter. It's still
19 under heavy development.
29 * Useful concepts and properties::
30 * Titles and headers::
31 * Working with input files::
32 * Controlling output::
37 @section Input structure
39 The main format of input for LilyPond are text files. By convention,
40 these files end with @code{.ly}.
43 * Structure of a score::
44 * Multiple scores in a book::
49 @node Structure of a score
50 @subsection Structure of a score
52 A @code{\score} must contain a single music expression. However,
53 this music expression may be of any size. Recall that music
54 expressions may be included inside other expressions to form
55 larger expressions. All of these examples are single music
56 expressions; note the curly braces @{ @} or angle brackets <<
57 >> at the beginning and ending of the music.
63 @lilypond[ragged-right,verbatim,quote]
70 @lilypond[ragged-right,verbatim,quote]
72 \new Staff { c'4 c' c' c' }
73 \new Staff { d'4 d' d' d' }
81 \new Staff @{ \flute @}
82 \new Staff @{ \oboe @}
85 \new Staff @{ \violinI @}
86 \new Staff @{ \violinII @}
93 @node Multiple scores in a book
94 @subsection Multiple scores in a book
97 @cindex movements, multiple
99 A document may contain multiple pieces of music and texts. Examples
100 of these are an etude book, or an orchestral part with multiple
101 movements. Each movement is entered with a @code{\score} block,
109 and texts are entered with a @code{\markup} block,
119 All the movements and texts which appear in the same @code{.ly} file
120 will normally be typeset in the form of a single output file.
134 However, if you want multiple output files from the same @code{.ly}
135 file, then you can add multiple @code{\book} blocks, where each such
136 @code{\book} block will result in a separate output. If you do not
137 specify any @code{\book} block in the file, LilyPond will implicitly
138 treat the full file as a single @code{\book} block, see @ref{File
139 structure}. One important exception is within lilypond-book documents,
140 where you explicitly have to add a @code{\book} block, otherwise only
141 the first @code{\score} or @code{\markup} will appear in the output.
143 The header for each piece of music can be put inside the @code{\score}
144 block. The @code{piece} name from the header will be printed before
145 each movement. The title for the entire book can be put inside the
146 @code{\book}, but if it is not present, the @code{\header} which is at
147 the top of the file is inserted.
151 title = "Eight miniatures"
152 composer = "Igor Stravinsky"
156 \header @{ piece = "Romanze" @}
159 ..text of second verse..
162 ..text of third verse..
166 \header @{ piece = "Menuetto" @}
171 @subsection File structure
173 A @code{.ly} file contains any number of toplevel expressions, where a
174 toplevel expression is one of the following
178 An output definition, such as @code{\paper}, @code{\midi}, and
179 @code{\layout}. Such a definition at the toplevel changes the default
180 settings for the block entered.
183 A direct scheme expression, such as
184 @code{#(set-default-paper-size "a7" 'landscape)} or
185 @code{#(ly:set-option 'point-and-click #f)}.
188 A @code{\header} block. This sets the global header block. This
189 is the block containing the definitions for book-wide settings, like
190 composer, title, etc.
193 A @code{\score} block. This score will be collected with other
194 toplevel scores, and combined as a single @code{\book}.
196 This behavior can be changed by setting the variable
197 @code{toplevel-score-handler} at toplevel. The default handler is
198 defined in the init file @file{scm/@/lily@/.scm}.
200 The @code{\score} must begin with a music expression, and may
201 contain only one music expression.
204 A @code{\book} block logically combines multiple movements
205 (i.e., multiple @code{\score} blocks) in one document. If there are
206 a number of @code{\scores}, one output file will be created for
207 each @code{\book} block, in which all corresponding movements are
208 concatenated. The only reason to explicitly specify @code{\book} blocks
209 in a @code{.ly} file is if you wish multiple output files from a single
210 input file. One exception is within lilypond-book documents, where you
211 explicitly have to add a @code{\book} block if you want more than a
212 single @code{\score} or @code{\markup} in the same example.
214 This behavior can be changed by setting the variable
215 @code{toplevel-book-handler} at toplevel. The default handler is
216 defined in the init file @file{scm/@/lily@/.scm}.
219 A compound music expression, such as
224 This will add the piece in a @code{\score} and format it in a
225 single book together with all other toplevel @code{\score}s and music
226 expressions. In other words, a file containing only the above
227 music expression will be translated into
243 This behavior can be changed by setting the variable
244 @code{toplevel-music-handler} at toplevel. The default handler is
245 defined in the init file @file{scm/@/lily@/.scm}.
248 A markup text, a verse for example
251 2. The first line verse two.
255 Markup texts are rendered above, between or below the scores or music
256 expressions, wherever they appear.
266 This can be used later on in the file by entering @code{\foo}. The
267 name of an variable should have alphabetic characters only; no
268 numbers, underscores or dashes.
272 The following example shows three things that may be entered at
277 % movements are non-justified by default
289 At any point in a file, any of the following lexical instructions can
293 @item @code{\version}
294 @item @code{\include}
295 @item @code{\sourcefilename}
296 @item @code{\sourcefileline}
301 @node Useful concepts and properties
302 @section Useful concepts and properties
308 * Controlling direction and placement::
309 * Distances and measurements::
314 @subsection Input modes
318 \notemode turns the front end of LilyPond into note mode
319 (which is the default parsing mode).
320 It's certainly useful in certain situations, for example if you
321 are in \lyricmode or \chordmode or ... and want to insert
322 something that only can be done with \notemode syntax.
325 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
326 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
327 http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
328 http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html
336 @node When to add a -
337 @subsection When to add a -
339 One of these works, the other doesn't.
343 { c'\mp\fermata\accent-\markup { "forcefully"} }
344 % { c'\mp\fermata\accent\markup { "forcefully"} }
347 @node Controlling direction and placement
348 @subsection Controlling direction and placement
352 By default, LilyPond does a pretty jazz'n job of picking
353 directions. But in some cases, it may be desirable to force a
367 Maybe rename section to "directions".
369 Also mention \override Foo #'direction = #'DOWN.
371 also mention the typical \fooDown, \fooNeutral predefined commands.
373 also mention that some directions are (without other tweaking)
374 always up or always down (like dynamics or fermata), while other
375 things can alternate between up or down based on the stem direction
376 (like slurs or accents).
379 @node Distances and measurements
380 @subsection Distances and measurements
382 DISCUSS after working on other sections.
384 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
391 @node Titles and headers
392 @section Titles and headers
394 Almost all printed music includes a title and the composer's name;
395 some pieces include a lot more information.
400 * Reference to page numbers::
401 * Table of contents::
405 @node Creating titles
406 @subsection Creating titles
408 Titles are created for each @code{\score} block, as well as for the full
409 input file (or @code{\book} block).
411 The contents of the titles are taken from the @code{\header} blocks.
412 The header block for a book supports the following
418 The dedicatee of the music, centered at the top of the first page.
422 The title of the music, centered just below the dedication.
426 Subtitle, centered below the title.
428 @funindex subsubtitle
430 Subsubtitle, centered below the subtitle.
434 Name of the poet, flush-left below the subtitle.
438 Name of the composer, flush-right below the subtitle.
442 Meter string, flush-left below the poet.
446 Name of the opus, flush-right below the composer.
450 Name of the arranger, flush-right below the opus.
454 Name of the instrument, centered below the arranger. Also
455 centered at the top of pages (other than the first page).
459 Name of the piece, flush-left below the instrument.
461 @cindex page breaks, forcing
462 @funindex breakbefore
464 This forces the title to start on a new page (set to ##t or ##f).
468 Copyright notice, centered at the bottom of the first page. To
469 insert the copyright symbol, see @ref{Text encoding}.
473 Centered at the bottom of the last page.
477 Here is a demonstration of the fields available. Note that you
478 may use any @ref{Formatting text}, commands in the header.
480 @lilypond[quote,verbatim,line-width=11.0\cm]
483 paper-height = 10.0\cm
488 dedication = "dedicated to me"
489 title = \markup \center-align { "Title first line" "Title second line,
491 subtitle = "the subtitle,"
492 subsubtitle = #(string-append "subsubtitle LilyPond version "
495 composer = \markup \center-align { "composer" \small "(1847-1973)" }
496 texttranslator = "Text Translator"
497 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
499 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
500 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
501 instrument = \markup \bold \italic "instrument"
525 As demonstrated before, you can use multiple @code{\header} blocks.
526 When same fields appear in different blocks, the latter is used.
527 Here is a short example.
531 composer = "Composer"
539 piece = "New piece" % overwrite previous one
544 If you define the @code{\header} inside the @code{\score} block, then
545 normally only the @code{piece} and @code{opus} headers will be printed.
546 Note that the music expression must come before the @code{\header}.
548 @lilypond[quote,verbatim,line-width=11.0\cm]
552 title = "title" % not printed
559 @funindex printallheaders
561 You may change this behavior (and print all the headers when defining
562 @code{\header} inside @code{\score}) by using
573 The default footer is empty, except for the first page, where the
574 @code{copyright} field from @code{\header} is inserted, and the last
575 page, where @code{tagline} from @code{\header} is added. The default
576 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
577 printed parts are good PR for us, so please leave the tagline if you
580 Headers may be completely removed by setting them to false.
591 @subsection Custom titles
593 A more advanced option is to change the definitions of the following
594 variables in the @code{\paper} block. The init file
595 @file{ly/titling-init.ly} lists the default layout.
598 @funindex bookTitleMarkup
599 @item bookTitleMarkup
600 This is the title added at the top of the entire output document.
601 Typically, it has the composer and the title of the piece
603 @funindex scoreTitleMarkup
604 @item scoreTitleMarkup
605 This is the title put over a @code{\score} block. Typically, it has
606 the name of the movement (@code{piece} field).
608 @funindex oddHeaderMarkup
609 @item oddHeaderMarkup
610 This is the page header for odd-numbered pages.
612 @funindex evenHeaderMarkup
613 @item evenHeaderMarkup
614 This is the page header for even-numbered pages. If unspecified,
615 the odd header is used instead.
617 By default, headers are defined such that the page number is on the
618 outside edge, and the instrument is centered.
620 @funindex oddFooterMarkup
621 @item oddFooterMarkup
622 This is the page footer for odd-numbered pages.
624 @funindex evenFooterMarkup
625 @item evenFooterMarkup
626 This is the page footer for even-numbered pages. If unspecified,
627 the odd header is used instead.
629 By default, the footer has the copyright notice on the first, and
630 the tagline on the last page.
640 The following definition will put the title flush left, and the
641 composer flush right on a single line.
645 bookTitleMarkup = \markup {
647 \fromproperty #'header:title
648 \fromproperty #'header:composer
654 @node Reference to page numbers
655 @subsection Reference to page numbers
657 A particular place of a score can be marked using the @code{\label}
658 command, either at top-level or inside music. This label can then be
659 referred to in a markup, to get the number of the page where the marked
660 point is placed, using the @code{\page-ref} markup command.
662 @lilypond[verbatim,line-width=11.0\cm]
663 \header { tagline = ##f }
669 \pageBreak \mark A \label #'markA
674 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
675 \markup { Mark A is on page \page-ref #'markA "0" "?" }
679 The @code{\page-ref} markup command takes three arguments:
681 @item the label, a scheme symbol, eg. @code{#'firstScore};
682 @item a markup that will be used as a gauge to estimate the dimensions
684 @item a markup that will be used in place of the page number if the label
688 The reason why a gauge is needed is that, at the time markups are
689 interpreted, the page breaking has not yet occurred, so the page numbers
690 are not yet known. To work around this issue, the actual markup
691 interpretation is delayed to a later time; however, the dimensions of
692 the markup have to be known before, so a gauge is used to decide these
693 dimensions. If the book has between 10 and 99 pages, it may be "00",
694 ie. a two digit number.
703 @node Table of contents
704 @subsection Table of contents
705 A table of contents is included using the @code{\markuplines \table-of-contents}
706 command. The elements which should appear in the table of contents are
707 entered with the @code{\tocItem} command, which may be used either at
708 top-level, or inside a music expression.
711 \markuplines \table-of-contents
714 \tocItem \markup "First score"
718 \tocItem \markup "Some particular point in the first score"
723 \tocItem \markup "Second score"
731 The markups which are used to format the table of contents are defined
732 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
733 for formatting the title of the table, and @code{tocItemMarkup}, for
734 formatting the toc elements, composed of the element title and page
735 number. These variables may be changed by the user:
739 %% Translate the toc title into French:
740 tocTitleMarkup = \markup \huge \column {
741 \fill-line { \null "Table des matières" \null }
744 %% use larger font size
745 tocItemMarkup = \markup \large \fill-line {
746 \fromproperty #'toc:text \fromproperty #'toc:page
751 Note how the toc element text and page number are referred to in
752 the @code{tocItemMarkup} definition.
754 New commands and markups may also be defined to build more elaborated
757 @item first, define a new markup variable in the @code{\paper} block
758 @item then, define a music function which aims at adding a toc element
759 using this markup paper variable.
762 In the following example, a new style is defined for entering act names
763 in the table of contents of an opera:
767 tocActMarkup = \markup \large \column {
769 \fill-line { \null \italic \fromproperty #'toc:text \null }
775 #(define-music-function (parser location text) (markup?)
776 (add-toc-item! 'tocActMarkup text))
779 @lilypond[line-width=11.0\cm]
780 \header { tagline = ##f }
782 tocActMarkup = \markup \large \column {
784 \fill-line { \null \italic \fromproperty #'toc:text \null }
790 #(define-music-function (parser location text) (markup?)
791 (add-toc-item! 'tocActMarkup text))
794 \markuplines \table-of-contents
795 \tocAct \markup { Atto Primo }
796 \tocItem \markup { Coro. Viva il nostro Alcide }
797 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
798 \tocAct \markup { Atto Secondo }
799 \tocItem \markup { Sinfonia }
800 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
807 Init files: @file{ly/@/toc@/-init@/.ly}.
811 @funindex \table-of-contents
812 @code{\table-of-contents}
817 @node Working with input files
818 @section Working with input files
821 * Including LilyPond files::
822 * Different editions from one source::
824 * Displaying LilyPond notation::
828 @node Including LilyPond files
829 @subsection Including LilyPond files
832 @cindex including files
834 A large project may be split up into separate files. To refer to another
838 \include "otherfile.ly"
841 The line @code{\include "file.ly"} is equivalent to pasting the contents
842 of file.ly into the current file at the place where you have the
843 \include. For example, for a large project you might write separate files
844 for each instrument part and create a @q{full score} file which brings
845 together the individual instrument files.
847 The initialization of LilyPond is done in a number of files that are
848 included by default when you start the program, normally transparent to the
849 user. Run @code{lilypond --verbose} to see a list of paths and files that Lily
852 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
853 VERSION is in the form @q{2.6.1}) are on the path and available to
854 @code{\include}. Files in the
855 current working directory are available to \include, but a file of the same
856 name in LilyPond's installation takes precedence. Files are
857 available to \include from directories in the search path specified as an
858 option when invoking @code{lilypond --include=DIR} which adds DIR to the
861 The @code{\include} statement can use full path information, but with the UNIX
862 convention @code{/} rather than the DOS/Windows @code{\}. For example,
863 if @file{stuff.ly} is located one directory higher than the current working
867 \include "../stuff.ly"
871 @node Different editions from one source
872 @subsection Different editions from one source
877 The @code{\tag} command marks music expressions with a name. These
878 tagged expressions can be filtered out later. With this mechanism it
879 is possible to make different versions of the same music source.
881 In the following example, we see two versions of a piece of music, one
882 for the full score, and one with cue notes for the instrumental part
898 The same can be applied to articulations, texts, etc.: they are
901 -\tag #@var{your-tag}
903 to an articulation, for example,
908 This defines a note with a conditional fingering indication.
911 @cindex removeWithTag
912 By applying the @code{\keepWithTag} and @code{\removeWithTag}
913 commands, tagged expressions can be filtered. For example,
917 \keepWithTag #'score @var{the music}
918 \keepWithTag #'part @var{the music}
924 @c @lilypondfile[ragged-right,quote]{tag-filter.ly}
926 The arguments of the @code{\tag} command should be a symbol
927 (such as @code{#'score} or @code{#'part}), followed by a
928 music expression. It is possible to put multiple tags on
929 a piece of music with multiple @code{\tag} entries,
932 \tag #'original-part \tag #'transposed-part @dots{}
938 Multiple rests are not merged if you create the score with both tagged
943 @subsection Text encoding
945 LilyPond uses the Pango library to format multi-lingual texts, and
946 does not perform any input-encoding conversions. This means that any
947 text, be it title, lyric text, or musical instruction containing
948 non-ASCII characters, must be utf-8. The easiest way to enter such text is
949 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
950 popular modern editors have utf-8 support, for example, vim, Emacs,
953 @c Currently not working
955 Depending on the fonts installed, the following fragment shows Hebrew
962 @li lypondfile[fontload]{utf-8.ly}
964 The @TeX{} backend does not handle encoding specially at all. Strings
965 in the input are put in the output as-is. Extents of text items in the
966 @TeX{} backend, are determined by reading a file created via the
967 @file{texstr} backend,
970 lilypond -dbackend=texstr input/les-nereides.ly
971 latex les-nereides.texstr
974 The last command produces @file{les-nereides.textmetrics}, which is
975 read when you execute
978 lilypond -dbackend=tex input/les-nereides.ly
981 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
982 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
983 interpreting non-ASCII strings.
987 To use a Unicode escape sequence, use
990 #(ly:export (ly:wide-char->utf-8 #x2014))
994 @node Displaying LilyPond notation
995 @subsection Displaying LilyPond notation
997 @funindex \displayLilyMusic
998 Displaying a music expression in LilyPond notation can be
999 done using the music function @code{\displayLilyMusic}. For example,
1003 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1010 @{ a, cis e fis g @}
1013 By default, LilyPond will print these messages to the console along
1014 with all the other messages. To split up these messages and save
1015 the results of @code{\display@{STUFF@}}, redirect the output to
1019 lilypond file.ly >display.txt
1024 @node Controlling output
1025 @section Controlling output
1028 * Extracting fragments of notation::
1029 * Skipping corrected music::
1032 @node Extracting fragments of notation
1033 @subsection Extracting fragments of notation
1035 It is possible to quote small fragments of a large score directly from
1036 the output. This can be compared to clipping a piece of a paper score
1039 This is done by defining the measures that need to be cut out
1040 separately. For example, including the following definition
1048 (make-rhythmic-location 5 1 2)
1049 (make-rhythmic-location 7 3 4)))
1054 will extract a fragment starting halfway the fifth measure, ending in
1055 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1056 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1058 More clip regions can be defined by adding more pairs of
1059 rhythmic-locations to the list.
1061 In order to use this feature, LilyPond must be invoked with
1062 @code{-dclip-systems}. The clips are output as EPS files, and are
1063 converted to PDF and PNG if these formats are switched on as well.
1065 For more information on output formats, see @rprogram{Invoking lilypond}.
1067 @node Skipping corrected music
1068 @subsection Skipping corrected music
1071 @funindex skipTypesetting
1072 @funindex showLastLength
1074 When entering or copying music, usually only the music near the end (where
1076 are adding notes) is interesting to view and correct. To speed up
1077 this correction process, it is possible to skip typesetting of all but
1078 the last few measures. This is achieved by putting
1081 showLastLength = R1*5
1086 in your source file. This will render only the last 5 measures
1087 (assuming 4/4 time signature) of every @code{\score} in the input
1088 file. For longer pieces, rendering only a small part is often an order
1089 of magnitude quicker than rendering it completely
1091 Skipping parts of a score can be controlled in a more fine-grained
1092 fashion with the property @code{Score.skipTypesetting}. When it is
1093 set, no typesetting is performed at all.
1095 This property is also used to control output to the MIDI file. Note that
1096 it skips all events, including tempo and instrument changes. You have
1099 @lilypond[quote,fragment,ragged-right,verbatim]
1102 \set Score.skipTypesetting = ##t
1104 \set Score.skipTypesetting = ##f
1108 In polyphonic music, @code{Score.skipTypesetting} will affect all
1109 voices and staves, saving even more time.