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?::
29 * add to a Tweaks chapter::
36 The main format of input for LilyPond are text files. By convention,
37 these files end with @code{.ly}.
41 * A single music expression::
42 * Multiple scores in a book::
43 * Extracting fragments of notation::
44 * Including LilyPond files::
46 * Different editions from one source::
51 @subsection File structure
53 A @code{.ly} file contains any number of toplevel expressions, where a
54 toplevel expression is one of the following
58 An output definition, such as @code{\paper}, @code{\midi}, and
59 @code{\layout}. Such a definition at the toplevel changes the default
60 settings for the block entered.
63 A direct scheme expression, such as
64 @code{#(set-default-paper-size "a7" 'landscape)} or
65 @code{#(ly:set-option 'point-and-click #f)}.
68 A @code{\header} block. This sets the global header block. This
69 is the block containing the definitions for book-wide settings, like
73 A @code{\score} block. This score will be collected with other
74 toplevel scores, and combined as a single @code{\book}.
76 This behavior can be changed by setting the variable
77 @code{toplevel-score-handler} at toplevel. The default handler is
78 defined in the init file @file{scm/@/lily@/.scm}.
80 The @code{\score} must begin with a music expression, and may
81 contain only one music expression.
84 A @code{\book} block logically combines multiple movements
85 (i.e., multiple @code{\score} blocks) in one document. If there are
86 a number of @code{\scores}, one output file will be created for
87 each @code{\book} block, in which all corresponding movements are
88 concatenated. The only reason to explicitly specify @code{\book} blocks
89 in a @code{.ly} file is if you wish multiple output files from a single
90 input file. One exception is within lilypond-book documents, where you
91 explicitly have to add a @code{\book} block if you want more than a
92 single @code{\score} or @code{\markup} in the same example.
94 This behavior can be changed by setting the variable
95 @code{toplevel-book-handler} at toplevel. The default handler is
96 defined in the init file @file{scm/@/lily@/.scm}.
99 A compound music expression, such as
104 This will add the piece in a @code{\score} and format it in a
105 single book together with all other toplevel @code{\score}s and music
106 expressions. In other words, a file containing only the above
107 music expression will be translated into
123 This behavior can be changed by setting the variable
124 @code{toplevel-music-handler} at toplevel. The default handler is
125 defined in the init file @file{scm/@/lily@/.scm}.
128 A markup text, a verse for example
131 2. The first line verse two.
135 Markup texts are rendered above, between or below the scores or music
136 expressions, wherever they appear.
146 This can be used later on in the file by entering @code{\foo}. The
147 name of an variable should have alphabetic characters only; no
148 numbers, underscores or dashes.
152 The following example shows three things that may be entered at
157 % movements are non-justified by default
169 At any point in a file, any of the following lexical instructions can
173 @item @code{\version}
174 @item @code{\include}
175 @item @code{\sourcefilename}
176 @item @code{\sourcefileline}
181 @node A single music expression
182 @subsection A single music expression
184 A @code{\score} must contain a single music expression. However,
185 this music expression may be of any size. Recall that music
186 expressions may be included inside other expressions to form
187 larger expressions. All of these examples are single music
188 expressions; note the curly braces @{ @} or angle brackets <<
189 >> at the beginning and ending of the music.
195 @lilypond[ragged-right,verbatim,quote]
202 @lilypond[ragged-right,verbatim,quote]
204 \new Staff { c'4 c' c' c' }
205 \new Staff { d'4 d' d' d' }
213 \new Staff @{ \flute @}
214 \new Staff @{ \oboe @}
217 \new Staff @{ \violinI @}
218 \new Staff @{ \violinII @}
225 @node Multiple scores in a book
226 @subsection Multiple scores in a book
229 @cindex movements, multiple
231 A document may contain multiple pieces of music and texts. Examples
232 of these are an etude book, or an orchestral part with multiple
233 movements. Each movement is entered with a @code{\score} block,
241 and texts are entered with a @code{\markup} block,
251 All the movements and texts which appear in the same @code{.ly} file
252 will normally be typeset in the form of a single output file.
266 However, if you want multiple output files from the same @code{.ly}
267 file, then you can add multiple @code{\book} blocks, where each such
268 @code{\book} block will result in a separate output. If you do not
269 specify any @code{\book} block in the file, LilyPond will implicitly
270 treat the full file as a single @code{\book} block, see @ref{File
271 structure}. One important exception is within lilypond-book documents,
272 where you explicitly have to add a @code{\book} block, otherwise only
273 the first @code{\score} or @code{\markup} will appear in the output.
275 The header for each piece of music can be put inside the @code{\score}
276 block. The @code{piece} name from the header will be printed before
277 each movement. The title for the entire book can be put inside the
278 @code{\book}, but if it is not present, the @code{\header} which is at
279 the top of the file is inserted.
283 title = "Eight miniatures"
284 composer = "Igor Stravinsky"
288 \header @{ piece = "Romanze" @}
291 ..text of second verse..
294 ..text of third verse..
298 \header @{ piece = "Menuetto" @}
302 @node Extracting fragments of notation
303 @subsection Extracting fragments of notation
305 It is possible to quote small fragments of a large score directly from
306 the output. This can be compared to clipping a piece of a paper score
309 This is done by definining the measures that need to be cut out
310 separately. For example, including the following definition
318 (make-rhythmic-location 5 1 2)
319 (make-rhythmic-location 7 3 4)))
324 will extract a fragment starting halfway the fifth measure, ending in
325 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
326 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
328 More clip regions can be defined by adding more pairs of
329 rhythmic-locations to the list.
331 In order to use this feature, LilyPond must be invoked with
332 @code{-dclip-systems}. The clips are output as EPS files, and are
333 converted to PDF and PNG if these formats are switched on as well.
335 For more information on output formats, see @rprogram{Invoking lilypond}.
339 Examples: @c @lsr{non-notation,clip-systems.ly}
342 @node Including LilyPond files
343 @subsection Including LilyPond files
346 @cindex including files
348 A large project may be split up into separate files. To refer to another
352 \include "otherfile.ly"
355 The line @code{\include "file.ly"} is equivalent to pasting the contents
356 of file.ly into the current file at the place where you have the
357 \include. For example, for a large project you might write separate files
358 for each instrument part and create a @q{full score} file which brings
359 together the individual instrument files.
361 The initialization of LilyPond is done in a number of files that are
362 included by default when you start the program, normally transparent to the
363 user. Run lilypond --verbose to see a list of paths and files that Lily
366 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
367 VERSION is in the form @q{2.6.1}) are on the path and available to
368 @code{\include}. Files in the
369 current working directory are available to \include, but a file of the same
370 name in LilyPond's installation takes precedence. Files are
371 available to \include from directories in the search path specified as an
372 option when invoking @code{lilypond --include=DIR} which adds DIR to the
375 The @code{\include} statement can use full path information, but with the Unix
376 convention @code{/} rather than the DOS/Windows @code{\}. For example,
377 if @file{stuff.ly} is located one directory higher than the current working
381 \include "../stuff.ly"
386 @subsection Text encoding
388 LilyPond uses the Pango library to format multi-lingual texts, and
389 does not perform any input-encoding conversions. This means that any
390 text, be it title, lyric text, or musical instruction containing
391 non-ASCII characters, must be utf-8. The easiest way to enter such text is
392 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
393 popular modern editors have utf-8 support, for example, vim, Emacs,
396 @c Currently not working
398 Depending on the fonts installed, the following fragment shows Hebrew
405 @li lypondfile[fontload]{utf-8.ly}
407 The @TeX{} backend does not handle encoding specially at all. Strings
408 in the input are put in the output as-is. Extents of text items in the
409 @TeX{} backend, are determined by reading a file created via the
410 @file{texstr} backend,
413 lilypond -dbackend=texstr input/les-nereides.ly
414 latex les-nereides.texstr
417 The last command produces @file{les-nereides.textmetrics}, which is
418 read when you execute
421 lilypond -dbackend=tex input/les-nereides.ly
424 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
425 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
426 interpreting non-ASCII strings.
430 To use a Unicode escape sequence, use
433 #(ly:export (ly:wide-char->utf-8 #x2014))
439 @c @lsr{text,utf-8.ly}
442 @node Different editions from one source
443 @subsection Different editions from one source
448 The @code{\tag} command marks music expressions with a name. These
449 tagged expressions can be filtered out later. With this mechanism it
450 is possible to make different versions of the same music source.
452 In the following example, we see two versions of a piece of music, one
453 for the full score, and one with cue notes for the instrumental part
469 The same can be applied to articulations, texts, etc.: they are
472 -\tag #@var{your-tag}
474 to an articulation, for example,
479 This defines a note with a conditional fingering indication.
482 @cindex removeWithTag
483 By applying the @code{\keepWithTag} and @code{\removeWithTag}
484 commands, tagged expressions can be filtered. For example,
488 \keepWithTag #'score @var{the music}
489 \keepWithTag #'part @var{the music}
494 @lilypondfile[ragged-right,quote]{tag-filter.ly}
496 The arguments of the @code{\tag} command should be a symbol
497 (such as @code{#'score} or @code{#'part}), followed by a
498 music expression. It is possible to put multiple tags on
499 a piece of music with multiple @code{\tag} entries,
502 \tag #'original-part \tag #'transposed-part @dots{}
508 Examples: @c @lsr{parts,tag@/-filter@/.ly}
513 Multiple rests are not merged if you create the score with both tagged
517 @node Common syntax issues TODO name?
518 @section Common syntax issues TODO name?
521 * Controlling direction and placement::
522 * Distances and measurements MAYBE MOVE::
526 @node Controlling direction and placement
527 @subsection Controlling direction and placement
531 By default, lilypnod does a pretty jazz'n job of picking
532 directions. But in some cases, it may be desirable to force a
546 Maybe rename section to "directions".
548 Also mention \override Foo #'direction = #'DOWN.
550 also mention the typical \fooDown, \fooNeutral predefined commands.
552 also mention that some directions are (without other tweaking)
553 always up or always down (like dynamics or fermata), while other
554 things can alternate between up or down based on the stem direction
555 (like slurs or accents).
558 @node Distances and measurements MAYBE MOVE
559 @subsection Distances and measurements MAYBE MOVE
561 DISCUSS after working on other sections.
563 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
566 @node When to add a -
567 @subsection When to add a -
569 One of these works, the other doesn't.
573 { c'\mp\fermata\accent-\markup { "forcefully"} }
574 % { c'\mp\fermata\accent\markup { "forcefully"} }
578 @node Other stuffs TODO move?
579 @section Other stuffs TODO move?
583 * Displaying LilyPond notation::
584 * Skipping corrected music::
585 * context list FIXME::
586 * another thing FIXME::
587 * Input modes FIXME::
590 @node Displaying LilyPond notation
591 @subsection Displaying LilyPond notation
593 @funindex \displayLilyMusic
594 Displaying a music expression in LilyPond notation can be
595 done using the music function @code{\displayLilyMusic}. For example,
599 \displayLilyMusic \transpose c a, @{ c e g a bes @}
609 By default, LilyPond will print these messages to the console along
610 with all the other messages. To split up these messages and save
611 the results of @code{\display@{STUFF@}}, redirect the output to
615 lilypond file.ly >display.txt
619 @node Skipping corrected music
620 @subsection Skipping corrected music
623 @funindex skipTypesetting
624 @funindex showLastLength
626 When entering or copying music, usually only the music near the end (where
628 are adding notes) is interesting to view and correct. To speed up
629 this correction process, it is possible to skip typesetting of all but
630 the last few measures. This is achieved by putting
633 showLastLength = R1*5
638 in your source file. This will render only the last 5 measures
639 (assuming 4/4 time signature) of every @code{\score} in the input
640 file. For longer pieces, rendering only a small part is often an order
641 of magnitude quicker than rendering it completely
643 Skipping parts of a score can be controlled in a more fine-grained
644 fashion with the property @code{Score.skipTypesetting}. When it is
645 set, no typesetting is performed at all.
647 This property is also used to control output to the MIDI file. Note that
648 it skips all events, including tempo and instrument changes. You have
651 @lilypond[quote,fragment,ragged-right,verbatim]
654 \set Score.skipTypesetting = ##t
656 \set Score.skipTypesetting = ##f
660 In polyphonic music, @code{Score.skipTypesetting} will affect all
661 voices and staves, saving even more time.
664 @node context list FIXME
665 @subsection context list FIXME
667 >> > > - list of contexts: my *danger unmaintainable*
668 >> > > alarm just went off. I'm
670 I knew it would... And leaving out some of them is perfectly fine
672 I do think that a list like this, with the main contexts and a
674 description of what they do (perhaps also with a note about what
676 behaviour is associated with each of them, but this may be
678 should be there, and then we could simply list the remaining ones
680 further explanation and with links to the IR.
683 The Master Of All Contexts
684 ==========================
687 This is the top level notation context. No other context
689 contain a Score context. This context handles the
690 administration of time signatures. It also makes sure that
691 items such as clefs, time signatures, and key-signatures
693 aligned across staves.
694 You cannot explicitly instantiate a Score context (since
696 not contained in any other context). It is instantiated
697 automatically when an output definition (a \score or
700 (it should also be made clear somewhere what the
701 difference is between
704 Top-level contexts: Staff containers
705 ====================================
707 Groups staves while adding a bracket on the left side,
708 grouping the staves together. The bar lines of the
710 staves are connected vertically. StaffGroup only consists
712 collection of staves, with a bracket in front and spanning
716 Identical to StaffGroup except that the contained staves
718 not connected vertically.
720 A group of staves, with a brace on the left side, grouping
722 staves together. The bar lines of the contained staves are
723 connected vertically.
725 Just like GrandStaff but with a forced distance between
727 staves, so cross staff beaming and slurring can be used.
729 Handles typesetting for percussion. Can contain DrumVoice
736 Handles clefs, bar lines, keys, accidentals. It can
740 Like Staff but for printing rhythms. Pitches are
741 ignored; the notes are printed on one line.
743 Context for generating tablature. By default lays the
745 expression out as a guitar tablature, printed on six
748 Same as Staff, except that it is accommodated for
749 typesetting a piece in gregorian style.
751 Same as Staff, except that it is accommodated for
752 typesetting a piece in mensural style.
754 Voice-level (bottom) contexts
755 =============================
756 What is generated by default here? The voice-level contexts
758 certain properties and start engravers.
761 Corresponds to a voice on a staff. This context handles
763 conversion of dynamic signs, stems, beams, super- and
764 subscripts, slurs, ties, and rests.
765 You have to instantiate this explicitly if you want to
767 multiple voices on the same staff.
770 Same as Voice, except that it is accommodated for
771 typesetting a piece in gregorian style.
773 Same as Voice, except that it is accommodated for
774 typesetting a piece in mensural style.
776 Corresponds to a voice with lyrics. Handles the printing
778 single line of lyrics.
781 A voice on a percussion staff.
785 Typesets chord names. This context is a `bottom' context;
787 cannot contain other contexts.
789 ------------------------------
790 Then the following, which I don't know what to do with:
793 * GregorianTranscriptionVoice
794 * GregorianTranscriptionStaff
797 Engraves fretboards from chords. Not easy... Not
801 * CueVoice Not documented
803 Hard coded entry point for LilyPond. Cannot be tuned.
805 Silently discards all musical information given to this
809 @node another thing FIXME
810 @subsection another thing FIXME
812 Another thing that is needed, is an overview of the various naming
815 scheme functions: lowercase-with-hyphens (incl. one-word
817 scheme functions: ly:plus-scheme-style
818 music events, music classes and music properties:
820 Grob interfaces: scheme-style
821 backend properties: scheme-style (but X and Y!)
822 contexts (and MusicExpressions and grobs): Capitalized or
824 context properties: lowercaseFollowedByCamelCase
826 Capitalized_followed_by_lowercase_and_with_underscores
828 Which of these are conventions and which are rules?
829 Which are rules of the underlying language, and which are
833 @node Input modes FIXME
834 @subsection Input modes FIXME
838 \notemode turns the front end of LilyPond into note mode
839 (which is the default parsing mode).
840 It's certainly useful in certain situations, for example if you
841 are in \lyricmode or \chordmode or ... and want to insert
842 something that only can be done with \notemode syntax.
845 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
846 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
847 http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
848 http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html
857 @node add to a Tweaks chapter
858 @section add to a Tweaks chapter
862 * Controlling visibility of objects::
866 @subsection Line styles
868 Valentin: write stuff here.
871 @node Controlling visibility of objects
872 @subsection Controlling visibility of objects
874 stuff about #'break-visibility