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}.
420 This is the default mode or it may be activated with the
421 @code{\notemode} command. Input is interpreted as pitches,
422 durations, markup, etc and typeset as musical notation on a staff.
424 It is not normally necessary to specify note mode explicitly, but
425 it may be useful to do so in certain situations, for example if you
426 are in lyric mode, chord mode or any other mode and want to insert
427 something that only can be done with note mode syntax.
429 For example, to indicate dynamic markings for the verses of a
430 choral pieces it is necessary to enter note mode to interpret
433 @lilypond[verbatim,relative=2,quote]
436 \notemode{\set stanza = \markup{ \dynamic f 1. } }
440 \notemode{\set stanza = \markup{ \dynamic p 2. } }
447 @node Controlling direction and placement
448 @subsection Controlling direction and placement
450 TODO: Maybe rename section to "directions".
452 In typesetting music the direction and placement of many items is
453 a matter of choice. For example, the stems of notes can
454 be directed up or down; lyrics, dynamics, and other expressive
455 marks may be placed above or below the staff; text may be aligned
456 left, right or center; etc. Most of these choices may be left to
457 be determined automatically by LilyPond, but in some cases it may
458 be desirable to force a particular direction or placement.
460 @strong{Default actions}
462 By default some directions are always up or always down (e.g.
463 dynamics or fermata), while other things can alternate between
464 up or down based on the stem direction (like slurs or accents).
466 @c TODO Add table showing these
468 @strong{Context layout}
470 Contexts are positioned in a system from top to bottom in the
471 order in which they are encountered. Note, however, that a
472 context will be created implicitly if a command is encountered
473 when there is no suitable context available to contain it.
475 @c TODO Add example ?
477 The default order in which contexts are laid out can be changed,
478 see @ref{Aligning contexts}
480 @strong{Articulation direction indicators}
482 When adding articulations to notes the direction indicator,
483 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
484 @code{-} (meaning @qq{use default direction}), can usually be
485 omitted, in which case @code{-} is assumed. But a direction
486 indicator is @strong{always} required before
489 @item @code{\tweak} commands
490 @item @code{\markup} commands
491 @item @code{\tag} commands
492 @item string markups, e.g. -"string"
493 @item fingering instructions, e.g. @code{-1}
494 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
497 @strong{The direction property}
499 The position or direction of many layout objects is controlled
500 by the @code{direction} property.
502 The value of the @code{direction} property may be
503 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
504 meaning @qq{down} or @qq{below}. The symbols @code{UP} and
505 @code{DOWN} may be used instead of @code{1} and @code{-1}
506 respectively. The default direction may be specified by setting
507 @code{direction} to @code{0} or @code{CENTER}. Alternatively,
508 in many cases predefined commands
509 exist to specify the direction. These are all of the form
512 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
515 where @code{xxxNeutral} means @qq{use the default direction}.
516 See @rlearning{Within-staff objects}.
518 In a few cases, arpeggio being the only common example, the value
519 of the @code{direction} property specifies whether the object
520 is to be placed to the right or left of the parent object. In
521 this case @code{-1} or @code{LEFT} means @qq{to the left} and
522 @code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
523 or @code{CENTER} means @qq{use the default} direction, as before.
526 These all have side-axis set to #X
527 AmbitusAccidental - direction has no effect
529 StanzaNumber - not tried
530 TrillPitchAccidental - not tried
531 TrillPitchGroup - not tried
536 @node Distances and measurements
537 @subsection Distances and measurements
539 DISCUSS after working on other sections.
541 TODO: staff spaces. Maybe move into tweaks?
548 @node Titles and headers
549 @section Titles and headers
551 Almost all printed music includes a title and the composer's name;
552 some pieces include a lot more information.
557 * Reference to page numbers::
558 * Table of contents::
562 @node Creating titles
563 @subsection Creating titles
565 Titles are created for each @code{\score} block, as well as for the full
566 input file (or @code{\book} block).
568 The contents of the titles are taken from the @code{\header} blocks.
569 The header block for a book supports the following
575 The dedicatee of the music, centered at the top of the first page.
579 The title of the music, centered just below the dedication.
583 Subtitle, centered below the title.
585 @funindex subsubtitle
587 Subsubtitle, centered below the subtitle.
591 Name of the poet, flush-left below the subtitle.
595 Name of the composer, flush-right below the subtitle.
599 Meter string, flush-left below the poet.
603 Name of the opus, flush-right below the composer.
607 Name of the arranger, flush-right below the opus.
611 Name of the instrument, centered below the arranger. Also
612 centered at the top of pages (other than the first page).
616 Name of the piece, flush-left below the instrument.
618 @cindex page breaks, forcing
619 @funindex breakbefore
621 This forces the title to start on a new page (set to ##t or ##f).
625 Copyright notice, centered at the bottom of the first page. To
626 insert the copyright symbol, see @ref{Text encoding}.
630 Centered at the bottom of the last page.
634 Here is a demonstration of the fields available. Note that you
635 may use any @ref{Formatting text}, commands in the header.
637 @lilypond[quote,verbatim,line-width=11.0\cm]
640 paper-height = 10.0\cm
645 dedication = "dedicated to me"
646 title = \markup \center-align { "Title first line" "Title second line,
648 subtitle = "the subtitle,"
649 subsubtitle = #(string-append "subsubtitle LilyPond version "
652 composer = \markup \center-align { "composer" \small "(1847-1973)" }
653 texttranslator = "Text Translator"
654 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
656 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
657 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
658 instrument = \markup \bold \italic "instrument"
682 As demonstrated before, you can use multiple @code{\header} blocks.
683 When same fields appear in different blocks, the latter is used.
684 Here is a short example.
688 composer = "Composer"
696 piece = "New piece" % overwrite previous one
701 If you define the @code{\header} inside the @code{\score} block, then
702 normally only the @code{piece} and @code{opus} headers will be printed.
703 Note that the music expression must come before the @code{\header}.
705 @lilypond[quote,verbatim,line-width=11.0\cm]
709 title = "title" % not printed
716 @funindex printallheaders
718 You may change this behavior (and print all the headers when defining
719 @code{\header} inside @code{\score}) by using
730 The default footer is empty, except for the first page, where the
731 @code{copyright} field from @code{\header} is inserted, and the last
732 page, where @code{tagline} from @code{\header} is added. The default
733 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
734 printed parts are good PR for us, so please leave the tagline if you
737 Headers may be completely removed by setting them to false.
748 @subsection Custom titles
750 A more advanced option is to change the definitions of the following
751 variables in the @code{\paper} block. The init file
752 @file{ly/titling-init.ly} lists the default layout.
755 @funindex bookTitleMarkup
756 @item bookTitleMarkup
757 This is the title added at the top of the entire output document.
758 Typically, it has the composer and the title of the piece
760 @funindex scoreTitleMarkup
761 @item scoreTitleMarkup
762 This is the title put over a @code{\score} block. Typically, it has
763 the name of the movement (@code{piece} field).
765 @funindex oddHeaderMarkup
766 @item oddHeaderMarkup
767 This is the page header for odd-numbered pages.
769 @funindex evenHeaderMarkup
770 @item evenHeaderMarkup
771 This is the page header for even-numbered pages. If unspecified,
772 the odd header is used instead.
774 By default, headers are defined such that the page number is on the
775 outside edge, and the instrument is centered.
777 @funindex oddFooterMarkup
778 @item oddFooterMarkup
779 This is the page footer for odd-numbered pages.
781 @funindex evenFooterMarkup
782 @item evenFooterMarkup
783 This is the page footer for even-numbered pages. If unspecified,
784 the odd header is used instead.
786 By default, the footer has the copyright notice on the first, and
787 the tagline on the last page.
797 The following definition will put the title flush left, and the
798 composer flush right on a single line.
802 bookTitleMarkup = \markup {
804 \fromproperty #'header:title
805 \fromproperty #'header:composer
811 @node Reference to page numbers
812 @subsection Reference to page numbers
814 A particular place of a score can be marked using the @code{\label}
815 command, either at top-level or inside music. This label can then be
816 referred to in a markup, to get the number of the page where the marked
817 point is placed, using the @code{\page-ref} markup command.
819 @lilypond[verbatim,line-width=11.0\cm]
820 \header { tagline = ##f }
826 \pageBreak \mark A \label #'markA
831 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
832 \markup { Mark A is on page \page-ref #'markA "0" "?" }
836 The @code{\page-ref} markup command takes three arguments:
838 @item the label, a scheme symbol, eg. @code{#'firstScore};
839 @item a markup that will be used as a gauge to estimate the dimensions
841 @item a markup that will be used in place of the page number if the label
845 The reason why a gauge is needed is that, at the time markups are
846 interpreted, the page breaking has not yet occurred, so the page numbers
847 are not yet known. To work around this issue, the actual markup
848 interpretation is delayed to a later time; however, the dimensions of
849 the markup have to be known before, so a gauge is used to decide these
850 dimensions. If the book has between 10 and 99 pages, it may be "00",
851 ie. a two digit number.
860 @node Table of contents
861 @subsection Table of contents
862 A table of contents is included using the @code{\markuplines \table-of-contents}
863 command. The elements which should appear in the table of contents are
864 entered with the @code{\tocItem} command, which may be used either at
865 top-level, or inside a music expression.
868 \markuplines \table-of-contents
871 \tocItem \markup "First score"
875 \tocItem \markup "Some particular point in the first score"
880 \tocItem \markup "Second score"
888 The markups which are used to format the table of contents are defined
889 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
890 for formatting the title of the table, and @code{tocItemMarkup}, for
891 formatting the toc elements, composed of the element title and page
892 number. These variables may be changed by the user:
896 %% Translate the toc title into French:
897 tocTitleMarkup = \markup \huge \column {
898 \fill-line { \null "Table des matières" \null }
901 %% use larger font size
902 tocItemMarkup = \markup \large \fill-line {
903 \fromproperty #'toc:text \fromproperty #'toc:page
908 Note how the toc element text and page number are referred to in
909 the @code{tocItemMarkup} definition.
911 New commands and markups may also be defined to build more elaborated
914 @item first, define a new markup variable in the @code{\paper} block
915 @item then, define a music function which aims at adding a toc element
916 using this markup paper variable.
919 In the following example, a new style is defined for entering act names
920 in the table of contents of an opera:
924 tocActMarkup = \markup \large \column {
926 \fill-line { \null \italic \fromproperty #'toc:text \null }
932 #(define-music-function (parser location text) (markup?)
933 (add-toc-item! 'tocActMarkup text))
936 @lilypond[line-width=11.0\cm]
937 \header { tagline = ##f }
939 tocActMarkup = \markup \large \column {
941 \fill-line { \null \italic \fromproperty #'toc:text \null }
947 #(define-music-function (parser location text) (markup?)
948 (add-toc-item! 'tocActMarkup text))
951 \markuplines \table-of-contents
952 \tocAct \markup { Atto Primo }
953 \tocItem \markup { Coro. Viva il nostro Alcide }
954 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
955 \tocAct \markup { Atto Secondo }
956 \tocItem \markup { Sinfonia }
957 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
964 Init files: @file{ly/@/toc@/-init@/.ly}.
968 @funindex \table-of-contents
969 @code{\table-of-contents}
974 @node Working with input files
975 @section Working with input files
978 * Including LilyPond files::
979 * Different editions from one source::
981 * Displaying LilyPond notation::
985 @node Including LilyPond files
986 @subsection Including LilyPond files
989 @cindex including files
991 A large project may be split up into separate files. To refer to another
995 \include "otherfile.ly"
998 The line @code{\include "file.ly"} is equivalent to pasting the contents
999 of file.ly into the current file at the place where you have the
1000 \include. For example, for a large project you might write separate files
1001 for each instrument part and create a @q{full score} file which brings
1002 together the individual instrument files.
1004 The initialization of LilyPond is done in a number of files that are
1005 included by default when you start the program, normally transparent to the
1006 user. Run @code{lilypond --verbose} to see a list of paths and files that Lily
1009 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
1010 VERSION is in the form @q{2.6.1}) are on the path and available to
1011 @code{\include}. Files in the
1012 current working directory are available to \include, but a file of the same
1013 name in LilyPond's installation takes precedence. Files are
1014 available to \include from directories in the search path specified as an
1015 option when invoking @code{lilypond --include=DIR} which adds DIR to the
1018 The @code{\include} statement can use full path information, but with the UNIX
1019 convention @code{/} rather than the DOS/Windows @code{\}. For example,
1020 if @file{stuff.ly} is located one directory higher than the current working
1024 \include "../stuff.ly"
1028 @node Different editions from one source
1029 @subsection Different editions from one source
1034 The @code{\tag} command marks music expressions with a name. These
1035 tagged expressions can be filtered out later. With this mechanism it
1036 is possible to make different versions of the same music source.
1038 In the following example, we see two versions of a piece of music, one
1039 for the full score, and one with cue notes for the instrumental part
1055 The same can be applied to articulations, texts, etc.: they are
1058 -\tag #@var{your-tag}
1060 to an articulation, for example,
1065 This defines a note with a conditional fingering indication.
1068 @cindex removeWithTag
1069 By applying the @code{\keepWithTag} and @code{\removeWithTag}
1070 commands, tagged expressions can be filtered. For example,
1074 \keepWithTag #'score @var{the music}
1075 \keepWithTag #'part @var{the music}
1081 @c @lilypondfile[ragged-right,quote]{tag-filter.ly}
1083 The arguments of the @code{\tag} command should be a symbol
1084 (such as @code{#'score} or @code{#'part}), followed by a
1085 music expression. It is possible to put multiple tags on
1086 a piece of music with multiple @code{\tag} entries,
1089 \tag #'original-part \tag #'transposed-part @dots{}
1095 Multiple rests are not merged if you create the score with both tagged
1100 @subsection Text encoding
1102 LilyPond uses the Pango library to format multi-lingual texts, and
1103 does not perform any input-encoding conversions. This means that any
1104 text, be it title, lyric text, or musical instruction containing
1105 non-ASCII characters, must be utf-8. The easiest way to enter such text is
1106 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
1107 popular modern editors have utf-8 support, for example, vim, Emacs,
1108 jEdit, and GEdit do.
1110 @c Currently not working
1112 Depending on the fonts installed, the following fragment shows Hebrew
1113 and Cyrillic lyrics,
1119 @li lypondfile[fontload]{utf-8.ly}
1121 The @TeX{} backend does not handle encoding specially at all. Strings
1122 in the input are put in the output as-is. Extents of text items in the
1123 @TeX{} backend, are determined by reading a file created via the
1124 @file{texstr} backend,
1127 lilypond -dbackend=texstr input/les-nereides.ly
1128 latex les-nereides.texstr
1131 The last command produces @file{les-nereides.textmetrics}, which is
1132 read when you execute
1135 lilypond -dbackend=tex input/les-nereides.ly
1138 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
1139 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
1140 interpreting non-ASCII strings.
1144 To use a Unicode escape sequence, use
1147 #(ly:export (ly:wide-char->utf-8 #x2014))
1151 @node Displaying LilyPond notation
1152 @subsection Displaying LilyPond notation
1154 @funindex \displayLilyMusic
1155 Displaying a music expression in LilyPond notation can be
1156 done using the music function @code{\displayLilyMusic}. For example,
1160 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1167 @{ a, cis e fis g @}
1170 By default, LilyPond will print these messages to the console along
1171 with all the other messages. To split up these messages and save
1172 the results of @code{\display@{STUFF@}}, redirect the output to
1176 lilypond file.ly >display.txt
1181 @node Controlling output
1182 @section Controlling output
1185 * Extracting fragments of notation::
1186 * Skipping corrected music::
1189 @node Extracting fragments of notation
1190 @subsection Extracting fragments of notation
1192 It is possible to quote small fragments of a large score directly from
1193 the output. This can be compared to clipping a piece of a paper score
1196 This is done by defining the measures that need to be cut out
1197 separately. For example, including the following definition
1205 (make-rhythmic-location 5 1 2)
1206 (make-rhythmic-location 7 3 4)))
1211 will extract a fragment starting halfway the fifth measure, ending in
1212 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1213 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1215 More clip regions can be defined by adding more pairs of
1216 rhythmic-locations to the list.
1218 In order to use this feature, LilyPond must be invoked with
1219 @code{-dclip-systems}. The clips are output as EPS files, and are
1220 converted to PDF and PNG if these formats are switched on as well.
1222 For more information on output formats, see @rprogram{Invoking lilypond}.
1224 @node Skipping corrected music
1225 @subsection Skipping corrected music
1228 @funindex skipTypesetting
1229 @funindex showLastLength
1231 When entering or copying music, usually only the music near the end (where
1233 are adding notes) is interesting to view and correct. To speed up
1234 this correction process, it is possible to skip typesetting of all but
1235 the last few measures. This is achieved by putting
1238 showLastLength = R1*5
1243 in your source file. This will render only the last 5 measures
1244 (assuming 4/4 time signature) of every @code{\score} in the input
1245 file. For longer pieces, rendering only a small part is often an order
1246 of magnitude quicker than rendering it completely
1248 Skipping parts of a score can be controlled in a more fine-grained
1249 fashion with the property @code{Score.skipTypesetting}. When it is
1250 set, no typesetting is performed at all.
1252 This property is also used to control output to the MIDI file. Note that
1253 it skips all events, including tempo and instrument changes. You have
1256 @lilypond[quote,fragment,ragged-right,verbatim]
1259 \set Score.skipTypesetting = ##t
1261 \set Score.skipTypesetting = ##f
1265 In polyphonic music, @code{Score.skipTypesetting} will affect all
1266 voices and staves, saving even more time.