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.
21 * Common syntax issues TODO name?::
22 * Other stuffs TODO move?::
29 The main format of input for LilyPond are text files. By convention,
30 these files end with @code{.ly}.
34 * A single music expression::
35 * Multiple scores in a book::
36 * Extracting fragments of notation::
37 * Including LilyPond files::
39 * Different editions from one source::
44 @subsection File structure
46 A @code{.ly} file contains any number of toplevel expressions, where a
47 toplevel expression is one of the following
51 An output definition, such as @code{\paper}, @code{\midi}, and
52 @code{\layout}. Such a definition at the toplevel changes the default
53 settings for the block entered.
56 A direct scheme expression, such as
57 @code{#(set-default-paper-size "a7" 'landscape)} or
58 @code{#(ly:set-option 'point-and-click #f)}.
61 A @code{\header} block. This sets the global header block. This
62 is the block containing the definitions for book-wide settings, like
66 A @code{\score} block. This score will be collected with other
67 toplevel scores, and combined as a single @code{\book}.
69 This behavior can be changed by setting the variable
70 @code{toplevel-score-handler} at toplevel. The default handler is
71 defined in the init file @file{scm/@/lily@/.scm}.
73 The @code{\score} must begin with a music expression, and may
74 contain only one music expression.
77 A @code{\book} block logically combines multiple movements
78 (i.e., multiple @code{\score} blocks) in one document. If there are
79 a number of @code{\scores}, one output file will be created for
80 each @code{\book} block, in which all corresponding movements are
81 concatenated. The only reason to explicitly specify @code{\book} blocks
82 in a @code{.ly} file is if you wish multiple output files from a single
83 input file. One exception is within lilypond-book documents, where you
84 explicitly have to add a @code{\book} block if you want more than a
85 single @code{\score} or @code{\markup} in the same example.
87 This behavior can be changed by setting the variable
88 @code{toplevel-book-handler} at toplevel. The default handler is
89 defined in the init file @file{scm/@/lily@/.scm}.
92 A compound music expression, such as
97 This will add the piece in a @code{\score} and format it in a
98 single book together with all other toplevel @code{\score}s and music
99 expressions. In other words, a file containing only the above
100 music expression will be translated into
116 This behavior can be changed by setting the variable
117 @code{toplevel-music-handler} at toplevel. The default handler is
118 defined in the init file @file{scm/@/lily@/.scm}.
121 A markup text, a verse for example
124 2. The first line verse two.
128 Markup texts are rendered above, between or below the scores or music
129 expressions, wherever they appear.
139 This can be used later on in the file by entering @code{\foo}. The
140 name of an variable should have alphabetic characters only; no
141 numbers, underscores or dashes.
145 The following example shows three things that may be entered at
150 % movements are non-justified by default
162 At any point in a file, any of the following lexical instructions can
166 @item @code{\version}
167 @item @code{\include}
168 @item @code{\sourcefilename}
169 @item @code{\sourcefileline}
174 @node A single music expression
175 @subsection A single music expression
177 A @code{\score} must contain a single music expression. However,
178 this music expression may be of any size. Recall that music
179 expressions may be included inside other expressions to form
180 larger expressions. All of these examples are single music
181 expressions; note the curly braces @{ @} or angle brackets <<
182 >> at the beginning and ending of the music.
188 @lilypond[ragged-right,verbatim,quote]
195 @lilypond[ragged-right,verbatim,quote]
197 \new Staff { c'4 c' c' c' }
198 \new Staff { d'4 d' d' d' }
206 \new Staff @{ \flute @}
207 \new Staff @{ \oboe @}
210 \new Staff @{ \violinI @}
211 \new Staff @{ \violinII @}
218 @node Multiple scores in a book
219 @subsection Multiple scores in a book
222 @cindex movements, multiple
224 A document may contain multiple pieces of music and texts. Examples
225 of these are an etude book, or an orchestral part with multiple
226 movements. Each movement is entered with a @code{\score} block,
234 and texts are entered with a @code{\markup} block,
244 All the movements and texts which appear in the same @code{.ly} file
245 will normally be typeset in the form of a single output file.
259 However, if you want multiple output files from the same @code{.ly}
260 file, then you can add multiple @code{\book} blocks, where each such
261 @code{\book} block will result in a separate output. If you do not
262 specify any @code{\book} block in the file, LilyPond will implicitly
263 treat the full file as a single @code{\book} block, see @ref{File
264 structure}. One important exception is within lilypond-book documents,
265 where you explicitly have to add a @code{\book} block, otherwise only
266 the first @code{\score} or @code{\markup} will appear in the output.
268 The header for each piece of music can be put inside the @code{\score}
269 block. The @code{piece} name from the header will be printed before
270 each movement. The title for the entire book can be put inside the
271 @code{\book}, but if it is not present, the @code{\header} which is at
272 the top of the file is inserted.
276 title = "Eight miniatures"
277 composer = "Igor Stravinsky"
281 \header @{ piece = "Romanze" @}
284 ..text of second verse..
287 ..text of third verse..
291 \header @{ piece = "Menuetto" @}
295 @node Extracting fragments of notation
296 @subsection Extracting fragments of notation
298 It is possible to quote small fragments of a large score directly from
299 the output. This can be compared to clipping a piece of a paper score
302 This is done by definining the measures that need to be cut out
303 separately. For example, including the following definition
311 (make-rhythmic-location 5 1 2)
312 (make-rhythmic-location 7 3 4)))
317 will extract a fragment starting halfway the fifth measure, ending in
318 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
319 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
321 More clip regions can be defined by adding more pairs of
322 rhythmic-locations to the list.
324 In order to use this feature, LilyPond must be invoked with
325 @code{-dclip-systems}. The clips are output as EPS files, and are
326 converted to PDF and PNG if these formats are switched on as well.
328 For more information on output formats, see @rprogram{Invoking lilypond}.
332 Examples: @c @lsr{non-notation,clip-systems.ly}
335 @node Including LilyPond files
336 @subsection Including LilyPond files
339 @cindex including files
341 A large project may be split up into separate files. To refer to another
345 \include "otherfile.ly"
348 The line @code{\include "file.ly"} is equivalent to pasting the contents
349 of file.ly into the current file at the place where you have the
350 \include. For example, for a large project you might write separate files
351 for each instrument part and create a @q{full score} file which brings
352 together the individual instrument files.
354 The initialization of LilyPond is done in a number of files that are
355 included by default when you start the program, normally transparent to the
356 user. Run lilypond --verbose to see a list of paths and files that Lily
359 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
360 VERSION is in the form @q{2.6.1}) are on the path and available to
361 @code{\include}. Files in the
362 current working directory are available to \include, but a file of the same
363 name in LilyPond's installation takes precedence. Files are
364 available to \include from directories in the search path specified as an
365 option when invoking @code{lilypond --include=DIR} which adds DIR to the
368 The @code{\include} statement can use full path information, but with the Unix
369 convention @code{/} rather than the DOS/Windows @code{\}. For example,
370 if @file{stuff.ly} is located one directory higher than the current working
374 \include "../stuff.ly"
379 @subsection Text encoding
381 LilyPond uses the Pango library to format multi-lingual texts, and
382 does not perform any input-encoding conversions. This means that any
383 text, be it title, lyric text, or musical instruction containing
384 non-ASCII characters, must be utf-8. The easiest way to enter such text is
385 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
386 popular modern editors have utf-8 support, for example, vim, Emacs,
389 @c Currently not working
391 Depending on the fonts installed, the following fragment shows Hebrew
398 @li lypondfile[fontload]{utf-8.ly}
400 The @TeX{} backend does not handle encoding specially at all. Strings
401 in the input are put in the output as-is. Extents of text items in the
402 @TeX{} backend, are determined by reading a file created via the
403 @file{texstr} backend,
406 lilypond -dbackend=texstr input/les-nereides.ly
407 latex les-nereides.texstr
410 The last command produces @file{les-nereides.textmetrics}, which is
411 read when you execute
414 lilypond -dbackend=tex input/les-nereides.ly
417 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
418 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
419 interpreting non-ASCII strings.
423 To use a Unicode escape sequence, use
426 #(ly:export (ly:wide-char->utf-8 #x2014))
432 @c @lsr{text,utf-8.ly}
435 @node Different editions from one source
436 @subsection Different editions from one source
441 The @code{\tag} command marks music expressions with a name. These
442 tagged expressions can be filtered out later. With this mechanism it
443 is possible to make different versions of the same music source.
445 In the following example, we see two versions of a piece of music, one
446 for the full score, and one with cue notes for the instrumental part
462 The same can be applied to articulations, texts, etc.: they are
465 -\tag #@var{your-tag}
467 to an articulation, for example,
472 This defines a note with a conditional fingering indication.
475 @cindex removeWithTag
476 By applying the @code{\keepWithTag} and @code{\removeWithTag}
477 commands, tagged expressions can be filtered. For example,
481 \keepWithTag #'score @var{the music}
482 \keepWithTag #'part @var{the music}
487 @lilypondfile[ragged-right,quote]{tag-filter.ly}
489 The arguments of the @code{\tag} command should be a symbol
490 (such as @code{#'score} or @code{#'part}), followed by a
491 music expression. It is possible to put multiple tags on
492 a piece of music with multiple @code{\tag} entries,
495 \tag #'original-part \tag #'transposed-part @dots{}
501 Examples: @c @lsr{parts,tag@/-filter@/.ly}
506 Multiple rests are not merged if you create the score with both tagged
510 @node Common syntax issues TODO name?
511 @section Common syntax issues TODO name?
514 * Controlling direction::
515 * Distances and measurements MAYBE MOVE::
518 @node Controlling direction
519 @subsection Controlling direction
523 By default, lilypnod does a pretty jazz'n job of picking
524 directions. But in some cases, it may be desirable to force a
538 Maybe rename section to "directions".
540 Also mention \override Foo #'direction = #'DOWN.
542 also mention the typical \fooDown, \fooNeutral predefined commands.
545 @node Distances and measurements MAYBE MOVE
546 @subsection Distances and measurements MAYBE MOVE
548 DISCUSS after working on other sections.
550 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
556 @node Other stuffs TODO move?
557 @section Other stuffs TODO move?
561 * Displaying LilyPond notation::
562 * Skipping corrected music::
563 * context list FIXME::
564 * another thing FIXME::
565 * Input modes FIXME::
568 @node Displaying LilyPond notation
569 @subsection Displaying LilyPond notation
571 @funindex \displayLilyMusic
572 Displaying a music expression in LilyPond notation can be
573 done using the music function @code{\displayLilyMusic}. For example,
577 \displayLilyMusic \transpose c a, @{ c e g a bes @}
587 By default, LilyPond will print these messages to the console along
588 with all the other messages. To split up these messages and save
589 the results of @code{\display@{STUFF@}}, redirect the output to
593 lilypond file.ly >display.txt
597 @node Skipping corrected music
598 @subsection Skipping corrected music
601 @funindex skipTypesetting
602 @funindex showLastLength
604 When entering or copying music, usually only the music near the end (where
606 are adding notes) is interesting to view and correct. To speed up
607 this correction process, it is possible to skip typesetting of all but
608 the last few measures. This is achieved by putting
611 showLastLength = R1*5
616 in your source file. This will render only the last 5 measures
617 (assuming 4/4 time signature) of every @code{\score} in the input
618 file. For longer pieces, rendering only a small part is often an order
619 of magnitude quicker than rendering it completely
621 Skipping parts of a score can be controlled in a more fine-grained
622 fashion with the property @code{Score.skipTypesetting}. When it is
623 set, no typesetting is performed at all.
625 This property is also used to control output to the MIDI file. Note that
626 it skips all events, including tempo and instrument changes. You have
629 @lilypond[quote,fragment,ragged-right,verbatim]
632 \set Score.skipTypesetting = ##t
634 \set Score.skipTypesetting = ##f
638 In polyphonic music, @code{Score.skipTypesetting} will affect all
639 voices and staves, saving even more time.
642 @node context list FIXME
643 @subsection context list FIXME
645 >> > > - list of contexts: my *danger unmaintainable*
646 >> > > alarm just went off. I'm
648 I knew it would... And leaving out some of them is perfectly fine
650 I do think that a list like this, with the main contexts and a
652 description of what they do (perhaps also with a note about what
654 behaviour is associated with each of them, but this may be
656 should be there, and then we could simply list the remaining ones
658 further explanation and with links to the IR.
661 The Master Of All Contexts
662 ==========================
665 This is the top level notation context. No other context
667 contain a Score context. This context handles the
668 administration of time signatures. It also makes sure that
669 items such as clefs, time signatures, and key-signatures
671 aligned across staves.
672 You cannot explicitly instantiate a Score context (since
674 not contained in any other context). It is instantiated
675 automatically when an output definition (a \score or
678 (it should also be made clear somewhere what the
679 difference is between
682 Top-level contexts: Staff containers
683 ====================================
685 Groups staves while adding a bracket on the left side,
686 grouping the staves together. The bar lines of the
688 staves are connected vertically. StaffGroup only consists
690 collection of staves, with a bracket in front and spanning
694 Identical to StaffGroup except that the contained staves
696 not connected vertically.
698 A group of staves, with a brace on the left side, grouping
700 staves together. The bar lines of the contained staves are
701 connected vertically.
703 Just like GrandStaff but with a forced distance between
705 staves, so cross staff beaming and slurring can be used.
707 Handles typesetting for percussion. Can contain DrumVoice
714 Handles clefs, bar lines, keys, accidentals. It can
718 Like Staff but for printing rhythms. Pitches are
719 ignored; the notes are printed on one line.
721 Context for generating tablature. By default lays the
723 expression out as a guitar tablature, printed on six
726 Same as Staff, except that it is accommodated for
727 typesetting a piece in gregorian style.
729 Same as Staff, except that it is accommodated for
730 typesetting a piece in mensural style.
732 Voice-level (bottom) contexts
733 =============================
734 What is generated by default here? The voice-level contexts
736 certain properties and start engravers.
739 Corresponds to a voice on a staff. This context handles
741 conversion of dynamic signs, stems, beams, super- and
742 subscripts, slurs, ties, and rests.
743 You have to instantiate this explicitly if you want to
745 multiple voices on the same staff.
748 Same as Voice, except that it is accommodated for
749 typesetting a piece in gregorian style.
751 Same as Voice, except that it is accommodated for
752 typesetting a piece in mensural style.
754 Corresponds to a voice with lyrics. Handles the printing
756 single line of lyrics.
759 A voice on a percussion staff.
763 Typesets chord names. This context is a `bottom' context;
765 cannot contain other contexts.
767 ------------------------------
768 Then the following, which I don't know what to do with:
771 * GregorianTranscriptionVoice
772 * GregorianTranscriptionStaff
775 Engraves fretboards from chords. Not easy... Not
779 * CueVoice Not documented
781 Hard coded entry point for LilyPond. Cannot be tuned.
783 Silently discards all musical information given to this
787 @node another thing FIXME
788 @subsection another thing FIXME
790 Another thing that is needed, is an overview of the various naming
793 scheme functions: lowercase-with-hyphens (incl. one-word
795 scheme functions: ly:plus-scheme-style
796 music events, music classes and music properties:
798 Grob interfaces: scheme-style
799 backend properties: scheme-style (but X and Y!)
800 contexts (and MusicExpressions and grobs): Capitalized or
802 context properties: lowercaseFollowedByCamelCase
804 Capitalized_followed_by_lowercase_and_with_underscores
806 Which of these are conventions and which are rules?
807 Which are rules of the underlying language, and which are
811 @node Input modes FIXME
812 @subsection Input modes FIXME
816 \notemode turns the front end of LilyPond into note mode
817 (which is the default parsing mode).
818 It's certainly useful in certain situations, for example if you
819 are in \lyricmode or \chordmode or ... and want to insert
820 something that only can be done with \notemode syntax.
823 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
824 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
825 http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
826 http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html