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.
16 FIXME: don't complain about anything in this chapter. It's still
17 under heavy development.
27 * Common syntax issues TODO name?::
28 * Other stuffs TODO move?::
35 The main format of input for LilyPond are text files. By convention,
36 these files end with @code{.ly}.
40 * A single music expression::
41 * Multiple scores in a book::
42 * Extracting fragments of notation::
43 * Including LilyPond files::
45 * Different editions from one source::
50 @subsection File structure
52 A @code{.ly} file contains any number of toplevel expressions, where a
53 toplevel expression is one of the following
57 An output definition, such as @code{\paper}, @code{\midi}, and
58 @code{\layout}. Such a definition at the toplevel changes the default
59 settings for the block entered.
62 A direct scheme expression, such as
63 @code{#(set-default-paper-size "a7" 'landscape)} or
64 @code{#(ly:set-option 'point-and-click #f)}.
67 A @code{\header} block. This sets the global header block. This
68 is the block containing the definitions for book-wide settings, like
72 A @code{\score} block. This score will be collected with other
73 toplevel scores, and combined as a single @code{\book}.
75 This behavior can be changed by setting the variable
76 @code{toplevel-score-handler} at toplevel. The default handler is
77 defined in the init file @file{scm/@/lily@/.scm}.
79 The @code{\score} must begin with a music expression, and may
80 contain only one music expression.
83 A @code{\book} block logically combines multiple movements
84 (i.e., multiple @code{\score} blocks) in one document. If there are
85 a number of @code{\scores}, one output file will be created for
86 each @code{\book} block, in which all corresponding movements are
87 concatenated. The only reason to explicitly specify @code{\book} blocks
88 in a @code{.ly} file is if you wish multiple output files from a single
89 input file. One exception is within lilypond-book documents, where you
90 explicitly have to add a @code{\book} block if you want more than a
91 single @code{\score} or @code{\markup} in the same example.
93 This behavior can be changed by setting the variable
94 @code{toplevel-book-handler} at toplevel. The default handler is
95 defined in the init file @file{scm/@/lily@/.scm}.
98 A compound music expression, such as
103 This will add the piece in a @code{\score} and format it in a
104 single book together with all other toplevel @code{\score}s and music
105 expressions. In other words, a file containing only the above
106 music expression will be translated into
122 This behavior can be changed by setting the variable
123 @code{toplevel-music-handler} at toplevel. The default handler is
124 defined in the init file @file{scm/@/lily@/.scm}.
127 A markup text, a verse for example
130 2. The first line verse two.
134 Markup texts are rendered above, between or below the scores or music
135 expressions, wherever they appear.
145 This can be used later on in the file by entering @code{\foo}. The
146 name of an variable should have alphabetic characters only; no
147 numbers, underscores or dashes.
151 The following example shows three things that may be entered at
156 % movements are non-justified by default
168 At any point in a file, any of the following lexical instructions can
172 @item @code{\version}
173 @item @code{\include}
174 @item @code{\sourcefilename}
175 @item @code{\sourcefileline}
180 @node A single music expression
181 @subsection A single music expression
183 A @code{\score} must contain a single music expression. However,
184 this music expression may be of any size. Recall that music
185 expressions may be included inside other expressions to form
186 larger expressions. All of these examples are single music
187 expressions; note the curly braces @{ @} or angle brackets <<
188 >> at the beginning and ending of the music.
194 @lilypond[ragged-right,verbatim,quote]
201 @lilypond[ragged-right,verbatim,quote]
203 \new Staff { c'4 c' c' c' }
204 \new Staff { d'4 d' d' d' }
212 \new Staff @{ \flute @}
213 \new Staff @{ \oboe @}
216 \new Staff @{ \violinI @}
217 \new Staff @{ \violinII @}
224 @node Multiple scores in a book
225 @subsection Multiple scores in a book
228 @cindex movements, multiple
230 A document may contain multiple pieces of music and texts. Examples
231 of these are an etude book, or an orchestral part with multiple
232 movements. Each movement is entered with a @code{\score} block,
240 and texts are entered with a @code{\markup} block,
250 All the movements and texts which appear in the same @code{.ly} file
251 will normally be typeset in the form of a single output file.
265 However, if you want multiple output files from the same @code{.ly}
266 file, then you can add multiple @code{\book} blocks, where each such
267 @code{\book} block will result in a separate output. If you do not
268 specify any @code{\book} block in the file, LilyPond will implicitly
269 treat the full file as a single @code{\book} block, see @ref{File
270 structure}. One important exception is within lilypond-book documents,
271 where you explicitly have to add a @code{\book} block, otherwise only
272 the first @code{\score} or @code{\markup} will appear in the output.
274 The header for each piece of music can be put inside the @code{\score}
275 block. The @code{piece} name from the header will be printed before
276 each movement. The title for the entire book can be put inside the
277 @code{\book}, but if it is not present, the @code{\header} which is at
278 the top of the file is inserted.
282 title = "Eight miniatures"
283 composer = "Igor Stravinsky"
287 \header @{ piece = "Romanze" @}
290 ..text of second verse..
293 ..text of third verse..
297 \header @{ piece = "Menuetto" @}
301 @node Extracting fragments of notation
302 @subsection Extracting fragments of notation
304 It is possible to quote small fragments of a large score directly from
305 the output. This can be compared to clipping a piece of a paper score
308 This is done by definining the measures that need to be cut out
309 separately. For example, including the following definition
317 (make-rhythmic-location 5 1 2)
318 (make-rhythmic-location 7 3 4)))
323 will extract a fragment starting halfway the fifth measure, ending in
324 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
325 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
327 More clip regions can be defined by adding more pairs of
328 rhythmic-locations to the list.
330 In order to use this feature, LilyPond must be invoked with
331 @code{-dclip-systems}. The clips are output as EPS files, and are
332 converted to PDF and PNG if these formats are switched on as well.
334 For more information on output formats, see @rprogram{Invoking lilypond}.
338 Examples: @c @lsr{non-notation,clip-systems.ly}
341 @node Including LilyPond files
342 @subsection Including LilyPond files
345 @cindex including files
347 A large project may be split up into separate files. To refer to another
351 \include "otherfile.ly"
354 The line @code{\include "file.ly"} is equivalent to pasting the contents
355 of file.ly into the current file at the place where you have the
356 \include. For example, for a large project you might write separate files
357 for each instrument part and create a @q{full score} file which brings
358 together the individual instrument files.
360 The initialization of LilyPond is done in a number of files that are
361 included by default when you start the program, normally transparent to the
362 user. Run lilypond --verbose to see a list of paths and files that Lily
365 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
366 VERSION is in the form @q{2.6.1}) are on the path and available to
367 @code{\include}. Files in the
368 current working directory are available to \include, but a file of the same
369 name in LilyPond's installation takes precedence. Files are
370 available to \include from directories in the search path specified as an
371 option when invoking @code{lilypond --include=DIR} which adds DIR to the
374 The @code{\include} statement can use full path information, but with the Unix
375 convention @code{/} rather than the DOS/Windows @code{\}. For example,
376 if @file{stuff.ly} is located one directory higher than the current working
380 \include "../stuff.ly"
385 @subsection Text encoding
387 LilyPond uses the Pango library to format multi-lingual texts, and
388 does not perform any input-encoding conversions. This means that any
389 text, be it title, lyric text, or musical instruction containing
390 non-ASCII characters, must be utf-8. The easiest way to enter such text is
391 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
392 popular modern editors have utf-8 support, for example, vim, Emacs,
395 @c Currently not working
397 Depending on the fonts installed, the following fragment shows Hebrew
404 @li lypondfile[fontload]{utf-8.ly}
406 The @TeX{} backend does not handle encoding specially at all. Strings
407 in the input are put in the output as-is. Extents of text items in the
408 @TeX{} backend, are determined by reading a file created via the
409 @file{texstr} backend,
412 lilypond -dbackend=texstr input/les-nereides.ly
413 latex les-nereides.texstr
416 The last command produces @file{les-nereides.textmetrics}, which is
417 read when you execute
420 lilypond -dbackend=tex input/les-nereides.ly
423 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
424 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
425 interpreting non-ASCII strings.
429 To use a Unicode escape sequence, use
432 #(ly:export (ly:wide-char->utf-8 #x2014))
438 @c @lsr{text,utf-8.ly}
441 @node Different editions from one source
442 @subsection Different editions from one source
447 The @code{\tag} command marks music expressions with a name. These
448 tagged expressions can be filtered out later. With this mechanism it
449 is possible to make different versions of the same music source.
451 In the following example, we see two versions of a piece of music, one
452 for the full score, and one with cue notes for the instrumental part
468 The same can be applied to articulations, texts, etc.: they are
471 -\tag #@var{your-tag}
473 to an articulation, for example,
478 This defines a note with a conditional fingering indication.
481 @cindex removeWithTag
482 By applying the @code{\keepWithTag} and @code{\removeWithTag}
483 commands, tagged expressions can be filtered. For example,
487 \keepWithTag #'score @var{the music}
488 \keepWithTag #'part @var{the music}
493 @lilypondfile[ragged-right,quote]{tag-filter.ly}
495 The arguments of the @code{\tag} command should be a symbol
496 (such as @code{#'score} or @code{#'part}), followed by a
497 music expression. It is possible to put multiple tags on
498 a piece of music with multiple @code{\tag} entries,
501 \tag #'original-part \tag #'transposed-part @dots{}
507 Examples: @c @lsr{parts,tag@/-filter@/.ly}
512 Multiple rests are not merged if you create the score with both tagged
516 @node Common syntax issues TODO name?
517 @section Common syntax issues TODO name?
520 * Controlling direction and placement::
521 * Distances and measurements MAYBE MOVE::
525 @node Controlling direction and placement
526 @subsection Controlling direction and placement
530 By default, lilypnod does a pretty jazz'n job of picking
531 directions. But in some cases, it may be desirable to force a
545 Maybe rename section to "directions".
547 Also mention \override Foo #'direction = #'DOWN.
549 also mention the typical \fooDown, \fooNeutral predefined commands.
551 also mention that some directions are (without other tweaking)
552 always up or always down (like dynamics or fermata), while other
553 things can alternate between up or down based on the stem direction
554 (like slurs or accents).
557 @node Distances and measurements MAYBE MOVE
558 @subsection Distances and measurements MAYBE MOVE
560 DISCUSS after working on other sections.
562 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
565 @node When to add a -
566 @subsection When to add a -
568 One of these works, the other doesn't.
572 { c'\mp\fermata\accent-\markup { "forcefully"} }
573 % { c'\mp\fermata\accent\markup { "forcefully"} }
577 @node Other stuffs TODO move?
578 @section Other stuffs TODO move?
582 * Displaying LilyPond notation::
583 * Skipping corrected music::
584 * context list FIXME::
585 * another thing FIXME::
586 * Input modes FIXME::
589 @node Displaying LilyPond notation
590 @subsection Displaying LilyPond notation
592 @funindex \displayLilyMusic
593 Displaying a music expression in LilyPond notation can be
594 done using the music function @code{\displayLilyMusic}. For example,
598 \displayLilyMusic \transpose c a, @{ c e g a bes @}
608 By default, LilyPond will print these messages to the console along
609 with all the other messages. To split up these messages and save
610 the results of @code{\display@{STUFF@}}, redirect the output to
614 lilypond file.ly >display.txt
618 @node Skipping corrected music
619 @subsection Skipping corrected music
622 @funindex skipTypesetting
623 @funindex showLastLength
625 When entering or copying music, usually only the music near the end (where
627 are adding notes) is interesting to view and correct. To speed up
628 this correction process, it is possible to skip typesetting of all but
629 the last few measures. This is achieved by putting
632 showLastLength = R1*5
637 in your source file. This will render only the last 5 measures
638 (assuming 4/4 time signature) of every @code{\score} in the input
639 file. For longer pieces, rendering only a small part is often an order
640 of magnitude quicker than rendering it completely
642 Skipping parts of a score can be controlled in a more fine-grained
643 fashion with the property @code{Score.skipTypesetting}. When it is
644 set, no typesetting is performed at all.
646 This property is also used to control output to the MIDI file. Note that
647 it skips all events, including tempo and instrument changes. You have
650 @lilypond[quote,fragment,ragged-right,verbatim]
653 \set Score.skipTypesetting = ##t
655 \set Score.skipTypesetting = ##f
659 In polyphonic music, @code{Score.skipTypesetting} will affect all
660 voices and staves, saving even more time.
663 @node context list FIXME
664 @subsection context list FIXME
666 >> > > - list of contexts: my *danger unmaintainable*
667 >> > > alarm just went off. I'm
669 I knew it would... And leaving out some of them is perfectly fine
671 I do think that a list like this, with the main contexts and a
673 description of what they do (perhaps also with a note about what
675 behaviour is associated with each of them, but this may be
677 should be there, and then we could simply list the remaining ones
679 further explanation and with links to the IR.
682 The Master Of All Contexts
683 ==========================
686 This is the top level notation context. No other context
688 contain a Score context. This context handles the
689 administration of time signatures. It also makes sure that
690 items such as clefs, time signatures, and key-signatures
692 aligned across staves.
693 You cannot explicitly instantiate a Score context (since
695 not contained in any other context). It is instantiated
696 automatically when an output definition (a \score or
699 (it should also be made clear somewhere what the
700 difference is between
703 Top-level contexts: Staff containers
704 ====================================
706 Groups staves while adding a bracket on the left side,
707 grouping the staves together. The bar lines of the
709 staves are connected vertically. StaffGroup only consists
711 collection of staves, with a bracket in front and spanning
715 Identical to StaffGroup except that the contained staves
717 not connected vertically.
719 A group of staves, with a brace on the left side, grouping
721 staves together. The bar lines of the contained staves are
722 connected vertically.
724 Just like GrandStaff but with a forced distance between
726 staves, so cross staff beaming and slurring can be used.
728 Handles typesetting for percussion. Can contain DrumVoice
735 Handles clefs, bar lines, keys, accidentals. It can
739 Like Staff but for printing rhythms. Pitches are
740 ignored; the notes are printed on one line.
742 Context for generating tablature. By default lays the
744 expression out as a guitar tablature, printed on six
747 Same as Staff, except that it is accommodated for
748 typesetting a piece in gregorian style.
750 Same as Staff, except that it is accommodated for
751 typesetting a piece in mensural style.
753 Voice-level (bottom) contexts
754 =============================
755 What is generated by default here? The voice-level contexts
757 certain properties and start engravers.
760 Corresponds to a voice on a staff. This context handles
762 conversion of dynamic signs, stems, beams, super- and
763 subscripts, slurs, ties, and rests.
764 You have to instantiate this explicitly if you want to
766 multiple voices on the same staff.
769 Same as Voice, except that it is accommodated for
770 typesetting a piece in gregorian style.
772 Same as Voice, except that it is accommodated for
773 typesetting a piece in mensural style.
775 Corresponds to a voice with lyrics. Handles the printing
777 single line of lyrics.
780 A voice on a percussion staff.
784 Typesets chord names. This context is a `bottom' context;
786 cannot contain other contexts.
788 ------------------------------
789 Then the following, which I don't know what to do with:
792 * GregorianTranscriptionVoice
793 * GregorianTranscriptionStaff
796 Engraves fretboards from chords. Not easy... Not
800 * CueVoice Not documented
802 Hard coded entry point for LilyPond. Cannot be tuned.
804 Silently discards all musical information given to this
808 @node another thing FIXME
809 @subsection another thing FIXME
811 Another thing that is needed, is an overview of the various naming
814 scheme functions: lowercase-with-hyphens (incl. one-word
816 scheme functions: ly:plus-scheme-style
817 music events, music classes and music properties:
819 Grob interfaces: scheme-style
820 backend properties: scheme-style (but X and Y!)
821 contexts (and MusicExpressions and grobs): Capitalized or
823 context properties: lowercaseFollowedByCamelCase
825 Capitalized_followed_by_lowercase_and_with_underscores
827 Which of these are conventions and which are rules?
828 Which are rules of the underlying language, and which are
832 @node Input modes FIXME
833 @subsection Input modes FIXME
837 \notemode turns the front end of LilyPond into note mode
838 (which is the default parsing mode).
839 It's certainly useful in certain situations, for example if you
840 are in \lyricmode or \chordmode or ... and want to insert
841 something that only can be done with \notemode syntax.
844 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
845 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
846 http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
847 http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html