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.
13 This section deals with general lilypond input syntax issues,
14 rather than specific notation.
18 * Common syntax issues TODO name?::
19 * Other stuffs TODO move?::
26 The main format of input for LilyPond are text files. By convention,
27 these files end with @code{.ly}.
31 * A single music expression::
32 * Multiple scores in a book::
33 * Extracting fragments of notation::
34 * Including LilyPond files::
36 * Different editions from one source::
41 @subsection File structure
43 A @code{.ly} file contains any number of toplevel expressions, where a
44 toplevel expression is one of the following
48 An output definition, such as @code{\paper}, @code{\midi}, and
49 @code{\layout}. Such a definition at the toplevel changes the default
50 settings for the block entered.
53 A direct scheme expression, such as
54 @code{#(set-default-paper-size "a7" 'landscape)} or
55 @code{#(ly:set-option 'point-and-click #f)}.
58 A @code{\header} block. This sets the global header block. This
59 is the block containing the definitions for book-wide settings, like
63 A @code{\score} block. This score will be collected with other
64 toplevel scores, and combined as a single @code{\book}.
66 This behavior can be changed by setting the variable
67 @code{toplevel-score-handler} at toplevel. The default handler is
68 defined in the init file @file{scm/@/lily@/.scm}.
70 The @code{\score} must begin with a music expression, and may
71 contain only one music expression.
74 A @code{\book} block logically combines multiple movements
75 (i.e., multiple @code{\score} blocks) in one document. If there are
76 a number of @code{\scores}, one output file will be created for
77 each @code{\book} block, in which all corresponding movements are
78 concatenated. The only reason to explicitly specify @code{\book} blocks
79 in a @code{.ly} file is if you wish multiple output files from a single
80 input file. One exception is within lilypond-book documents, where you
81 explicitly have to add a @code{\book} block if you want more than a
82 single @code{\score} or @code{\markup} in the same example.
84 This behavior can be changed by setting the variable
85 @code{toplevel-book-handler} at toplevel. The default handler is
86 defined in the init file @file{scm/@/lily@/.scm}.
89 A compound music expression, such as
94 This will add the piece in a @code{\score} and format it in a
95 single book together with all other toplevel @code{\score}s and music
96 expressions. In other words, a file containing only the above
97 music expression will be translated into
113 This behavior can be changed by setting the variable
114 @code{toplevel-music-handler} at toplevel. The default handler is
115 defined in the init file @file{scm/@/lily@/.scm}.
118 A markup text, a verse for example
121 2. The first line verse two.
125 Markup texts are rendered above, between or below the scores or music
126 expressions, wherever they appear.
136 This can be used later on in the file by entering @code{\foo}. The
137 name of an variable should have alphabetic characters only; no
138 numbers, underscores or dashes.
142 The following example shows three things that may be entered at
147 % movements are non-justified by default
159 At any point in a file, any of the following lexical instructions can
163 @item @code{\version}
164 @item @code{\include}
165 @item @code{\sourcefilename}
166 @item @code{\sourcefileline}
171 @node A single music expression
172 @subsection A single music expression
174 A @code{\score} must contain a single music expression. However,
175 this music expression may be of any size. Recall that music
176 expressions may be included inside other expressions to form
177 larger expressions. All of these examples are single music
178 expressions; note the curly braces @{ @} or angle brackets <<
179 >> at the beginning and ending of the music.
185 @lilypond[ragged-right,verbatim,quote]
192 @lilypond[ragged-right,verbatim,quote]
194 \new Staff { c'4 c' c' c' }
195 \new Staff { d'4 d' d' d' }
203 \new Staff @{ \flute @}
204 \new Staff @{ \oboe @}
207 \new Staff @{ \violinI @}
208 \new Staff @{ \violinII @}
215 @node Multiple scores in a book
216 @subsection Multiple scores in a book
219 @cindex movements, multiple
221 A document may contain multiple pieces of music and texts. Examples
222 of these are an etude book, or an orchestral part with multiple
223 movements. Each movement is entered with a @code{\score} block,
231 and texts are entered with a @code{\markup} block,
241 All the movements and texts which appear in the same @code{.ly} file
242 will normally be typeset in the form of a single output file.
256 However, if you want multiple output files from the same @code{.ly}
257 file, then you can add multiple @code{\book} blocks, where each such
258 @code{\book} block will result in a separate output. If you do not
259 specify any @code{\book} block in the file, LilyPond will implicitly
260 treat the full file as a single @code{\book} block, see @ref{File
261 structure}. One important exception is within lilypond-book documents,
262 where you explicitly have to add a @code{\book} block, otherwise only
263 the first @code{\score} or @code{\markup} will appear in the output.
265 The header for each piece of music can be put inside the @code{\score}
266 block. The @code{piece} name from the header will be printed before
267 each movement. The title for the entire book can be put inside the
268 @code{\book}, but if it is not present, the @code{\header} which is at
269 the top of the file is inserted.
273 title = "Eight miniatures"
274 composer = "Igor Stravinsky"
278 \header @{ piece = "Romanze" @}
281 ..text of second verse..
284 ..text of third verse..
288 \header @{ piece = "Menuetto" @}
292 @node Extracting fragments of notation
293 @subsection Extracting fragments of notation
295 It is possible to quote small fragments of a large score directly from
296 the output. This can be compared to clipping a piece of a paper score
299 This is done by definining the measures that need to be cut out
300 separately. For example, including the following definition
308 (make-rhythmic-location 5 1 2)
309 (make-rhythmic-location 7 3 4)))
314 will extract a fragment starting halfway the fifth measure, ending in
315 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
316 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
318 More clip regions can be defined by adding more pairs of
319 rhythmic-locations to the list.
321 In order to use this feature, LilyPond must be invoked with
322 @code{-dclip-systems}. The clips are output as EPS files, and are
323 converted to PDF and PNG if these formats are switched on as well.
325 For more information on output formats, see @rprogram{Invoking lilypond}.
329 Examples: @lsr{non-notation,clip-systems.ly}
332 @node Including LilyPond files
333 @subsection Including LilyPond files
336 @cindex including files
338 A large project may be split up into separate files. To refer to another
342 \include "otherfile.ly"
345 The line @code{\include "file.ly"} is equivalent to pasting the contents
346 of file.ly into the current file at the place where you have the
347 \include. For example, for a large project you might write separate files
348 for each instrument part and create a @q{full score} file which brings
349 together the individual instrument files.
351 The initialization of LilyPond is done in a number of files that are
352 included by default when you start the program, normally transparent to the
353 user. Run lilypond --verbose to see a list of paths and files that Lily
356 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
357 VERSION is in the form @q{2.6.1}) are on the path and available to
358 @code{\include}. Files in the
359 current working directory are available to \include, but a file of the same
360 name in LilyPond's installation takes precedence. Files are
361 available to \include from directories in the search path specified as an
362 option when invoking @code{lilypond --include=DIR} which adds DIR to the
365 The @code{\include} statement can use full path information, but with the Unix
366 convention @code{/} rather than the DOS/Windows @code{\}. For example,
367 if @file{stuff.ly} is located one directory higher than the current working
371 \include "../stuff.ly"
376 @subsection Text encoding
378 LilyPond uses the Pango library to format multi-lingual texts, and
379 does not perform any input-encoding conversions. This means that any
380 text, be it title, lyric text, or musical instruction containing
381 non-ASCII characters, must be utf-8. The easiest way to enter such text is
382 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
383 popular modern editors have utf-8 support, for example, vim, Emacs,
386 @c Currently not working
388 Depending on the fonts installed, the following fragment shows Hebrew
395 @li lypondfile[fontload]{utf-8.ly}
397 The @TeX{} backend does not handle encoding specially at all. Strings
398 in the input are put in the output as-is. Extents of text items in the
399 @TeX{} backend, are determined by reading a file created via the
400 @file{texstr} backend,
403 lilypond -dbackend=texstr input/les-nereides.ly
404 latex les-nereides.texstr
407 The last command produces @file{les-nereides.textmetrics}, which is
408 read when you execute
411 lilypond -dbackend=tex input/les-nereides.ly
414 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
415 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
416 interpreting non-ASCII strings.
420 To use a Unicode escape sequence, use
423 #(ly:export (ly:wide-char->utf-8 #x2014))
432 @node Different editions from one source
433 @subsection Different editions from one source
438 The @code{\tag} command marks music expressions with a name. These
439 tagged expressions can be filtered out later. With this mechanism it
440 is possible to make different versions of the same music source.
442 In the following example, we see two versions of a piece of music, one
443 for the full score, and one with cue notes for the instrumental part
459 The same can be applied to articulations, texts, etc.: they are
462 -\tag #@var{your-tag}
464 to an articulation, for example,
469 This defines a note with a conditional fingering indication.
472 @cindex removeWithTag
473 By applying the @code{\keepWithTag} and @code{\removeWithTag}
474 commands, tagged expressions can be filtered. For example,
478 \keepWithTag #'score @var{the music}
479 \keepWithTag #'part @var{the music}
484 @lilypondfile[ragged-right,quote]{tag-filter.ly}
486 The arguments of the @code{\tag} command should be a symbol
487 (such as @code{#'score} or @code{#'part}), followed by a
488 music expression. It is possible to put multiple tags on
489 a piece of music with multiple @code{\tag} entries,
492 \tag #'original-part \tag #'transposed-part @dots{}
498 Examples: @lsr{parts,tag@/-filter@/.ly}
503 Multiple rests are not merged if you create the score with both tagged
507 @node Common syntax issues TODO name?
508 @section Common syntax issues TODO name?
512 * Distances and measurements MAYBE MOVE::
516 @subsection Up and down
520 By default, lilypnod does a pretty jazz'n job of picking
521 directions. But in some cases, it may be desirable to force a
535 Maybe rename section to "directions".
538 @node Distances and measurements MAYBE MOVE
539 @subsection Distances and measurements MAYBE MOVE
541 DISCUSS after working on other sections.
543 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
549 @node Other stuffs TODO move?
550 @section Other stuffs TODO move?
554 * Displaying LilyPond notation::
555 * Skipping corrected music::
558 @node Displaying LilyPond notation
559 @subsection Displaying LilyPond notation
561 @funindex \displayLilyMusic
562 Displaying a music expression in LilyPond notation can be
563 done using the music function @code{\displayLilyMusic}. For example,
567 \displayLilyMusic \transpose c a, @{ c e g a bes @}
577 By default, LilyPond will print these messages to the console along
578 with all the other messages. To split up these messages and save
579 the results of @code{\display@{STUFF@}}, redirect the output to
583 lilypond file.ly >display.txt
587 @node Skipping corrected music
588 @subsection Skipping corrected music
591 @funindex skipTypesetting
592 @funindex showLastLength
594 When entering or copying music, usually only the music near the end (where
596 are adding notes) is interesting to view and correct. To speed up
597 this correction process, it is possible to skip typesetting of all but
598 the last few measures. This is achieved by putting
601 showLastLength = R1*5
606 in your source file. This will render only the last 5 measures
607 (assuming 4/4 time signature) of every @code{\score} in the input
608 file. For longer pieces, rendering only a small part is often an order
609 of magnitude quicker than rendering it completely
611 Skipping parts of a score can be controlled in a more fine-grained
612 fashion with the property @code{Score.skipTypesetting}. When it is
613 set, no typesetting is performed at all.
615 This property is also used to control output to the MIDI file. Note that
616 it skips all events, including tempo and instrument changes. You have
619 @lilypond[quote,fragment,ragged-right,verbatim]
622 \set Score.skipTypesetting = ##t
624 \set Score.skipTypesetting = ##f
628 In polyphonic music, @code{Score.skipTypesetting} will affect all
629 voices and staves, saving even more time.