1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
15 This section deals with general LilyPond input syntax issues,
16 rather than specific notation.
18 FIXME: don't complain about anything in this chapter. It's still
19 under heavy development.
29 * Common syntax issues TODO name?::
30 * Other stuffs TODO move?::
37 The main format of input for LilyPond are text files. By convention,
38 these files end with @code{.ly}.
42 * A single music expression::
43 * Multiple scores in a book::
44 * Extracting fragments of notation::
45 * Including LilyPond files::
47 * Different editions from one source::
52 @subsection File structure
54 A @code{.ly} file contains any number of toplevel expressions, where a
55 toplevel expression is one of the following
59 An output definition, such as @code{\paper}, @code{\midi}, and
60 @code{\layout}. Such a definition at the toplevel changes the default
61 settings for the block entered.
64 A direct scheme expression, such as
65 @code{#(set-default-paper-size "a7" 'landscape)} or
66 @code{#(ly:set-option 'point-and-click #f)}.
69 A @code{\header} block. This sets the global header block. This
70 is the block containing the definitions for book-wide settings, like
74 A @code{\score} block. This score will be collected with other
75 toplevel scores, and combined as a single @code{\book}.
77 This behavior can be changed by setting the variable
78 @code{toplevel-score-handler} at toplevel. The default handler is
79 defined in the init file @file{scm/@/lily@/.scm}.
81 The @code{\score} must begin with a music expression, and may
82 contain only one music expression.
85 A @code{\book} block logically combines multiple movements
86 (i.e., multiple @code{\score} blocks) in one document. If there are
87 a number of @code{\scores}, one output file will be created for
88 each @code{\book} block, in which all corresponding movements are
89 concatenated. The only reason to explicitly specify @code{\book} blocks
90 in a @code{.ly} file is if you wish multiple output files from a single
91 input file. One exception is within lilypond-book documents, where you
92 explicitly have to add a @code{\book} block if you want more than a
93 single @code{\score} or @code{\markup} in the same example.
95 This behavior can be changed by setting the variable
96 @code{toplevel-book-handler} at toplevel. The default handler is
97 defined in the init file @file{scm/@/lily@/.scm}.
100 A compound music expression, such as
105 This will add the piece in a @code{\score} and format it in a
106 single book together with all other toplevel @code{\score}s and music
107 expressions. In other words, a file containing only the above
108 music expression will be translated into
124 This behavior can be changed by setting the variable
125 @code{toplevel-music-handler} at toplevel. The default handler is
126 defined in the init file @file{scm/@/lily@/.scm}.
129 A markup text, a verse for example
132 2. The first line verse two.
136 Markup texts are rendered above, between or below the scores or music
137 expressions, wherever they appear.
147 This can be used later on in the file by entering @code{\foo}. The
148 name of an variable should have alphabetic characters only; no
149 numbers, underscores or dashes.
153 The following example shows three things that may be entered at
158 % movements are non-justified by default
170 At any point in a file, any of the following lexical instructions can
174 @item @code{\version}
175 @item @code{\include}
176 @item @code{\sourcefilename}
177 @item @code{\sourcefileline}
182 @node A single music expression
183 @subsection A single music expression
185 A @code{\score} must contain a single music expression. However,
186 this music expression may be of any size. Recall that music
187 expressions may be included inside other expressions to form
188 larger expressions. All of these examples are single music
189 expressions; note the curly braces @{ @} or angle brackets <<
190 >> at the beginning and ending of the music.
196 @lilypond[ragged-right,verbatim,quote]
203 @lilypond[ragged-right,verbatim,quote]
205 \new Staff { c'4 c' c' c' }
206 \new Staff { d'4 d' d' d' }
214 \new Staff @{ \flute @}
215 \new Staff @{ \oboe @}
218 \new Staff @{ \violinI @}
219 \new Staff @{ \violinII @}
226 @node Multiple scores in a book
227 @subsection Multiple scores in a book
230 @cindex movements, multiple
232 A document may contain multiple pieces of music and texts. Examples
233 of these are an etude book, or an orchestral part with multiple
234 movements. Each movement is entered with a @code{\score} block,
242 and texts are entered with a @code{\markup} block,
252 All the movements and texts which appear in the same @code{.ly} file
253 will normally be typeset in the form of a single output file.
267 However, if you want multiple output files from the same @code{.ly}
268 file, then you can add multiple @code{\book} blocks, where each such
269 @code{\book} block will result in a separate output. If you do not
270 specify any @code{\book} block in the file, LilyPond will implicitly
271 treat the full file as a single @code{\book} block, see @ref{File
272 structure}. One important exception is within lilypond-book documents,
273 where you explicitly have to add a @code{\book} block, otherwise only
274 the first @code{\score} or @code{\markup} will appear in the output.
276 The header for each piece of music can be put inside the @code{\score}
277 block. The @code{piece} name from the header will be printed before
278 each movement. The title for the entire book can be put inside the
279 @code{\book}, but if it is not present, the @code{\header} which is at
280 the top of the file is inserted.
284 title = "Eight miniatures"
285 composer = "Igor Stravinsky"
289 \header @{ piece = "Romanze" @}
292 ..text of second verse..
295 ..text of third verse..
299 \header @{ piece = "Menuetto" @}
303 @node Extracting fragments of notation
304 @subsection Extracting fragments of notation
306 It is possible to quote small fragments of a large score directly from
307 the output. This can be compared to clipping a piece of a paper score
310 This is done by defining the measures that need to be cut out
311 separately. For example, including the following definition
319 (make-rhythmic-location 5 1 2)
320 (make-rhythmic-location 7 3 4)))
325 will extract a fragment starting halfway the fifth measure, ending in
326 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
327 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
329 More clip regions can be defined by adding more pairs of
330 rhythmic-locations to the list.
332 In order to use this feature, LilyPond must be invoked with
333 @code{-dclip-systems}. The clips are output as EPS files, and are
334 converted to PDF and PNG if these formats are switched on as well.
336 For more information on output formats, see @rprogram{Invoking LilyPond}.
340 Examples: @c @lsr{non-notation,clip-systems.ly}
343 @node Including LilyPond files
344 @subsection Including LilyPond files
347 @cindex including files
349 A large project may be split up into separate files. To refer to another
353 \include "otherfile.ly"
356 The line @code{\include "file.ly"} is equivalent to pasting the contents
357 of file.ly into the current file at the place where you have the
358 \include. For example, for a large project you might write separate files
359 for each instrument part and create a @q{full score} file which brings
360 together the individual instrument files.
362 The initialization of LilyPond is done in a number of files that are
363 included by default when you start the program, normally transparent to the
364 user. Run @code{lilypond --verbose} to see a list of paths and files that Lily
367 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
368 VERSION is in the form @q{2.6.1}) are on the path and available to
369 @code{\include}. Files in the
370 current working directory are available to \include, but a file of the same
371 name in LilyPond's installation takes precedence. Files are
372 available to \include from directories in the search path specified as an
373 option when invoking @code{lilypond --include=DIR} which adds DIR to the
376 The @code{\include} statement can use full path information, but with the UNIX
377 convention @code{/} rather than the DOS/Windows @code{\}. For example,
378 if @file{stuff.ly} is located one directory higher than the current working
382 \include "../stuff.ly"
387 @subsection Text encoding
389 LilyPond uses the Pango library to format multi-lingual texts, and
390 does not perform any input-encoding conversions. This means that any
391 text, be it title, lyric text, or musical instruction containing
392 non-ASCII characters, must be utf-8. The easiest way to enter such text is
393 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
394 popular modern editors have utf-8 support, for example, vim, Emacs,
397 @c Currently not working
399 Depending on the fonts installed, the following fragment shows Hebrew
406 @li lypondfile[fontload]{utf-8.ly}
408 The @TeX{} backend does not handle encoding specially at all. Strings
409 in the input are put in the output as-is. Extents of text items in the
410 @TeX{} backend, are determined by reading a file created via the
411 @file{texstr} backend,
414 lilypond -dbackend=texstr input/les-nereides.ly
415 latex les-nereides.texstr
418 The last command produces @file{les-nereides.textmetrics}, which is
419 read when you execute
422 lilypond -dbackend=tex input/les-nereides.ly
425 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
426 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
427 interpreting non-ASCII strings.
431 To use a Unicode escape sequence, use
434 #(ly:export (ly:wide-char->utf-8 #x2014))
440 @c @lsr{text,utf-8.ly}
443 @node Different editions from one source
444 @subsection Different editions from one source
449 The @code{\tag} command marks music expressions with a name. These
450 tagged expressions can be filtered out later. With this mechanism it
451 is possible to make different versions of the same music source.
453 In the following example, we see two versions of a piece of music, one
454 for the full score, and one with cue notes for the instrumental part
470 The same can be applied to articulations, texts, etc.: they are
473 -\tag #@var{your-tag}
475 to an articulation, for example,
480 This defines a note with a conditional fingering indication.
483 @cindex removeWithTag
484 By applying the @code{\keepWithTag} and @code{\removeWithTag}
485 commands, tagged expressions can be filtered. For example,
489 \keepWithTag #'score @var{the music}
490 \keepWithTag #'part @var{the music}
496 @c @lilypondfile[ragged-right,quote]{tag-filter.ly}
498 The arguments of the @code{\tag} command should be a symbol
499 (such as @code{#'score} or @code{#'part}), followed by a
500 music expression. It is possible to put multiple tags on
501 a piece of music with multiple @code{\tag} entries,
504 \tag #'original-part \tag #'transposed-part @dots{}
510 Examples: @c @lsr{parts,tag@/-filter@/.ly}
515 Multiple rests are not merged if you create the score with both tagged
519 @node Common syntax issues TODO name?
520 @section Common syntax issues TODO name?
523 * Controlling direction and placement::
524 * Distances and measurements MAYBE MOVE::
528 @node Controlling direction and placement
529 @subsection Controlling direction and placement
533 By default, LilyPond does a pretty jazz'n job of picking
534 directions. But in some cases, it may be desirable to force a
548 Maybe rename section to "directions".
550 Also mention \override Foo #'direction = #'DOWN.
552 also mention the typical \fooDown, \fooNeutral predefined commands.
554 also mention that some directions are (without other tweaking)
555 always up or always down (like dynamics or fermata), while other
556 things can alternate between up or down based on the stem direction
557 (like slurs or accents).
560 @node Distances and measurements MAYBE MOVE
561 @subsection Distances and measurements MAYBE MOVE
563 DISCUSS after working on other sections.
565 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
568 @node When to add a -
569 @subsection When to add a -
571 One of these works, the other doesn't.
575 { c'\mp\fermata\accent-\markup { "forcefully"} }
576 % { c'\mp\fermata\accent\markup { "forcefully"} }
580 @node Other stuffs TODO move?
581 @section Other stuffs TODO move?
585 * Displaying LilyPond notation::
586 * Skipping corrected music::
587 * context list FIXME::
588 * another thing FIXME::
589 * Input modes FIXME::
592 @node Displaying LilyPond notation
593 @subsection Displaying LilyPond notation
595 @funindex \displayLilyMusic
596 Displaying a music expression in LilyPond notation can be
597 done using the music function @code{\displayLilyMusic}. For example,
601 \displayLilyMusic \transpose c a, @{ c e g a bes @}
611 By default, LilyPond will print these messages to the console along
612 with all the other messages. To split up these messages and save
613 the results of @code{\display@{STUFF@}}, redirect the output to
617 lilypond file.ly >display.txt
621 @node Skipping corrected music
622 @subsection Skipping corrected music
625 @funindex skipTypesetting
626 @funindex showLastLength
628 When entering or copying music, usually only the music near the end (where
630 are adding notes) is interesting to view and correct. To speed up
631 this correction process, it is possible to skip typesetting of all but
632 the last few measures. This is achieved by putting
635 showLastLength = R1*5
640 in your source file. This will render only the last 5 measures
641 (assuming 4/4 time signature) of every @code{\score} in the input
642 file. For longer pieces, rendering only a small part is often an order
643 of magnitude quicker than rendering it completely
645 Skipping parts of a score can be controlled in a more fine-grained
646 fashion with the property @code{Score.skipTypesetting}. When it is
647 set, no typesetting is performed at all.
649 This property is also used to control output to the MIDI file. Note that
650 it skips all events, including tempo and instrument changes. You have
653 @lilypond[quote,fragment,ragged-right,verbatim]
656 \set Score.skipTypesetting = ##t
658 \set Score.skipTypesetting = ##f
662 In polyphonic music, @code{Score.skipTypesetting} will affect all
663 voices and staves, saving even more time.
666 @node context list FIXME
667 @subsection context list FIXME
669 >> > > - list of contexts: my *danger unmaintainable*
670 >> > > alarm just went off. I'm
672 I knew it would... And leaving out some of them is perfectly fine
674 I do think that a list like this, with the main contexts and a
676 description of what they do (perhaps also with a note about what
678 behavior is associated with each of them, but this may be
680 should be there, and then we could simply list the remaining ones
682 further explanation and with links to the IR.
685 The Master Of All Contexts
686 ==========================
689 This is the top level notation context. No other context
691 contain a Score context. This context handles the
692 administration of time signatures. It also makes sure that
693 items such as clefs, time signatures, and key-signatures
695 aligned across staves.
696 You cannot explicitly instantiate a Score context (since
698 not contained in any other context). It is instantiated
699 automatically when an output definition (a \score or
702 (it should also be made clear somewhere what the
703 difference is between
706 Top-level contexts: Staff containers
707 ====================================
709 Groups staves while adding a bracket on the left side,
710 grouping the staves together. The bar lines of the
712 staves are connected vertically. StaffGroup only consists
714 collection of staves, with a bracket in front and spanning
718 Identical to StaffGroup except that the contained staves
720 not connected vertically.
722 A group of staves, with a brace on the left side, grouping
724 staves together. The bar lines of the contained staves are
725 connected vertically.
727 Just like GrandStaff but with a forced distance between
729 staves, so cross staff beaming and slurring can be used.
731 Handles typesetting for percussion. Can contain DrumVoice
738 Handles clefs, bar lines, keys, accidentals. It can
742 Like Staff but for printing rhythms. Pitches are
743 ignored; the notes are printed on one line.
745 Context for generating tablature. By default lays the
747 expression out as a guitar tablature, printed on six
750 Same as Staff, except that it is accommodated for
751 typesetting a piece in gregorian style.
753 Same as Staff, except that it is accommodated for
754 typesetting a piece in mensural style.
756 Voice-level (bottom) contexts
757 =============================
758 What is generated by default here? The voice-level contexts
760 certain properties and start engravers.
763 Corresponds to a voice on a staff. This context handles
765 conversion of dynamic signs, stems, beams, super- and
766 subscripts, slurs, ties, and rests.
767 You have to instantiate this explicitly if you want to
769 multiple voices on the same staff.
772 Same as Voice, except that it is accommodated for
773 typesetting a piece in gregorian style.
775 Same as Voice, except that it is accommodated for
776 typesetting a piece in mensural style.
778 Corresponds to a voice with lyrics. Handles the printing
780 single line of lyrics.
783 A voice on a percussion staff.
787 Typesets chord names. This context is a `bottom' context;
789 cannot contain other contexts.
791 ------------------------------
792 Then the following, which I don't know what to do with:
795 * GregorianTranscriptionVoice
796 * GregorianTranscriptionStaff
799 Engraves fretboards from chords. Not easy... Not
803 * CueVoice Not documented
805 Hard coded entry point for LilyPond. Cannot be tuned.
807 Silently discards all musical information given to this
811 @node another thing FIXME
812 @subsection another thing FIXME
814 Another thing that is needed, is an overview of the various naming
817 scheme functions: lowercase-with-hyphens (incl. one-word
819 scheme functions: ly:plus-scheme-style
820 music events, music classes and music properties:
822 Grob interfaces: scheme-style
823 backend properties: scheme-style (but X and Y!)
824 contexts (and MusicExpressions and grobs): Capitalized or
826 context properties: lowercaseFollowedByCamelCase
828 Capitalized_followed_by_lowercase_and_with_underscores
830 Which of these are conventions and which are rules?
831 Which are rules of the underlying language, and which are
835 @node Input modes FIXME
836 @subsection Input modes FIXME
840 \notemode turns the front end of LilyPond into note mode
841 (which is the default parsing mode).
842 It's certainly useful in certain situations, for example if you
843 are in \lyricmode or \chordmode or ... and want to insert
844 something that only can be done with \notemode syntax.
847 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
848 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
849 http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
850 http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html