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.
23 * Useful concepts and properties::
24 * Titles and headers::
25 * Working with input files::
26 * Controlling output::
31 @section Input structure
33 The main format of input for LilyPond are text files. By convention,
34 these files end with @code{.ly}.
37 * Structure of a score::
38 * Multiple scores in a book::
43 @node Structure of a score
44 @subsection Structure of a score
48 A @code{\score} block must contain a single music expression
49 delimited by curly brackets:
57 @warning{There must be @strong{only one} outer music expression in
58 a @code{\score} block, and it @strong{must} be surrounded by
61 This single music expression may be of any size, and may contain
62 other music expressions to any complexity. All of these examples
63 are music expressions:
69 @lilypond[verbatim,quote]
76 @lilypond[verbatim,quote]
78 \new Staff { c'4 c' c' c' }
79 \new Staff { d'4 d' d' d' }
87 \new Staff @{ \flute @}
88 \new Staff @{ \oboe @}
91 \new Staff @{ \violinI @}
92 \new Staff @{ \violinII @}
98 Comments are one exception to this general rule. (For others see
99 @ref{File structure}.) Both single-line comments and comments
100 delimited by @code{%@{ .. %@}} may be placed anywhere within an
101 input file. They may be placed inside or outside a @code{\score}
102 block, and inside or outside the single music expression within a
109 @rlearning{Working on input files},
110 @rlearning{Music expressions explained},
111 @rlearning{Score is a single (compound) music expression}.
114 @node Multiple scores in a book
115 @subsection Multiple scores in a book
118 @cindex movements, multiple
120 A document may contain multiple pieces of music and text. Examples
121 of these are an etude book, or an orchestral part with multiple
122 movements. Each movement is entered with a @code{\score} block,
130 and texts are entered with a @code{\markup} block,
140 All the movements and texts which appear in the same @code{.ly} file
141 will normally be typeset in the form of a single output file.
155 However, if you want multiple output files from the same @code{.ly}
156 file, then you can add multiple @code{\book} blocks, where each such
157 @code{\book} block will result in a separate output. If you do not
158 specify any @code{\book} block in the file, LilyPond will implicitly
159 treat the full file as a single @code{\book} block, see @ref{File
160 structure}. One important exception is within lilypond-book documents,
161 where you explicitly have to add a @code{\book} block, otherwise only
162 the first @code{\score} or @code{\markup} will appear in the output.
164 The header for each piece of music can be put inside the @code{\score}
165 block. The @code{piece} name from the header will be printed before
166 each movement. The title for the entire book can be put inside the
167 @code{\book}, but if it is not present, the @code{\header} which is at
168 the top of the file is inserted.
172 title = "Eight miniatures"
173 composer = "Igor Stravinsky"
177 \header @{ piece = "Romanze" @}
180 ..text of second verse..
183 ..text of third verse..
187 \header @{ piece = "Menuetto" @}
192 @subsection File structure
201 A @code{.ly} file may contain any number of toplevel expressions, where a
202 toplevel expression is one of the following:
206 An output definition, such as @code{\paper}, @code{\midi}, and
207 @code{\layout}. Such a definition at the toplevel changes the default
208 book-wide settings. If more than one such definition of
209 the same type is entered at the top level any definitions in the later
210 expressions have precedence.
213 A direct scheme expression, such as
214 @code{#(set-default-paper-size "a7" 'landscape)} or
215 @code{#(ly:set-option 'point-and-click #f)}.
218 A @code{\header} block. This sets the global header block. This
219 is the block containing the definitions for book-wide settings, like
220 composer, title, etc.
223 A @code{\score} block. This score will be collected with other
224 toplevel scores, and combined as a single @code{\book}.
225 This behavior can be changed by setting the variable
226 @code{toplevel-score-handler} at toplevel. The default handler is
227 defined in the init file @file{scm/@/lily@/.scm}.
230 A @code{\book} block logically combines multiple movements
231 (i.e., multiple @code{\score} blocks) in one document. If there
232 are a number of @code{\score}s, one output file will be created
233 for each @code{\book} block, in which all corresponding movements
234 are concatenated. The only reason to explicitly specify
235 @code{\book} blocks in a @code{.ly} file is if you wish to create
236 multiple output files from a single input file. One exception is
237 within lilypond-book documents, where you explicitly have to add
238 a @code{\book} block if you want more than a single @code{\score}
239 or @code{\markup} in the same example. This behavior can be
240 changed by setting the variable @code{toplevel-book-handler} at
241 toplevel. The default handler is defined in the init file
242 @file{scm/@/lily@/.scm}.
245 A compound music expression, such as
250 This will add the piece in a @code{\score} and format it in a
251 single book together with all other toplevel @code{\score}s and music
252 expressions. In other words, a file containing only the above
253 music expression will be translated into
269 This behavior can be changed by setting the variable
270 @code{toplevel-music-handler} at toplevel. The default handler is
271 defined in the init file @file{scm/@/lily@/.scm}.
274 A markup text, a verse for example
277 2. The first line verse two.
281 Markup texts are rendered above, between or below the scores or music
282 expressions, wherever they appear.
292 This can be used later on in the file by entering @code{\foo}. The
293 name of an variable should have alphabetic characters only; no
294 numbers, underscores or dashes.
298 The following example shows three things that may be entered at
303 % Don't justify the output
315 At any point in a file, any of the following lexical instructions can
319 @item @code{\version}
320 @item @code{\include}
321 @item @code{\sourcefilename}
322 @item @code{\sourcefileline}
324 A single-line comment, introduced by a leading @code{%} sign.
327 A multi-line comment delimited by @code{%@{ .. %@}}.
334 @rlearning{How LilyPond input files work}.
336 @node Useful concepts and properties
337 @section Useful concepts and properties
342 * Controlling direction and placement::
343 * Distances and measurements::
348 @subsection Input modes
350 The way in which the notation contained within an input file is
351 interpreted is determined by the current input mode.
355 This is activated with the @code{\chordmode} command, and causes
356 input to be interpreted with the syntax of chord notation, see
357 @ref{Chord notation}. Chords are rendered as notes on a staff.
359 Chord mode is also activated with the @code{\chords} command.
360 This also creates a new @code{ChordNames} context and
361 causes the following input to be interpreted with the syntax of
362 chord notation and rendered as chord names in the @code{ChordNames}
363 context, see @ref{Printing chord names}.
367 This is activated with the @code{\drummode} command, and causes
368 input to be interpreted with the syntax of drum notation, see
369 @ref{Basic percussion notation}.
371 Drum mode is also activated with the @code{\drums} command.
372 This also creates a new @code{DrumStaff} context and causes the
373 following input to be interpreted with the syntax of drum notation
374 and rendered as drum symbols on a drum staff, see @ref{Basic
375 percussion notation}.
379 This is activated with the @code{\figuremode} command, and causes
380 input to be interpreted with the syntax of figured bass, see
381 @ref{Entering figured bass}.
383 Figure mode is also activated with the @code{\figures} command.
384 This also creates a new @code{FiguredBass} context and causes the
385 following input to be interpreted with the figured bass syntax
386 and rendered as figured bass symbols in the @code{FiguredBass}
387 context, see @ref{Introduction to figured bass}.
389 @strong{Fret and tab modes}
391 There are no special input modes for entering fret and tab symbols.
393 To create tab diagrams, enter notes or chords in note mode and
394 render them in a @code{TabStaff} context, see
395 @ref{Default tablatures}.
397 To create fret diagrams above a staff, enter them as markup
398 above the notes using the @code{\fret-diagram} command, see
403 This is activated with the @code{\lyricmode} command, and causes
404 input to be interpreted as lyric syllables with optional durations
405 and associated lyric modifiers, see @ref{Vocal music}.
407 Lyric mode is also activated with the @code{\addlyrics} command.
408 This also creates a new @code{Lyrics} context and an implicit
409 @code{\lyricsto} command which associates the following lyrics
410 with the preceding music.
414 This is activated with the @code{\markup} command, and causes
415 input to be interpreted with the syntax of markup, see
416 @ref{Text markup commands}.
418 @c silly work-around for texinfo broken-ness
419 @c (@strong{Note...} causes a spurious cross-reference in Info)
422 This is the default mode or it may be activated with the
423 @code{\notemode} command. Input is interpreted as pitches,
424 durations, markup, etc and typeset as musical notation on a staff.
426 It is not normally necessary to specify note mode explicitly, but
427 it may be useful to do so in certain situations, for example if you
428 are in lyric mode, chord mode or any other mode and want to insert
429 something that only can be done with note mode syntax.
431 For example, to indicate dynamic markings for the verses of a
432 choral pieces it is necessary to enter note mode to interpret
435 @lilypond[verbatim,relative=2,quote]
438 \notemode{\set stanza = \markup{ \dynamic f 1. } }
442 \notemode{\set stanza = \markup{ \dynamic p 2. } }
449 @node Controlling direction and placement
450 @subsection Controlling direction and placement
452 TODO: Maybe rename section to "directions".
454 In typesetting music the direction and placement of many items is
455 a matter of choice. For example, the stems of notes can
456 be directed up or down; lyrics, dynamics, and other expressive
457 marks may be placed above or below the staff; text may be aligned
458 left, right or center; etc. Most of these choices may be left to
459 be determined automatically by LilyPond, but in some cases it may
460 be desirable to force a particular direction or placement.
462 @strong{Default actions}
464 By default some directions are always up or always down (e.g.
465 dynamics or fermata), while other things can alternate between
466 up or down based on the stem direction (like slurs or accents).
468 @c TODO Add table showing these
470 @strong{Context layout}
472 Contexts are positioned in a system from top to bottom in the
473 order in which they are encountered. Note, however, that a
474 context will be created implicitly if a command is encountered
475 when there is no suitable context available to contain it.
477 @c TODO Add example ?
479 The default order in which contexts are laid out can be changed,
480 see @ref{Aligning contexts}
482 @strong{Articulation direction indicators}
484 When adding articulations to notes the direction indicator,
485 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
486 @code{-} (meaning @qq{use default direction}), can usually be
487 omitted, in which case @code{-} is assumed. But a direction
488 indicator is @strong{always} required before
491 @item @code{\tweak} commands
492 @item @code{\markup} commands
493 @item @code{\tag} commands
494 @item string markups, e.g. -"string"
495 @item fingering instructions, e.g. @code{-1}
496 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
499 @strong{The direction property}
501 The position or direction of many layout objects is controlled
502 by the @code{direction} property.
504 The value of the @code{direction} property may be
505 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
506 meaning @qq{down} or @qq{below}. The symbols @code{UP} and
507 @code{DOWN} may be used instead of @code{1} and @code{-1}
508 respectively. The default direction may be specified by setting
509 @code{direction} to @code{0} or @code{CENTER}. Alternatively,
510 in many cases predefined commands
511 exist to specify the direction. These are all of the form
514 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
517 where @code{xxxNeutral} means @qq{use the default direction}.
518 See @rlearning{Within-staff objects}.
520 In a few cases, arpeggio being the only common example, the value
521 of the @code{direction} property specifies whether the object
522 is to be placed to the right or left of the parent object. In
523 this case @code{-1} or @code{LEFT} means @qq{to the left} and
524 @code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
525 or @code{CENTER} means @qq{use the default} direction, as before.
528 These all have side-axis set to #X
529 AmbitusAccidental - direction has no effect
531 StanzaNumber - not tried
532 TrillPitchAccidental - not tried
533 TrillPitchGroup - not tried
538 @node Distances and measurements
539 @subsection Distances and measurements
541 DISCUSS after working on other sections.
543 TODO: staff spaces. Maybe move into tweaks?
550 @node Titles and headers
551 @section Titles and headers
553 Almost all printed music includes a title and the composer's name;
554 some pieces include a lot more information.
559 * Reference to page numbers::
560 * Table of contents::
564 @node Creating titles
565 @subsection Creating titles
567 Titles are created for each @code{\score} block, as well as for the full
568 input file (or @code{\book} block).
570 The contents of the titles are taken from the @code{\header} blocks.
571 The header block for a book supports the following
577 The dedicatee of the music, centered at the top of the first page.
581 The title of the music, centered just below the dedication.
585 Subtitle, centered below the title.
587 @funindex subsubtitle
589 Subsubtitle, centered below the subtitle.
593 Name of the poet, flush-left below the subtitle.
597 Name of the composer, flush-right below the subtitle.
601 Meter string, flush-left below the poet.
605 Name of the opus, flush-right below the composer.
609 Name of the arranger, flush-right below the opus.
613 Name of the instrument, centered below the arranger. Also
614 centered at the top of pages (other than the first page).
618 Name of the piece, flush-left below the instrument.
620 @cindex page breaks, forcing
621 @funindex breakbefore
623 This forces the title to start on a new page (set to ##t or ##f).
627 Copyright notice, centered at the bottom of the first page. To
628 insert the copyright symbol, see @ref{Text encoding}.
632 Centered at the bottom of the last page.
636 Here is a demonstration of the fields available. Note that you
637 may use any @ref{Formatting text}, commands in the header.
639 @lilypond[quote,verbatim,line-width=11.0\cm]
642 paper-height = 10.0\cm
647 dedication = "dedicated to me"
648 title = \markup \center-align { "Title first line" "Title second line,
650 subtitle = "the subtitle,"
651 subsubtitle = #(string-append "subsubtitle LilyPond version "
654 composer = \markup \center-align { "composer" \small "(1847-1973)" }
655 texttranslator = "Text Translator"
656 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
658 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
659 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
660 instrument = \markup \bold \italic "instrument"
684 As demonstrated before, you can use multiple @code{\header} blocks.
685 When same fields appear in different blocks, the latter is used.
686 Here is a short example.
690 composer = "Composer"
698 piece = "New piece" % overwrite previous one
703 If you define the @code{\header} inside the @code{\score} block, then
704 normally only the @code{piece} and @code{opus} headers will be printed.
705 Note that the music expression must come before the @code{\header}.
707 @lilypond[quote,verbatim,line-width=11.0\cm]
711 title = "title" % not printed
718 @funindex printallheaders
720 You may change this behavior (and print all the headers when defining
721 @code{\header} inside @code{\score}) by using
732 The default footer is empty, except for the first page, where the
733 @code{copyright} field from @code{\header} is inserted, and the last
734 page, where @code{tagline} from @code{\header} is added. The default
735 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
736 printed parts are good PR for us, so please leave the tagline if you
739 Headers may be completely removed by setting them to false.
750 @subsection Custom titles
752 A more advanced option is to change the definitions of the following
753 variables in the @code{\paper} block. The init file
754 @file{ly/titling-init.ly} lists the default layout.
757 @funindex bookTitleMarkup
758 @item bookTitleMarkup
759 This is the title added at the top of the entire output document.
760 Typically, it has the composer and the title of the piece
762 @funindex scoreTitleMarkup
763 @item scoreTitleMarkup
764 This is the title put over a @code{\score} block. Typically, it has
765 the name of the movement (@code{piece} field).
767 @funindex oddHeaderMarkup
768 @item oddHeaderMarkup
769 This is the page header for odd-numbered pages.
771 @funindex evenHeaderMarkup
772 @item evenHeaderMarkup
773 This is the page header for even-numbered pages. If unspecified,
774 the odd header is used instead.
776 By default, headers are defined such that the page number is on the
777 outside edge, and the instrument is centered.
779 @funindex oddFooterMarkup
780 @item oddFooterMarkup
781 This is the page footer for odd-numbered pages.
783 @funindex evenFooterMarkup
784 @item evenFooterMarkup
785 This is the page footer for even-numbered pages. If unspecified,
786 the odd header is used instead.
788 By default, the footer has the copyright notice on the first, and
789 the tagline on the last page.
799 The following definition will put the title flush left, and the
800 composer flush right on a single line.
804 bookTitleMarkup = \markup {
806 \fromproperty #'header:title
807 \fromproperty #'header:composer
813 @node Reference to page numbers
814 @subsection Reference to page numbers
816 A particular place of a score can be marked using the @code{\label}
817 command, either at top-level or inside music. This label can then be
818 referred to in a markup, to get the number of the page where the marked
819 point is placed, using the @code{\page-ref} markup command.
821 @lilypond[verbatim,line-width=11.0\cm]
822 \header { tagline = ##f }
828 \pageBreak \mark A \label #'markA
833 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
834 \markup { Mark A is on page \page-ref #'markA "0" "?" }
838 The @code{\page-ref} markup command takes three arguments:
840 @item the label, a scheme symbol, eg. @code{#'firstScore};
841 @item a markup that will be used as a gauge to estimate the dimensions
843 @item a markup that will be used in place of the page number if the label
847 The reason why a gauge is needed is that, at the time markups are
848 interpreted, the page breaking has not yet occurred, so the page numbers
849 are not yet known. To work around this issue, the actual markup
850 interpretation is delayed to a later time; however, the dimensions of
851 the markup have to be known before, so a gauge is used to decide these
852 dimensions. If the book has between 10 and 99 pages, it may be "00",
853 ie. a two digit number.
862 @node Table of contents
863 @subsection Table of contents
864 A table of contents is included using the @code{\markuplines \table-of-contents}
865 command. The elements which should appear in the table of contents are
866 entered with the @code{\tocItem} command, which may be used either at
867 top-level, or inside a music expression.
870 \markuplines \table-of-contents
873 \tocItem \markup "First score"
877 \tocItem \markup "Some particular point in the first score"
882 \tocItem \markup "Second score"
890 The markups which are used to format the table of contents are defined
891 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
892 for formatting the title of the table, and @code{tocItemMarkup}, for
893 formatting the toc elements, composed of the element title and page
894 number. These variables may be changed by the user:
898 %% Translate the toc title into French:
899 tocTitleMarkup = \markup \huge \column {
900 \fill-line { \null "Table des matières" \null }
903 %% use larger font size
904 tocItemMarkup = \markup \large \fill-line {
905 \fromproperty #'toc:text \fromproperty #'toc:page
910 Note how the toc element text and page number are referred to in
911 the @code{tocItemMarkup} definition.
913 New commands and markups may also be defined to build more elaborated
916 @item first, define a new markup variable in the @code{\paper} block
917 @item then, define a music function which aims at adding a toc element
918 using this markup paper variable.
921 In the following example, a new style is defined for entering act names
922 in the table of contents of an opera:
926 tocActMarkup = \markup \large \column {
928 \fill-line { \null \italic \fromproperty #'toc:text \null }
934 #(define-music-function (parser location text) (markup?)
935 (add-toc-item! 'tocActMarkup text))
938 @lilypond[line-width=11.0\cm]
939 \header { tagline = ##f }
941 tocActMarkup = \markup \large \column {
943 \fill-line { \null \italic \fromproperty #'toc:text \null }
949 #(define-music-function (parser location text) (markup?)
950 (add-toc-item! 'tocActMarkup text))
953 \markuplines \table-of-contents
954 \tocAct \markup { Atto Primo }
955 \tocItem \markup { Coro. Viva il nostro Alcide }
956 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
957 \tocAct \markup { Atto Secondo }
958 \tocItem \markup { Sinfonia }
959 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
966 Init files: @file{ly/@/toc@/-init@/.ly}.
970 @funindex \table-of-contents
971 @code{\table-of-contents}
976 @node Working with input files
977 @section Working with input files
980 * Including LilyPond files::
981 * Different editions from one source::
983 * Displaying LilyPond notation::
987 @node Including LilyPond files
988 @subsection Including LilyPond files
991 @cindex including files
993 A large project may be split up into separate files. To refer to another
997 \include "otherfile.ly"
1000 The line @code{\include "file.ly"} is equivalent to pasting the contents
1001 of file.ly into the current file at the place where you have the
1002 \include. For example, for a large project you might write separate files
1003 for each instrument part and create a @q{full score} file which brings
1004 together the individual instrument files.
1006 The initialization of LilyPond is done in a number of files that are
1007 included by default when you start the program, normally transparent to the
1008 user. Run @code{lilypond --verbose} to see a list of paths and files that Lily
1011 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
1012 VERSION is in the form @q{2.6.1}) are on the path and available to
1013 @code{\include}. Files in the
1014 current working directory are available to \include, but a file of the same
1015 name in LilyPond's installation takes precedence. Files are
1016 available to \include from directories in the search path specified as an
1017 option when invoking @code{lilypond --include=DIR} which adds DIR to the
1020 The @code{\include} statement can use full path information, but with the UNIX
1021 convention @code{/} rather than the DOS/Windows @code{\}. For example,
1022 if @file{stuff.ly} is located one directory higher than the current working
1026 \include "../stuff.ly"
1030 @node Different editions from one source
1031 @subsection Different editions from one source
1036 The @code{\tag} command marks music expressions with a name. These
1037 tagged expressions can be filtered out later. With this mechanism it
1038 is possible to make different versions of the same music source.
1040 In the following example, we see two versions of a piece of music, one
1041 for the full score, and one with cue notes for the instrumental part
1057 The same can be applied to articulations, texts, etc.: they are
1060 -\tag #@var{your-tag}
1062 to an articulation, for example,
1067 This defines a note with a conditional fingering indication.
1070 @cindex removeWithTag
1071 By applying the @code{\keepWithTag} and @code{\removeWithTag}
1072 commands, tagged expressions can be filtered. For example,
1076 \keepWithTag #'score @var{the music}
1077 \keepWithTag #'part @var{the music}
1083 @c @lilypondfile[ragged-right,quote]{tag-filter.ly}
1085 The arguments of the @code{\tag} command should be a symbol
1086 (such as @code{#'score} or @code{#'part}), followed by a
1087 music expression. It is possible to put multiple tags on
1088 a piece of music with multiple @code{\tag} entries,
1091 \tag #'original-part \tag #'transposed-part @dots{}
1097 Multiple rests are not merged if you create the score with both tagged
1102 @subsection Text encoding
1104 LilyPond uses the Pango library to format multi-lingual texts, and
1105 does not perform any input-encoding conversions. This means that any
1106 text, be it title, lyric text, or musical instruction containing
1107 non-ASCII characters, must be utf-8. The easiest way to enter such text is
1108 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
1109 popular modern editors have utf-8 support, for example, vim, Emacs,
1110 jEdit, and GEdit do.
1112 @c Currently not working
1114 Depending on the fonts installed, the following fragment shows Hebrew
1115 and Cyrillic lyrics,
1121 @li lypondfile[fontload]{utf-8.ly}
1123 The @TeX{} backend does not handle encoding specially at all. Strings
1124 in the input are put in the output as-is. Extents of text items in the
1125 @TeX{} backend, are determined by reading a file created via the
1126 @file{texstr} backend,
1129 lilypond -dbackend=texstr input/les-nereides.ly
1130 latex les-nereides.texstr
1133 The last command produces @file{les-nereides.textmetrics}, which is
1134 read when you execute
1137 lilypond -dbackend=tex input/les-nereides.ly
1140 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
1141 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
1142 interpreting non-ASCII strings.
1146 To use a Unicode escape sequence, use
1149 #(ly:export (ly:wide-char->utf-8 #x2014))
1153 @node Displaying LilyPond notation
1154 @subsection Displaying LilyPond notation
1156 @funindex \displayLilyMusic
1157 Displaying a music expression in LilyPond notation can be
1158 done using the music function @code{\displayLilyMusic}. For example,
1162 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1169 @{ a, cis e fis g @}
1172 By default, LilyPond will print these messages to the console along
1173 with all the other messages. To split up these messages and save
1174 the results of @code{\display@{STUFF@}}, redirect the output to
1178 lilypond file.ly >display.txt
1183 @node Controlling output
1184 @section Controlling output
1187 * Extracting fragments of notation::
1188 * Skipping corrected music::
1191 @node Extracting fragments of notation
1192 @subsection Extracting fragments of notation
1194 It is possible to quote small fragments of a large score directly from
1195 the output. This can be compared to clipping a piece of a paper score
1198 This is done by defining the measures that need to be cut out
1199 separately. For example, including the following definition
1207 (make-rhythmic-location 5 1 2)
1208 (make-rhythmic-location 7 3 4)))
1213 will extract a fragment starting halfway the fifth measure, ending in
1214 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1215 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1217 More clip regions can be defined by adding more pairs of
1218 rhythmic-locations to the list.
1220 In order to use this feature, LilyPond must be invoked with
1221 @code{-dclip-systems}. The clips are output as EPS files, and are
1222 converted to PDF and PNG if these formats are switched on as well.
1224 For more information on output formats, see @rprogram{Invoking lilypond}.
1226 @node Skipping corrected music
1227 @subsection Skipping corrected music
1230 @funindex skipTypesetting
1231 @funindex showLastLength
1233 When entering or copying music, usually only the music near the end (where
1235 are adding notes) is interesting to view and correct. To speed up
1236 this correction process, it is possible to skip typesetting of all but
1237 the last few measures. This is achieved by putting
1240 showLastLength = R1*5
1245 in your source file. This will render only the last 5 measures
1246 (assuming 4/4 time signature) of every @code{\score} in the input
1247 file. For longer pieces, rendering only a small part is often an order
1248 of magnitude quicker than rendering it completely
1250 Skipping parts of a score can be controlled in a more fine-grained
1251 fashion with the property @code{Score.skipTypesetting}. When it is
1252 set, no typesetting is performed at all.
1254 This property is also used to control output to the MIDI file. Note that
1255 it skips all events, including tempo and instrument changes. You have
1258 @lilypond[quote,fragment,ragged-right,verbatim]
1261 \set Score.skipTypesetting = ##t
1263 \set Score.skipTypesetting = ##f
1267 In polyphonic music, @code{Score.skipTypesetting} will affect all
1268 voices and staves, saving even more time.