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) musical 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 * 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 Direction and placement
450 @subsection Direction and placement
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?
547 Many objects of musical notation extend over several notes or even
548 several bars. Examples are crescendi, trills, tuplet brackets, and
549 volta repeat brackets. Such objects are called @qq{spanners}, and
550 have special properties to control their appearance and behaviour.
551 Some of these properties are common to all spanners; others are
552 restricted to a sub-set of the spanners.
554 @node Titles and headers
555 @section Titles and headers
557 Almost all printed music includes a title and the composer's name;
558 some pieces include a lot more information.
563 * Reference to page numbers::
564 * Table of contents::
568 @node Creating titles
569 @subsection Creating titles
571 Titles are created for each @code{\score} block, as well as for the full
572 input file (or @code{\book} block).
574 The contents of the titles are taken from the @code{\header} blocks.
575 The header block for a book supports the following
581 The dedicatee of the music, centered at the top of the first page.
585 The title of the music, centered just below the dedication.
589 Subtitle, centered below the title.
591 @funindex subsubtitle
593 Subsubtitle, centered below the subtitle.
597 Name of the poet, flush-left below the subtitle.
601 Name of the composer, flush-right below the subtitle.
605 Meter string, flush-left below the poet.
609 Name of the opus, flush-right below the composer.
613 Name of the arranger, flush-right below the opus.
617 Name of the instrument, centered below the arranger. Also
618 centered at the top of pages (other than the first page).
622 Name of the piece, flush-left below the instrument.
624 @cindex page breaks, forcing
625 @funindex breakbefore
627 This forces the title to start on a new page (set to ##t or ##f).
631 Copyright notice, centered at the bottom of the first page. To
632 insert the copyright symbol, see @ref{Text encoding}.
636 Centered at the bottom of the last page.
640 Here is a demonstration of the fields available. Note that you
641 may use any @ref{Formatting text}, commands in the header.
643 @lilypond[quote,verbatim,line-width=11.0\cm]
646 paper-height = 10.0\cm
651 dedication = "dedicated to me"
652 title = \markup \center-align { "Title first line" "Title second line,
654 subtitle = "the subtitle,"
655 subsubtitle = #(string-append "subsubtitle LilyPond version "
658 composer = \markup \center-align { "composer" \small "(1847-1973)" }
659 texttranslator = "Text Translator"
660 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
662 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
663 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
664 instrument = \markup \bold \italic "instrument"
688 As demonstrated before, you can use multiple @code{\header} blocks.
689 When same fields appear in different blocks, the latter is used.
690 Here is a short example.
694 composer = "Composer"
702 piece = "New piece" % overwrite previous one
707 If you define the @code{\header} inside the @code{\score} block, then
708 normally only the @code{piece} and @code{opus} headers will be printed.
709 Note that the music expression must come before the @code{\header}.
711 @lilypond[quote,verbatim,line-width=11.0\cm]
715 title = "title" % not printed
722 @funindex printallheaders
724 You may change this behavior (and print all the headers when defining
725 @code{\header} inside @code{\score}) by using
736 The default footer is empty, except for the first page, where the
737 @code{copyright} field from @code{\header} is inserted, and the last
738 page, where @code{tagline} from @code{\header} is added. The default
739 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
740 printed parts are good PR for us, so please leave the tagline if you
743 Headers may be completely removed by setting them to false.
754 @subsection Custom titles
756 A more advanced option is to change the definitions of the following
757 variables in the @code{\paper} block. The init file
758 @file{ly/titling-init.ly} lists the default layout.
761 @funindex bookTitleMarkup
762 @item bookTitleMarkup
763 This is the title added at the top of the entire output document.
764 Typically, it has the composer and the title of the piece
766 @funindex scoreTitleMarkup
767 @item scoreTitleMarkup
768 This is the title put over a @code{\score} block. Typically, it has
769 the name of the movement (@code{piece} field).
771 @funindex oddHeaderMarkup
772 @item oddHeaderMarkup
773 This is the page header for odd-numbered pages.
775 @funindex evenHeaderMarkup
776 @item evenHeaderMarkup
777 This is the page header for even-numbered pages. If unspecified,
778 the odd header is used instead.
780 By default, headers are defined such that the page number is on the
781 outside edge, and the instrument is centered.
783 @funindex oddFooterMarkup
784 @item oddFooterMarkup
785 This is the page footer for odd-numbered pages.
787 @funindex evenFooterMarkup
788 @item evenFooterMarkup
789 This is the page footer for even-numbered pages. If unspecified,
790 the odd header is used instead.
792 By default, the footer has the copyright notice on the first, and
793 the tagline on the last page.
803 The following definition will put the title flush left, and the
804 composer flush right on a single line.
808 bookTitleMarkup = \markup {
810 \fromproperty #'header:title
811 \fromproperty #'header:composer
817 @node Reference to page numbers
818 @subsection Reference to page numbers
820 A particular place of a score can be marked using the @code{\label}
821 command, either at top-level or inside music. This label can then be
822 referred to in a markup, to get the number of the page where the marked
823 point is placed, using the @code{\page-ref} markup command.
825 @lilypond[verbatim,line-width=11.0\cm]
826 \header { tagline = ##f }
832 \pageBreak \mark A \label #'markA
837 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
838 \markup { Mark A is on page \page-ref #'markA "0" "?" }
842 The @code{\page-ref} markup command takes three arguments:
844 @item the label, a scheme symbol, eg. @code{#'firstScore};
845 @item a markup that will be used as a gauge to estimate the dimensions
847 @item a markup that will be used in place of the page number if the label
851 The reason why a gauge is needed is that, at the time markups are
852 interpreted, the page breaking has not yet occurred, so the page numbers
853 are not yet known. To work around this issue, the actual markup
854 interpretation is delayed to a later time; however, the dimensions of
855 the markup have to be known before, so a gauge is used to decide these
856 dimensions. If the book has between 10 and 99 pages, it may be "00",
857 ie. a two digit number.
866 @node Table of contents
867 @subsection Table of contents
868 A table of contents is included using the @code{\markuplines \table-of-contents}
869 command. The elements which should appear in the table of contents are
870 entered with the @code{\tocItem} command, which may be used either at
871 top-level, or inside a music expression.
874 \markuplines \table-of-contents
877 \tocItem \markup "First score"
881 \tocItem \markup "Some particular point in the first score"
886 \tocItem \markup "Second score"
894 The markups which are used to format the table of contents are defined
895 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
896 for formatting the title of the table, and @code{tocItemMarkup}, for
897 formatting the toc elements, composed of the element title and page
898 number. These variables may be changed by the user:
902 %% Translate the toc title into French:
903 tocTitleMarkup = \markup \huge \column {
904 \fill-line { \null "Table des matières" \null }
907 %% use larger font size
908 tocItemMarkup = \markup \large \fill-line {
909 \fromproperty #'toc:text \fromproperty #'toc:page
914 Note how the toc element text and page number are referred to in
915 the @code{tocItemMarkup} definition.
917 New commands and markups may also be defined to build more elaborated
920 @item first, define a new markup variable in the @code{\paper} block
921 @item then, define a music function which aims at adding a toc element
922 using this markup paper variable.
925 In the following example, a new style is defined for entering act names
926 in the table of contents of an opera:
930 tocActMarkup = \markup \large \column {
932 \fill-line { \null \italic \fromproperty #'toc:text \null }
938 #(define-music-function (parser location text) (markup?)
939 (add-toc-item! 'tocActMarkup text))
942 @lilypond[line-width=11.0\cm]
943 \header { tagline = ##f }
945 tocActMarkup = \markup \large \column {
947 \fill-line { \null \italic \fromproperty #'toc:text \null }
953 #(define-music-function (parser location text) (markup?)
954 (add-toc-item! 'tocActMarkup text))
957 \markuplines \table-of-contents
958 \tocAct \markup { Atto Primo }
959 \tocItem \markup { Coro. Viva il nostro Alcide }
960 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
961 \tocAct \markup { Atto Secondo }
962 \tocItem \markup { Sinfonia }
963 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
970 Init files: @file{ly/@/toc@/-init@/.ly}.
974 @funindex \table-of-contents
975 @code{\table-of-contents}
980 @node Working with input files
981 @section Working with input files
984 * Including LilyPond files::
985 * Different editions from one source::
987 * Displaying LilyPond notation::
991 @node Including LilyPond files
992 @subsection Including LilyPond files
995 @cindex including files
997 A large project may be split up into separate files. To refer to another
1001 \include "otherfile.ly"
1004 The line @code{\include "file.ly"} is equivalent to pasting the contents
1005 of file.ly into the current file at the place where you have the
1006 \include. For example, for a large project you might write separate files
1007 for each instrument part and create a @q{full score} file which brings
1008 together the individual instrument files.
1010 The initialization of LilyPond is done in a number of files that are
1011 included by default when you start the program, normally transparent to the
1012 user. Run @code{lilypond --verbose} to see a list of paths and files that Lily
1015 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
1016 VERSION is in the form @q{2.6.1}) are on the path and available to
1017 @code{\include}. Files in the
1018 current working directory are available to \include, but a file of the same
1019 name in LilyPond's installation takes precedence. Files are
1020 available to \include from directories in the search path specified as an
1021 option when invoking @code{lilypond --include=DIR} which adds DIR to the
1024 The @code{\include} statement can use full path information, but with the UNIX
1025 convention @code{/} rather than the DOS/Windows @code{\}. For example,
1026 if @file{stuff.ly} is located one directory higher than the current working
1030 \include "../stuff.ly"
1034 @node Different editions from one source
1035 @subsection Different editions from one source
1040 The @code{\tag} command marks music expressions with a name. These
1041 tagged expressions can be filtered out later. With this mechanism it
1042 is possible to make different versions of the same music source.
1044 In the following example, we see two versions of a piece of music, one
1045 for the full score, and one with cue notes for the instrumental part
1061 The same can be applied to articulations, texts, etc.: they are
1064 -\tag #@var{your-tag}
1066 to an articulation, for example,
1071 This defines a note with a conditional fingering indication.
1074 @cindex removeWithTag
1075 By applying the @code{\keepWithTag} and @code{\removeWithTag}
1076 commands, tagged expressions can be filtered. For example,
1080 \keepWithTag #'score @var{the music}
1081 \keepWithTag #'part @var{the music}
1087 @c @lilypondfile[ragged-right,quote]{tag-filter.ly}
1089 The arguments of the @code{\tag} command should be a symbol
1090 (such as @code{#'score} or @code{#'part}), followed by a
1091 music expression. It is possible to put multiple tags on
1092 a piece of music with multiple @code{\tag} entries,
1095 \tag #'original-part \tag #'transposed-part @dots{}
1101 Multiple rests are not merged if you create the score with both tagged
1106 @subsection Text encoding
1108 LilyPond uses the Pango library to format multi-lingual texts, and
1109 does not perform any input-encoding conversions. This means that any
1110 text, be it title, lyric text, or musical instruction containing
1111 non-ASCII characters, must be utf-8. The easiest way to enter such text is
1112 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
1113 popular modern editors have utf-8 support, for example, vim, Emacs,
1114 jEdit, and GEdit do.
1116 @c Currently not working
1118 Depending on the fonts installed, the following fragment shows Hebrew
1119 and Cyrillic lyrics,
1125 @li lypondfile[fontload]{utf-8.ly}
1127 The @TeX{} backend does not handle encoding specially at all. Strings
1128 in the input are put in the output as-is. Extents of text items in the
1129 @TeX{} backend, are determined by reading a file created via the
1130 @file{texstr} backend,
1133 lilypond -dbackend=texstr input/les-nereides.ly
1134 latex les-nereides.texstr
1137 The last command produces @file{les-nereides.textmetrics}, which is
1138 read when you execute
1141 lilypond -dbackend=tex input/les-nereides.ly
1144 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
1145 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
1146 interpreting non-ASCII strings.
1150 To use a Unicode escape sequence, use
1153 #(ly:export (ly:wide-char->utf-8 #x2014))
1157 @node Displaying LilyPond notation
1158 @subsection Displaying LilyPond notation
1160 @funindex \displayLilyMusic
1161 Displaying a music expression in LilyPond notation can be
1162 done using the music function @code{\displayLilyMusic}. For example,
1166 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1173 @{ a, cis e fis g @}
1176 By default, LilyPond will print these messages to the console along
1177 with all the other messages. To split up these messages and save
1178 the results of @code{\display@{STUFF@}}, redirect the output to
1182 lilypond file.ly >display.txt
1187 @node Controlling output
1188 @section Controlling output
1191 * Extracting fragments of music::
1192 * Skipping corrected music::
1195 @node Extracting fragments of music
1196 @subsection Extracting fragments of music
1198 It is possible to quote small fragments of a large score directly from
1199 the output. This can be compared to clipping a piece of a paper score
1202 This is done by defining the measures that need to be cut out
1203 separately. For example, including the following definition
1211 (make-rhythmic-location 5 1 2)
1212 (make-rhythmic-location 7 3 4)))
1217 will extract a fragment starting halfway the fifth measure, ending in
1218 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1219 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1221 More clip regions can be defined by adding more pairs of
1222 rhythmic-locations to the list.
1224 In order to use this feature, LilyPond must be invoked with
1225 @code{-dclip-systems}. The clips are output as EPS files, and are
1226 converted to PDF and PNG if these formats are switched on as well.
1228 For more information on output formats, see @rprogram{Invoking lilypond}.
1230 @node Skipping corrected music
1231 @subsection Skipping corrected music
1234 @funindex skipTypesetting
1235 @funindex showLastLength
1237 When entering or copying music, usually only the music near the end (where
1239 are adding notes) is interesting to view and correct. To speed up
1240 this correction process, it is possible to skip typesetting of all but
1241 the last few measures. This is achieved by putting
1244 showLastLength = R1*5
1249 in your source file. This will render only the last 5 measures
1250 (assuming 4/4 time signature) of every @code{\score} in the input
1251 file. For longer pieces, rendering only a small part is often an order
1252 of magnitude quicker than rendering it completely
1254 Skipping parts of a score can be controlled in a more fine-grained
1255 fashion with the property @code{Score.skipTypesetting}. When it is
1256 set, no typesetting is performed at all.
1258 This property is also used to control output to the MIDI file. Note that
1259 it skips all events, including tempo and instrument changes. You have
1262 @lilypond[quote,fragment,ragged-right,verbatim]
1265 \set Score.skipTypesetting = ##t
1267 \set Score.skipTypesetting = ##f
1271 In polyphonic music, @code{Score.skipTypesetting} will affect all
1272 voices and staves, saving even more time.