X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=ee400db07aa56a89ea7a4efbff59ea6bd58264d3;hb=d4e71555e7e093a4da32d92378f8f475fa0d6aaa;hp=018f69c99705d27c1e20fc94e79c4c2298d85035;hpb=16552264e655926b1c54825a2b0f8778be4235fe;p=lilypond.git diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 018f69c997..ee400db07a 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,3 +1,4 @@ + @c Note: @c @c A menu is needed before every deeper *section nesting of @nodes @@ -6,17 +7,10 @@ @c before saving changes -@ignore - TODO: - - fix all FIXMEs +@macro refbugs +@unnumberedsubsec Bugs - Rhythm staff (clef, x-notehead) - \partcombine: -> orchestral part-HOWTO. - markup text - postscript, scheme output? - (links to?) using/existance of ly2dvi, lilypond-book -@end ignore +@end macro @c .{Reference Manual} @@ -24,29 +18,32 @@ @node Reference Manual @chapter Reference Manual -This document describes GNU LilyPond and its input format. This document -has been revised for LilyPond 1.3.125 - +This document describes GNU LilyPond and its input format. The last +revision of this document was for LilyPond 1.3.141. @menu * Overview:: -* Music constructs:: -* Modifying music:: -* Repeats:: * Note entry:: -* Music notation:: +* Staff notation:: * Polyphony:: -* Spanners:: +* Beaming:: +* Expressive marks:: +* Ornaments:: +* Repeats:: +* Rhythmic music:: * Piano music:: * Lyrics:: * Chords:: +* Writing parts:: +* Custodes:: +* Tuning output:: * Page layout:: * Sound:: * Music entry:: -* Engravers:: +* Interpretation context:: * Syntactic details:: -* Unsorted:: +* Lexical details:: @end menu @c . {Overview} @@ -56,26 +53,23 @@ has been revised for LilyPond 1.3.125 The purpose of LilyPond is explained informally by the term `music typesetter'. This is not a fully correct name: not only does the -program print musical symbols, it also makes esthetic decisions. All -symbols and their placement is @emph{generated} from a high-level +program print musical symbols, it also makes esthetic decisions. +Symbols and their placements are @emph{generated} from a high-level musical description. In other words, LilyPond would be best described by `music compiler' or `music to notation compiler'. -Internally, LilyPond is written in a mixture of Scheme and C++. Most of -the algorithms and low-level routines are written in C++, but these low -level components are glued together using Scheme data -structures. LilyPond is linked to GUILE, GNU's Scheme library for -extension. +LilyPond is linked to GUILE, GNU's Scheme library for extension. The +Scheme library provides the glue that holds together the low-level +routines and separate modules general, which are C++. When lilypond is run to typeset sheet music, the following happens: - @itemize @bullet @item GUILE Initialization: various scheme files are read -@item parsing: first standard .ly initialization files are read, and -then the user @file{.ly} file is read. -@item interpretation: the music in the file is processed "in playing -order", i.e. in the same order as your eyes scan sheet music, and in the -same order that you hear the notes play. +@item parsing: first standard @code{ly} initialization files are read, and +then the user @file{ly} file is read. +@item interpretation: the music in the file is processed ``in playing +order'', i.e. the order that you use to read sheet music, or the +order in which notes are played. @item typesetting: in this step, the results of the interpretation, a typesetting @@ -84,13 +78,14 @@ specification, is solved. @item the visible results ("virtual ink") is written to the output file. @end itemize -These stages, involve data of a specific type: during parsing, -@strong{Music} objects are created. During the interpretation, -@strong{context} is constructed, and with this context af network of -@strong{graphical objects} (``grobs'') is created. The grobs contain -unknown variables, and the network forms a set of equations. After -solving the equations and filling in these variables, the printed output -(in the form of @strong{molecules}) is written to an output file. +During these stages different types of data play the the main role: +during parsing, @strong{Music} objects are created. During the +interpretation, @strong{context} is constructed, and with this context +af network of @strong{graphical objects} (``grobs'') is created. The +grobs contain unknown variables, and the network forms a set of +equations. After solving the equations and filling in these variables, +the printed output (in the form of @strong{molecules}) is written to an +output file. These threemanship of tasks (parsing, translating, typesetting) and data-structures (music, context, graphical objects) permeates the entire @@ -98,806 +93,582 @@ design of the program. This manual is ordered in terms of user tasks. With each concept will be explained to which of the three parts it belongs. -LilyPond input can be classified into three types: -@itemize @bullet - @item musical expressions: a musical expression is some combination of -rest, notes, lyrics - @item output definitions: recipes for translating those musical -expressions into performances (MIDI) or graphics (eg. PostScript). - @item declarations: by declaring and naming musical expressions, you -can enter and edit them in manageable chunks. -@end itemize +@c . {Note entry} +@node Note entry +@section Note entry +@cindex Note entry + +The most basic forms of music are notes. We discuss how you enter them +here. Notes on their own don't form valid input, but for the sake of +brevity we omit obligotary lint such as @code{\score} blocks and +@code{\paper} declarations. -@c . {Music constructs} -@node Music constructs -@section Music constructs -@cindex Music constructs @menu -* Music expressions:: -* Sequential music:: -* Simultaneous music:: -* Compound music expressions:: +* Pitches:: +* Defining pitch names:: +* Durations:: +* Notes:: +* Easy Notation note heads :: +* Tie:: +* Tuplets:: +* Rests:: +* Skip:: +* Note mode:: @end menu -@c . {Music expressions} -@node Music expressions -@subsection Music expressions - -@cindex music expressions - -Music in LilyPond is entered as a music expression. Notes, rests, lyric -syllables are music expressions (the atomic expressions), and you can -combine music expressions to form new ones. This example forms a -compound expressions out of the quarter @code{c} note and a @code{d} -note: - -@example -\sequential @{ c4 d4 @} -@end example +@c . {Pitches} +@node Pitches +@subsection Pitches -The meaning of this compound expression is to play the @code{c} -first, and then the @code{d} (as opposed to playing them -simultaneously, for instance). +@cindex Pitch names +@cindex Note specification +@cindex pitches +@cindex entering notes -@c . {Sequential music} -@node Sequential music -@subsection Sequential music -@cindex Sequential music -@cindex @code{\sequential} -@cindex sequential music +The verbose syntax for pitch specification is +@cindex @code{\pitch} @example - \sequential @code{@{} @var{musicexprlist} @code{@}} + \pitch @var{scmpitch} @end example -This means that list should be played or written in sequence, i.e., -the second after the first, the third after the second. The duration -of sequential music is the the sum of the durations of the elements. -There is a shorthand, which leaves out the keyword: +@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}. -@example -@cindex @code{<} -@cindex @code{>} +In Note and Chord mode, pitches may be designated by names. The default +names are the Dutch note names. The notes are specified by the letters +@code{a} through @code{g} (where the octave is formed by notes ranging +from @code{c}, to @code{b}). The pitch @code{c} is an octave below +middle C and the letters span the octave above that C. - @code{@{} @var{musicexprlist} @code{@}} -@end example +@cindex note names, Dutch -@c . {Simultaneous music} -@node Simultaneous music -@subsection Simultaneous music -@cindex Simultaneous music -@cindex @code{\simultaneous} +In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch +name. A flat is formed by adding @code{-es}. Double sharps and double +flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes} +and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but +both forms are accepted. -@example - \simultaneous @code{@{} @var{musicexprlist} @code{@}} -@end example +LilyPond has predefined sets of notenames for various other languages. +To use them, simply include the language specific init file. For +example: @code{\include "english.ly"}. The available language files and +the names they define are: -It constructs a music expression where all of its arguments start at -the same moment. The duration is the maximum of the durations of the -elements. The following shorthand is a common idiom: +@example + Note Names sharp flat +nederlands.ly c d e f g a bes b -is -es +english.ly c d e f g a bf b -s/-sharp -f/-flat +deutsch.ly c d e f g a b h -is -es +norsk.ly c d e f g a b h -iss/-is -ess/-es +svenska.ly c d e f g a b h -iss -ess +italiano.ly do re mi fa sol la sib si -d -b +catalan.ly do re mi fa sol la sib si -d/-s -b +@end example -@example - @code{<} @var{musicexprlist} @code{>} -@end example +@cindex @code{'} +@cindex @code{,} -If you try to use a chord as the first thing in your score, you might -get multiple staffs instead of a chord. -@lilypond[verbatim,center] - \score { - \notes - \paper { - linewidth = -1.; - } - } -@end lilypond -This happens because the chord is interpreted by a score context. -Each time a note is encountered a default Voice context (along with a -Staff context) is created. The solution is to explicitly instantiate -a Voice context: +The optional octave specification takes the form of a series of +single quote (`@code{'}') characters or a series of comma +(`@code{,}') characters. Each @code{'} raises the pitch by one +octave; each @code{,} lowers the pitch by an octave. -@lilypond[verbatim,center] - \score { - \notes\context Voice - \paper { - linewidth = -1.; - } - } +@lilypond[fragment,verbatim,center] + c' c'' es' g' as' gisis' ais' @end lilypond -@c . {Compound music expressions} -@node Compound music expressions -@subsection Compound music expressions - -@cindex Compound music expressions - -Music expressions are compound data structures. You can nest music -expressions any way you like. This simple example shows how three -chords can be expressed in two different ways: - -@lilypond[fragment,verbatim,center] - \notes \context Staff { - - < { a b c' } { c' d' e' } > - } +@c . {Defining pitch names} +@node Defining pitch names +@subsection Defining pitch names -@end lilypond +@cindex defining pitch names +@cindex pitch names, defining -@cindex @code{\context} -@cindex context selection +Note names and chord modifiers can be customised for nationalities. The +syntax is as follows. +@cindex @code{\pitchnames} +@cindex @code{\chordmodifiers} @example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} + \pitchnames @var{scheme-alist} + \chordmodifiers @var{scheme-alist} @end example -Interpret @var{musicexpr} within a context of type @var{contexttype}. -If the context does not exist, it will be created. The new context -can optionally be given a name. +See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for +specific examples how to do this. -@c . {Modifying music} -@node Modifying music -@section Modifying music -@cindex Modifying music -FIXME: more verbose titling: -music expressions? -Repeat? -Repeated music? -Repeating music expressions? +@c . {Durations} +@node Durations +@subsection Durations -@menu -* Transpose:: -* Apply:: -@end menu -@c . {Transpose} -@node Transpose -@subsection Transpose -@cindex Transpose -@cindex transposition of pitches -@cindex @code{\transpose} -A music expression can be transposed with @code{\transpose}. The syntax -is +@cindex duration +@cindex @code{\duration} + +The syntax for a verbose duration specification is @example - \transpose @var{pitch} @var{musicexpr} + \duration @var{scmduration} @end example +Here, @var{scmduration} is a Scheme object of type Duration. See +@ref{Duration} for more information. -This means that middle C in @var{musicexpr} is transposed to -@var{pitch}. -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose cis'} or @code{\transpose des'} will transpose up half -a tone. The first version will print sharps and the second version -will print flats. +In Note, Chord, and Lyrics mode, durations may be designated by numbers +and dots: durations are entered as their reciprocal values. For notes +longer than a whole note, use identifiers. @quotation -@lilypond[fragment,verbatim] -\context Staff { - \clef "F"; - { \key e \major; c d e f } - \clef "G"; - \transpose des'' { \key e \major; c d e f } - \transpose cis'' { \key e \major; c d e f } -} +@example +c'\longa c'\breve +c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 +r\longa r\breve +r1 r2 r4 r8 r16 r32 r64 r64 +@end example + + +@lilypond[] +\score { + \notes \relative c'' { + a\longa a\breve \autoBeamOff + a1 a2 a4 a8 a16 a32 a64 a64 + r\longa r\breve + r1 r2 r4 r8 r16 r32 r64 r64 + } + \paper { + \translator { + \StaffContext + \remove "Clef_engraver"; + \remove "Staff_symbol_engraver"; + \remove "Time_signature_engraver"; + \consists "Pitch_squash_engraver"; + } + } +} @end lilypond @end quotation -If you want to use both @code{\transpose} and @code{\relative}, then -you must use @code{\transpose} first. @code{\relative} will have no -effect music that appears inside a @code{\transpose}. +As you can see, the longa is not printed. To get a longa note head, you +have to use a mensural note heads. This is done accomplished by setting +the @code{style} property of the NoteHead grob to @code{mensural}. -@c . {Apply} -@node Apply -@subsection Apply -@cindex Apply -Apply allows a Scheme-function to operate directly on the internal -representation of music. -@example - \apply #@var{func} @var{music} -@end example -The function takes two arguments, being a function and an musical -argument for that function. The function should return a music -expression. +If the duration is omitted then it is set to the previous duration +entered. At the start of parsing a quarter note is assumed. The +duration can be followed by a dot (`@code{.}') to obtain dotted note +lengths. +@cindex @code{.} -This example replaces the text string of a script. It also shows a dump -of the music it processes. -@lilypond[verbatim] -#(define (testfunc x) - (if (equal? (ly-get-mus-property x 'text) "foo") - (ly-set-mus-property x 'text "bar")) - ;; recurse - (ly-set-mus-property x 'elements - (map testfunc (ly-get-mus-property x 'elements))) - (display x) - x -) -\score { \notes - \apply #testfunc { c4_"foo" } -} +@lilypond[fragment,verbatim,center] + a'4. b'4.. c'8. @end lilypond +@cindex @code{r} +@cindex @code{s} -For more information on what is possible, see the @ref{Tricks} and the -automatically generated documentation. +You can alter the length of duration by appending +`@code{*}@var{fraction}'. This will not affect the appearance of the +notes or rests produced. +@c . {Notes} +@node Notes +@subsection Notes +A note specification has the form -@c . {Repeat} -@node Repeats -@section Repeats +@example + @var{pitch}[@var{octavespec}][!][?][@var{duration}] +@end example +LilyPond will determine what accidentals to typeset depending on the key +and context. The alteration refers to what note is heard, not to whether +an accidental is printed. A reminder accidental +@cindex reminder accidental +@cindex @code{?} +can be forced by adding an exclamation mark @code{!} after the pitch. A +cautionary accidental, +@cindex cautionary accidental +i.e., an accidental within parentheses can be obtained by adding the +question mark `@code{?}' after the pitch. -@cindex repeats -@cindex @code{\repeat} +@lilypond[fragment,verbatim,center] + cis' d' e' cis' c'? d' e' c'! +@end lilypond -In order to specify repeats, use the @code{\repeat} -keyword. Since repeats look and sound differently when played or -printed, there are a few different variants of repeats. -@table @asis -@item unfolded -Repeated music is fully written (played) out. Useful for MIDI -output. +@node Easy Notation note heads +@subsection Easy Notation note heads -@item volta -This is the normal notation: Repeats are not written out, but -alternative endings (voltas) are printed, left to right. +@cindex easy notation +@cindex Hal Leonard -@item folded -Alternative endings are written stacked. Which is unfortunately not -practical for anything right now. +A entirely different type of note head is the "easyplay" note head: a +note head that includes a note name. It is used in some publications by +Hal-Leonard Inc. music publishers. -@item tremolo -Make tremolo beams. -@end table +@lilypond[singleline,verbatim] +\include "paper26.ly" +\score { + \notes { c'2 e'4 f' | g'1 } + \paper { \translator { \EasyNotation } } +} +@end lilypond -@menu -* Repeat syntax:: -* Manual repeat commands:: -* Tremolo repeats:: -* Tremolo subdivision:: -@end menu +Note that @code{EasyNotation} overrides a @code{Score} context. You +probably will want to print it with magnification to make it better +readable. -@node Repeat syntax -@subsection Repeat syntax +@cindex Xdvi +@cindex ghostscript -The syntax for repeats is +If you view the result with Xdvi, then staff lines will show through the +letters. Printing the postscript file obtained either by using dvips or +the @code{-f ps} option of lilypond will produce the desired result. -@example - \repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example -If you have alternative endings, you may add +@node Tie +@subsection Tie -@cindex @code{\alternative} -@example - \alternative @code{@{} @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @code{@}} -@end example +@cindex Tie +@cindex ties +@cindex @code{~} -where each @var{alternative} is a Music expression. +A tie connects two adjacent note heads of the same pitch. When used +with chords, it connects all of the note heads whose pitches match. +Ties are indicated using the tilde symbol `@code{~}'. +If you try to tie together chords which have no common pitches, a +warning message will appear and no ties will be created. -Normal notation repeats are used like this: +@lilypond[fragment,verbatim,center] + e' ~ e' ~ +@end lilypond -@quotation +If you dislike the amount of ties created for a chord, you set +@code{Voice.sparseTies} to true, resulting in a smaller number of +ties: +@lilypond[fragment,verbatim,center] + \property Voice.sparseTies = ##t + ~ +@end lilypond -@lilypond[fragment,verbatim] - c'1 - \repeat volta 2 { c'4 d' e' f' } - \repeat volta 2 { f' e' d' c' } +In its meaning a tie is just a way of extending a note duration, similar +to the augmentation dot: the following example are three ways of notating +exactly the same concept. +@lilypond[fragment, singleline] +c'2 c'4 ~ c'4 @end lilypond -@end quotation -With alternative endings: +@refbugs -@quotation +At present, the tie is implemented as a separate thing, temporally +located in between the notes. There is also no way to convert +between tied notes, dotted notes and plain notes. -@lilypond[fragment,verbatim] - c'1 - \repeat volta 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } -@end lilypond -@end quotation +Tieing only a subset of the note heads of a chord is not supported in a +simple way. It can be achieved by moving the tie-engraver into Thread +context and turning off ties per Thread. -Folded repeats look like this:@footnote{Folded repeats offer little -more over simultaneous music. However, it is to be expected that -more functionality -- especially for the MIDI backend -- will be -implemented at some point in the future.} -@quotation +@node Tuplets +@subsection Tuplets -@lilypond[fragment,verbatim] - c'1 - \repeat fold 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } +@cindex tuplets +@cindex triplets +@cindex @code{\times} -@end lilypond -@end quotation +Tuplets are made out of a music expression by multiplying their duration +with a fraction. +@cindex @code{\times} +@example + \times @var{fraction} @var{musicexpr} +@end example -If you don't give enough alternatives for all of the repeats, then -the first alternative is assumed to be repeated often enough to equal -the specified number of repeats. +The duration of @var{musicexpr} will be multiplied by the fraction. +In print, the fraction's denominator will be printed over the notes, +optionally with a bracket. The most common tuplet is the triplet in +which 3 notes have the length of 2, so the notes are 2/3 of +their written length: -@quotation -@lilypond[fragment,verbatim] -\context Staff { - \relative c' { - \partial 4; - \repeat volta 3 { e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } { a | a a a a | b2. } } - } -} +@lilypond[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond + +The property @code{tupletSpannerDuration} specifies how long brackets +should last. With this, you can make lots of tuplets while typing +@code{\times} only once. This saves typing work when you must make lots +of tuplets. +@lilypond[fragment, relative, singleline, verbatim] +\property Voice.tupletSpannerDuration = #(make-moment 1 4) +\times 2/3 { c''8 c c c c c } @end lilypond -@end quotation +@c . {Rests} +@node Rests +@subsection Rests +@cindex Rests -As you can see, LilyPond doesn't remember the timing information, nor -are slurs or ties repeated. We hope to fix this after 1.4. +Rests are entered like notes, with note name `@code{r}'. -It is possible to nest @code{\repeat}, although it probably is only -meaningful for nested repeats. -@node Manual repeat commands -@subsection Manual repeat commands +@c . {Skip} +@node Skip +@subsection Skip +@cindex Skip -@cindex @code{repeatCommands} -The property @code{repeatCommands} can be used to control the layout of -repeats. Its value is a Scheme list of repeat commands, where each repeat -command can be +@example + \skip @var{duration} @code{;} + s@var{duration} +@end example +@cindex @code{\skip} -@table @code -@item 'start-repeat - Print a |: bar line -@item 'stop-repeat - Print a :| bar line -@item (volta . #f) -@item (volta . @var{text}) - Print a volta bracket saying @var{text}. -@end table +Skips the amount of time specified by @var{duration}. If no other music +is played, a gap will be left for the skipped time with no notes +printed. The shorthand is only available in Note and Chord mode. -@lilypond[verbatim, fragment] - c''4 - \property Score.repeatCommands = #'((volta "93") end-repeat) - c4 c4 - \property Score.repeatCommands = #'((volta #f)) - c4 c4 -@end lilypond -@node Tremolo repeats -@subsection Tremolo repeats -@cindex tremolo beams +@node Note mode +@subsection Note mode -To place tremolo marks between notes, use @code{\repeat} with tremolo -style. -@lilypond[verbatim,center] -\score { - \context Voice \notes\relative c' { - \repeat "tremolo" 8 { c16 d16 } - \repeat "tremolo" 4 { c16 d16 } - \repeat "tremolo" 2 { c16 d16 } - \repeat "tremolo" 4 c16 - } - \paper { - linewidth = 40*\staffspace; - } -} -@end lilypond -@node Tremolo subdivision -@subsection Tremolo subdivision -@cindex tremolo marks -@cindex @code{tremoloFlags} -Tremolo marks can be printed on a single note by adding -`@code{:}[@var{length}]' after the note. The length must be at least 8. -A @var{length} value of 8 gives one line across the note stem. If the -length is omitted, then the last value is used, or the value of the -@code{tremoloFlags} property if there was no last value. +@cindex note mode +@cindex @code{\notes} -@lilypond[verbatim,fragment,center] - c'2:8 c':32 -@end lilypond +Note mode is the lexical mode generally used for inputting notes. The +syntax is +@example +\notes @var{expr} +@end example -Tremolos in this style do not carry over into the MIDI output. +This instructs the tokenizer to interpret @var{expr} in note mode. If a +a sequence of alfabetical characters, like @code{foobar}, LilyPond first +checks if @code{foobar} is a pitch name. If it is not a pitch name, +then it is treated as a string. -Using this mechanism pays off when you entering many tremolos, since the -default argument saves a lot of typing. +Numbers and dots indicate durations, so you can enter floating point +numbers in this mode. -@c . {Note entry} -@node Note entry -@section Note entry -@cindex Note entry +@node Staff notation +@section Staff notation + +@cindex Staff notation @menu -* Notes mode:: -* Pitches:: -* Defining pitch names:: -* Durations:: -* Notes:: -* Rests:: -* Multi measure rests:: -* Skip:: +* Key signature:: +* Clef:: +* Time signature:: +* Unmetered music:: +* Bar lines:: @end menu -@c . {Notes mode} -@node Notes mode -@subsection Notes mode +@c . {Key} +@node Key signature +@subsection Key signature +@cindex Key -@cindex note mode +@cindex @code{\key} -@cindex @code{\notes} -Note mode is introduced by the keyword -@code{\notes}. In Note mode, words can only -contain alphabetic characters. If @code{word} is encountered, -LilyPond first checks for a notename of @code{word}. If no -notename is found, then @code{word} is treated as a string. +Changing the key signature is done with the @code{\key} command. +@example + @code{\key} @var{pitch} @var{type} @code{;} +@end example + +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} -Since combinations of numbers and dots are used for indicating -durations, it is not possible to enter real numbers in this mode. +Here, @var{type} should be @code{\major} or @code{\minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. The second +argument is optional; the default is major keys. The @var{\context} +argument can also be given as an integer, which tells the number of +semitones that should be added to the pitch given in the subsequent +@code{\key} commands to get the corresponding major key, e.g., +@code{\minor} is defined as 3. The standard mode names @code{\ionian}, +@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, +@code{\phrygian}, and @code{\dorian} are also defined. -@cindex Notes mode +This command sets context property @code{Staff.keySignature}. -@c . {Pitches} -@node Pitches -@subsection Pitches +@cindex @code{keySignature} -@cindex Pitch names -@cindex Note specification -@cindex pitches -@cindex entering notes +@c . {Clef} +@node Clef +@subsection Clef +@cindex @code{\clef} +@example + \clef @var{clefname} @code{;} +@end example -The verbose syntax for pitch specification is +Shortcut for -@cindex @code{\pitch} @example - \pitch @var{scmpitch} + \property Staff.clefGlyph = @var{glyph associated with clefname} + \property Staff.clefPosition = @var{clef Y-position for clefname} + \property Staff.clefOctavation = @var{extra pitch of clefname} @end example -@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}. +Supported clef-names include -In Note and Chord mode, pitches may be designated by names. The default -names are the Dutch note names. The notes are specified by the letters -@code{c} through @code{b}, where @code{c} is an octave below middle C -and the letters span the octave above that C. In Dutch, -@cindex note names, Dutch -a sharp is formed by adding @code{-is} to the end of a pitch name. A -flat is formed by adding @code{-es}. Double sharps and double flats are -obtained by adding @code{-isis} or @code{-eses}. @code{aes} and -@code{ees} are contracted to @code{as} and @code{es} in Dutch, but both -forms will be accepted. +@itemize @bullet +@item treble, violin, G, G2: G clef on 2nd line +@item french: G clef on 1st line +@item soprano: C clef on 1st line +@item mezzosoprano: C clef on 2nd line +@item alto: C clef on 3rd line +@item tenor: C clef on 4th line +@item baritone: C clef on 5th line +@item varbaritone: F clef on 3rd line +@item bass, F: F clef on 4th line +@item subbass: F clef on 5th line +@item percussion: percussion clef +@end itemize -LilyPond has predefined sets of notenames for various other languages. -To use them, simply include the language specific init file. For -example: @code{\include "english.ly"}. The available language files and -the names they define are: +Supported associated glyphs (for @code{Staff.clefGlyph}) are: -@example - Note Names sharp flat -nederlands.ly c d e f g a bes b -is -es -english.ly c d e f g a bf b -s/-sharp -f/-flat -deutsch.ly c d e f g a b h -is -es -norsk.ly c d e f g a b h -iss/-is -ess/-es -svenska.ly c d e f g a b h -iss -ess -italiano.ly do re mi fa sol la sib si -d -b -catalan.ly do re mi fa sol la sib si -d/-s -b -@end example +@itemize @bullet +@item clefs-C: modern style C clef +@item clefs-F: modern style F clef +@item clefs-G: modern style G clef +@item clefs-vaticana_do: Editio Vaticana style do clef +@item clefs-vaticana_fa: Editio Vaticana style fa clef +@item clefs-medicaea_do: Editio Medicaea style do clef +@item clefs-medicaea_fa: Editio Medicaea style fa clef +@item clefs-mensural1_c: modern style mensural C clef +@item clefs-mensural2_c: historic style small mensural C clef +@item clefs-mensural3_c: historic style big mensural C clef +@item clefs-mensural1_f: historic style traditional mensural F clef +@item clefs-mensural2_f: historic style new mensural F clef +@item clefs-mensural_g: historic style mensural G clef +@item clefs-hufnagel_do: historic style hufnagel do clef +@item clefs-hufnagel_fa: historic style hufnagel fa clef +@item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef +@item clefs-percussion: modern style percussion clef +@end itemize -@cindex @code{'} -@cindex @code{,} +@emph{Modern style} means ``as is typeset in current editions.'' +@emph{Historic style} means ``as was typeset or written in contemporary +historic editions''. @emph{Editio XXX style} means ``as is/was printed in +Editio XXX.'' +@cindex Vaticana, Editio +@cindex Medicaea, Editio +@cindex hufnagel clefs +@c . {Time signature} +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} -The optional octave specification takes the form of a series of -single quote (`@code{'}') characters or a series of comma -(`@code{,}') characters. Each @code{'} raises the pitch by one -octave; each @code{,} lowers the pitch by an octave. +The time signature is changed by the @code{\time} command. Syntax: +@example + \time @var{numerator}@code{/}@var{denominator} @code{;} +@end example +Internally, this is a shortcut for doing +@example + \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator}) +@end example -@lilypond[fragment,verbatim,center] - c' d' e' f' g' a' b' c'' -@end lilypond +[TODO: discuss options for layout] -@lilypond[fragment,verbatim,center] - cis' dis' eis' fis' gis' ais' bis' -@end lilypond +@c . {Partial} +@subsection Partial +@cindex Partial +@cindex anacrusis +@cindex upstep +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} -@lilypond[fragment,verbatim,center] - ces' des' es' fes' ges' as' bes' -@end lilypond +Partial measures are entered using the @code{\partial} command: +@example + \partial @var{duration} @code{;} +@end example -@lilypond[fragment,verbatim,center] - cisis' eisis' gisis' aisis' beses' -@end lilypond - -@lilypond[fragment,verbatim,center] - ceses' eses' geses' ases' beses' -@end lilypond - - -@c . {Defining pitch names} -@node Defining pitch names -@subsection Defining pitch names - -@cindex defining pitch names -@cindex pitch names, defining - -Note names and chord modifiers can be customised for nationalities. The -syntax is as follows. - -@cindex @code{\pitchnames} -@cindex @code{\chordmodifiers} -@example - \pitchnames @var{scheme-alist} - \chordmodifiers @var{scheme-alist} -@end example - -See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for -specific examples how to do this. Some national note names have been -provided, among others: Norwegian, Swedish, German, Italian, Catalan, -French, Dutch and English. - - -@c . {Durations} -@node Durations -@subsection Durations - - -@cindex duration -@cindex @code{\duration} - -The syntax for an verbose duration specification is -@example - \duration @var{scmduration} -@end example - -In Note, Chord, and Lyrics mode, durations may be designated by numbers -and dots: durations are entered as their reciprocal values. For notes -longer than a whole note, use identifiers. - -@quotation - -@example -c'\longa c'\breve -c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 -r\longa r\breve -r1 r2 r4 r8 r16 r32 r64 r64 -@end example - - -@lilypond[] -\score { - \notes \relative c'' { - a\longa a\breve \autoBeamOff - a1 a2 a4 a8 a16 a32 a64 a64 - r\longa r\breve - r1 r2 r4 r8 r16 r32 r64 r64 - } - \paper { - \translator { - \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - \remove "Time_signature_engraver"; - \consists "Pitch_squash_engraver"; - } - } -} -@end lilypond -@end quotation - -As you can see, the longa is not printed. To get a longa note head, you -have to use a different style of note heads. See [TODO]. - -If the duration is omitted then it is set equal to the previous duration -entered. At the start of parsing there is no previous duration, so then -a quarter note is assumed. The duration can be followed by a dot -(`@code{.}') to obtain dotted note lengths. -@cindex @code{.} - -@lilypond[fragment,verbatim,center] - a'4. b'4. -@end lilypond -@cindex @code{r} -@cindex @code{s} - -You can alter the length of duration by writing `@code{*}@var{fraction}' -after it. This will not affect the appearance of note heads or rests. - -@c . {Notes} -@node Notes -@subsection Notes - -A note specification has the form +Internally, this is a shortcut for @example - @var{pitch}[@var{octavespec}][!][?][@var{duration}] + \property Score.measurePosition = -@var{length of duration} @end example +@cindex @code{|} -LilyPond will determine what accidentals to typeset depending on the key -and context, so alteration refer to what note is heard, not to whether -accidentals are printed. A reminder accidental -@cindex reminder accidental -@cindex @code{?} -can be forced by adding an exclamation mark @code{!} after the pitch. -A cautionary accidental, -@cindex cautionary accidental - -i.e., an accidental within parentheses can be obtained by adding the -question mark `@code{?}' after the pitch. - -@lilypond[fragment,verbatim,center] - cis' d' e' cis' c'? d' e' c'! -@end lilypond - - - - -@c . {Rests} -@node Rests -@subsection Rests -@cindex Rests - -Rests are entered like notes, with note name `@code{r}'. -There is also a note name -`@code{s}', which produces a space of the specified -duration. - - -@c . {Multi measure rests} -@node Multi measure rests -@subsection Multi measure rests -@cindex Multi measure rests - -@cindex @code{R} - -[todo: moveme to orchestral-part section?] +@node Unmetered music +@subsection Unmetered music -Multi measure rests are entered using `@code{R}'. It is specifically -meant for entering parts: the rest can expand to fill a score with -rests, or it can be printed as a single multimeasure rest This expansion -is controlled by the property @code{Score.skipBars}. If this is set to true, -Lily will not expand empty measures, and the appropriate number is added -automatically. +Bar lines and bar numbers are calculated automatically. For unmetered +music (e.g. cadenzas), this is not desirable. The property +@code{Score.timing} can be used to switch off this automatic timing -@lilypond[fragment,verbatim] - \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 +@lilypond[fragment,relative,singleline,verbatim] +c'2. +\property Score.timing = ##f +c4 c4 c4 +\property Score.timing = ##t +c4 c4 c4 @end lilypond -Currently, there is no way to condense multiple rests into a single -multimeasure rest. - -@cindex condensing rests - -@c . {Skip} -@node Skip -@subsection Skip -@cindex Skip - - -@example - \skip @var{duration} @code{;} -@end example -@cindex @code{\skip} - -Skips the amount of time specified by @var{duration}. If no other -music is played, a gap will be left for the skipped time with no -notes printed. It works in Note Mode or Lyrics Mode. In Note mode, -this has the same effect as the spacer rest. - - - -@c . {Music notation} -@node Music notation -@section Music notation -@cindex Music notation -@menu -* Key:: -* Time signature:: -@end menu - -@c . {Key} -@node Key -@subsection Key -@cindex Key - -@cindex @code{\key} - -@example - @code{\key} @var{pitch} @var{type} @code{;} -@end example -@cindex @code{\minor} -@cindex @code{\major} -@cindex @code{\minor} -@cindex @code{\ionian} -@cindex @code{\locrian} -@cindex @code{\aeolian} -@cindex @code{\mixolydian} -@cindex @code{\lydian} -@cindex @code{\phrygian} -@cindex @code{\dorian} - -Change the key signature. @var{type} should be @code{\major} or -@code{\minor} to get @var{pitch}-major or @var{pitch}-minor, -respectively. The second argument is optional; the default is major -keys. The @var{\context} argument can also be given as an integer, -which tells the number of semitones that should be added to the pitch -given in the subsequent @code{\key} commands to get the corresponding -major key, e.g., @code{\minor} is defined as 3. The standard mode names -@code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, -@code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined. - - -@c . {Clef changes} -@subsubsection Clef changes -@cindex @code{\clef} -@example - \clef @var{clefname} @code{;} -@end example - -Short-cut for - -@example - \property Staff.clefGlyph = @var{symbol associated with clefname} - \property Staff.clefPosition = @var{clef Y-position for clefname} - \property Staff.clefOctavation = @var{extra pitch of clefname} -@end example +The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used to +achieve the same effect. -Supported clef-names include -[todo] +@c . {Bar lines} +@node Bar lines +@subsection Bar lines +@cindex Bar lines -@c . {Time signature} -@node Time signature -@subsection Time signature -@cindex Time signature -@cindex meter -@cindex @code{\time} +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars @example - \time @var{numerator}@code{/}@var{denominator} @code{;} + \bar @var{bartype}; @end example -A short-cut for doing +This is a shortcut for doing @example - \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator}) + \property Score.whichBar = @var{bartype} @end example -See the documentation of @code{timeSignatureFraction} - +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeats}, and the documentation of @code{whichBar} in the generated +documentation. -@c . {Partial} -@subsubsection Partial -@cindex Partial -@cindex anacrusis -@cindex upstep -@cindex partial measure -@cindex measure, partial -@cindex shorten measures -@cindex @code{\partial} -@example - \partial @var{duration} @code{;} -@end example -Short cut for +@cindex Bar_line_engraver +@cindex whichBar +@cindex repeatCommands +@cindex defaultBarType -@example - \property Score.measurePosition = @var{length of duration} -@end example -@cindex @code{|} +Bar lines are created by the @code{Bar_line_engraver}. That engraver examines +@code{whichBar} at every moment. Whenever it is set to a string, it will +create a bar with that type. @code{whichBar} is usually set +automatically: at the start of a measure it is set to +@code{defaultBarType}. The contents of @code{repeatCommands} is used to +override default measure bars. -See the documentation of @code{measurePosition}. +@code{whichBar} can also be set directly, using @code{\property} or +@code{\bar ; }. These settings take precedence over automatic @code{whichBar} +settings. @c . {Polyphony} @@ -905,8 +676,8 @@ See the documentation of @code{measurePosition}. @section Polyphony @cindex Polyphony -[todo : collisiosn, rest-collisinos, voiceX identifiers, how to -which contexts to instantiate.] +[TODO: collisions, rest-collisinos, voiceX identifiers, how to +which contexts to instantiate. some small examples? ] @table @code @@ -920,101 +691,164 @@ which contexts to instantiate.] shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn} set different shift values. -@cindex @code{\stemBoth} +@cindex @code{\stemBoth} @item @code{\stemBoth} - Allow stems, beams, and slurs to point either upwards or + Allow stems and beams to point either upwards or downwards, decided automatically by LilyPond. @cindex @code{\stemDown} @item @code{\stemDown} - Force stems, beams, and slurs to point down. + Force stems and beams to point down. @cindex @code{\stemUp} @item @code{\stemUp} - Force stems, beams and slurs to point up. + Force stems and beams to point up. @end table -@c . {Spanners} -@node Spanners -@section Spanners -@cindex Spanners - -@menu -* Beam:: -* Slur :: -* Ornaments:: -* Grace notes:: -* Bar check:: -@end menu - +@cindex @code{\slurBoth} +@cindex @code{\slurDown} +@cindex @code{\slurUp} +Similarly, for slurs use +@code{\slurBoth}, +@code{\slurDown}, +@code{\slurUp}. + +@cindex @code{\tieBoth} +@cindex @code{\tieDown} +@cindex @code{\tieUp} +For ties use +@code{\tieBoth}, +@code{\tieDown}, +@code{\tieUp}. + +@cindex @code{\dynacmicBoth} +@cindex @code{\dynamicDown} +@cindex @code{\dynamicUp} +For dynamics use +@code{\dynamicBoth}, +@code{\dynamicDown}, +@code{\dynamicUp}. + +@c text scripts? articulation scripts? fingering? + +@cindex @code{\voiceOne} +@cindex @code{\voiceTwo} +@cindex @code{\voiceThree} +@cindex @code{\voiceFour} +@cindex @code{\oneVoice} +@cindex @code{\shiftOn} +@cindex @code{\shiftOff} + +If two voices sharing one staff have the same stem directions, their +note heads may collide. You can shift the note heads of one voice by +setting @code{\shiftOn}. This can be undone by setting +@code{\shiftOff}. + +For simple polyphonic music, shorthands are available that combine +directions and shift settings: @code{\voiceOne}, @code{\voiceTwo}, +@code{\voiceThree}, @code{\voiceFour} and @code{\oneVoice}. + + +@node Beaming +@section Beaming + +Beams are used to group short notes into chunks that are aligned with +the metrum. LilyPond guesses where beams should be inserted, but if +you're not satisfied with the automatic beaming, you can either instruct +lilypond which patterns to beam automatically. In specific cases, you +can also specify explicitly what to beam and what not. -@c . {Beam} -@node Beam -@subsection Beams - -@cindex beams - @c . {Automatic beams} -@subsubsection Automatic beams - - -@cindex automatic beam generation -@cindex autobeam -@cindex @code{Voice.noAutoBeaming} - -LilyPond will group flagged notes and generate beams autmatically, where -appropriate. - -This feature can be disabled by setting the @code{Voice.noAutoBeaming} -property to true, which you may find necessary for the melody that goes -with lyrics, eg. Automatic beaming can easily be overridden for -specific cases by specifying explicit beams. This is discussed in the -next subsubsection. - - +@subsection Automatic beams @cindex @code{Voice.autoBeamSettings} @cindex @code{(end * * * *)} @cindex @code{(begin * * * *)} A large number of Voice properties are used to decide how to generate -beams. Their default values appear in @file{scm/auto-beam.scm}. In -general, beams can begin anywhere, but their ending location is -significant. Beams can end on a beat, or at durations specified by the -properties in @code{Voice.autoBeamSettings}. To end beams every quarter -note, for example, you could set the property @code{(end * * * *)} to -@code{(make-moment 1 4)}. To end beams at every three eighth notes you -would set it to @code{(make-moment 1 8)}. The same syntax can be used -to specify beam starting points using @code{(begin * * * *)}, eg: -@quotation +beams. Their default values appear in @file{scm/auto-beam.scm}. + +By default, automatic beams can start on any note@footnote{In exotic +time signatures such as 1/8 and 1/16 this is not true} but can only end +in a few positions within the measure: they can end on a beat, or at +durations specified by the properties in +@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings} +are defined in @file{scm/auto-beam.scm}. + +The syntax for changing the value @code{autoBeamSettings} is set using +@code{\override} and unset using @code{\revert}: +@example +\property Voice.autoBeamSettings \override #'(@var{BE} @var{N} @var{M} @var{P} @var{Q}) = @var{dur} +\property Voice.autoBeamSettings \revert #'(@var{BE} @var{N} @var{M} @var{P} @var{Q}) +@end example +Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines +whether the rule applies to begin or end-points. The quantity +@var{N}/@var{M} refers to a time signature (@code{* *} may be entered to +designate all time signatures), @var{P}/@var{Q} refers to the length of +the beamed notes (@code{* *} designate notes of any length). + +If you want automatic beams to end on every quarter note, you can +use the following: @example \property Voice.autoBeamSettings \override #'(end * * * *) = #(make-moment 1 4) +@end example +The duration a quarter note is 1/4 of a whole note. It is entered as +@code{(make-moment 1 4)}. + +The same syntax can be used to specify beam starting points. In this +example, you automatic beams can only end on a dotted quarter note. +@example \property Voice.autoBeamSettings \override - #'(begin * * * *) = #(make-moment 1 8) + #'(begin * * * *) = #(make-moment 3 8) @end example -@end quotation +In 4/4 time signature, this means that automatic beams could end only on +3/8 and on the fourth beat of the measure (after 3/4, that is 2 times +3/8 has passed within the measure). + +You can also restrict rules to specific time signatures. A rule that +should only be applied in @var{N}/@var{M} time signature is formed by +replacing the first asterisks by @var{N} and @var{M}. For example, a +rule for 6/8 time exclusively looks like +@example +\property Voice.autoBeamSettings \override + #'(begin 6 8 * *) = ... +@end example + +If you want a rule to apply to certain types of beams, you can use the +second pair of asterisks. Beams are classified according to the shortest +note they contain. For a beam ending rule that only applies to beams +with 32nd notes (and no shorter notes), you would use @code{(end * * 1 +32)}. -To allow different settings for different time signatures, instead of -the first two asterisks @code{* *} you can specify a time signature; use -@code{(end N M * *)} to restrict the definition to -`@var{N}@code{/}@var{M}' time. For example, to specify beams ending -only for 6/8 time you would use the property @code{(end 6 8 * *)}. +[say something about irregular meters. eg 5/8 = 2+3/8, 3+2/8] + +Automatic beams can not be put on the last note in a score. + +@cindex automatic beam generation +@cindex autobeam +@cindex @code{Voice.noAutoBeaming} -To allow different endings for notes of different durations, instead of -th last two asterisks you can specify a duration; use @code{(end * * N -M)} to restrict the definition to beams that contain notes of -`@var{N}@code{/}@var{M}' duration. +Automatic beaming is on by default, but it can switched off by setting +@code{Voice.noAutoBeaming} to true. You you may find this necessary for +a melody that goes with lyrics. -For example, to specify beam endings for beams that contain 32nd notes, -you would use @code{(end * * 1 32)}. +@refbugs +It is not possible to specify beaming for beams with mixed durations, +that differs from the beaming of all separate durations, ie, you'll +have to specify manual beams to get: +@lilypond[fragment,singleline,relative] + \property Voice.autoBeamSettings + \override #'(end * * * *) = #(make-moment 3 8) + \time 12/8; c'8 c c c16 c c c c c [c c c c] c8 c c4 +@end lilypond @c . {Manual beams} @cindex Automatic beams -@subsubsection Manual beams +@subsection Manual beams @cindex beams, manual @cindex @code{]} @cindex @code{[} @@ -1024,19 +858,19 @@ beaming algorithm. For example, the auto beamer will not beam over rests or bar lines, so if you want that, specify the begin and end point manually using @code{[} and @code{]}: -@quotation @lilypond[fragment,relative,verbatim] \context Staff { r4 [r8 g'' a r8] r8 [g | a] r8 } @end lilypond - +Whenever an manual beam is busy, the auto beam will not produce +anything. @cindex @code{stemLeftBeamCount} If you have specific wishes for the number of beams, you can fully control the number of beams through the properties -y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. +@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. @lilypond[fragment,relative,verbatim] \context Staff { @@ -1044,59 +878,61 @@ y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] } @end lilypond -@end quotation @cindex @code{stemRightBeamCount} +The beam symbol can be tweaked through @code{Voice.Beam}'s +grob-properties @code{height} and @code{staff-position}, +in staff-spaces. -@c . {Adjusting beams} -@unnumberedsubsubsec Adjusting beams -@cindex Adjusting beams +Set @code{height} to zero, to get horizontal beams: -FIXME +@lilypond[fragment,relative,verbatim] + \property Voice.Beam \set #'direction = #1 + \property Voice.Beam \set #'height = #0 + [a''8 e' d c] +@end lilypond +Here's how you'd specify a weird looking beam that instead of being +horizontal, falls two staff spaces: - +@lilypond[fragment,relative,verbatim] + \property Voice.Beam \set #'staff-position = #2 + \property Voice.Beam \set #'height = #-2 + [c'8 c] +@end lilypond +@cindex @code{default-neutral-direction} -@c . {Slur} -@node Slur -@subsection Slur -@cindex slur +@node Expressive marks +@section Expressive marks +@c . {Slur} @menu -* Slur attachments:: -* Tie:: -* Tuplets:: +* Slur :: +* Phrasing slur:: +* Breath marks:: +* Tempo:: * Text spanner:: -* Ottava:: -* Span requests:: @end menu -Slurs connects chords and try to avoid crossing stems. A slur is -started with @code{(} and stopped with @code{)}. The -starting @code{(} appears to the right of the first note in -the slur. The terminal @code{)} appears to the left of the -first note in the slur. This makes it possible to put a note in -slurs from both sides: +@node Slur +@subsection Slur +@cindex slur +A slur indicates that notes are to be played bound or @emph{legato}. In +lilypond, they are entered using parentheses: @lilypond[fragment,verbatim,center] f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 @end lilypond -@c . {Adjusting slurs} -@unnumberedsubsubsec Adjusting slurs +Slurs avoid crossing stems, and are attached to note heads whenever +possible. In some instances involving beams slurs may be attached to a +stem end. If you want to override this layout you can do this through +@code{Voice.Slur}'s grob-property @code{attachment}: -@node Slur attachments -@subsubsection Slur attachments +Maybe reinclude other slur features and move back to tricks? Esp. the +second example, how to fix, can be very helpful. -The ending of a slur should whenever possible be attached to a note -head. Only in some instances where beams are involved, LilyPond may -attach a slur to a stem end. In some cases, you may want to override -LilyPond's decision, e.g., to attach the slur to the stem end. This can -be done through @code{Voice.Slur}'s grob-property @code{attachment}: - - -@quotation @lilypond[fragment,relative,verbatim] \property Voice.Slur \set #'direction = #1 \property Voice.Stem \set #'length = #5.5 @@ -1104,24 +940,11 @@ be done through @code{Voice.Slur}'s grob-property @code{attachment}: \property Voice.Slur \set #'attachment = #'(stem . stem) g8(g)g4 @end lilypond -@end quotation - -Similarly, slurs can be attached to note heads even when beams are -involved: - -@quotation -@lilypond[fragment,relative,verbatim] - \property Voice.Slur \set #'direction = #1 - \property Voice.Slur \set #'attachment = #'(head . head) - g''16()g()g()g()d'()d()d()d -@end lilypond -@end quotation -If a slur would strike through a stem or beam, LilyPond will move the -slur away vertically (upward or downward). In some cases, this may -cause ugly slurs that you may want to correct: +If a slur would strike through a stem or beam, the slur will be moved +away upward or downward. If this happens, attaching the slur to the +stems might look better: -@quotation @lilypond[fragment,relative,verbatim] \property Voice.Stem \set #'direction = #1 \property Voice.Slur \set #'direction = #1 @@ -1129,169 +952,133 @@ cause ugly slurs that you may want to correct: \property Voice.Slur \set #'attachment = #'(stem . stem) d,32( d'4 )d8.. @end lilypond -@end quotation - -LilyPond will increase the curvature of a slur trying to stay free of -note heads and stems. However, if the curvature would increase too much, -the slur will be reverted to its default shape. This decision is based -on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some -cases, you may find ugly slurs beautiful, and tell LilyPond so by -increasing the @code{beautiful} value: -[hoe gedefd?? wat betekent beautiful = X?] -@quotation -@lilypond[verbatim] -\score { - \notes \context PianoStaff < - \time 6/4; - \context Staff=up { s1 * 6/4 } - \context Staff=down < - \clef bass; - \autochange Staff \context Voice - \notes \relative c { - d,8( a' d f a d f d a f d )a - } - > - > - \paper { - linewidth = -1.; - \translator { - \VoiceContext - Slur \override #'beautiful = #5.0 - Slur \override #'direction = #1 - Stem \override #'direction = #-1 - autoBeamSettings \override #'(end * * * *) - = #(make-moment 1 2) - } - \translator { - \PianoStaffContext - VerticalAlignment \override #'threshold = #'(5 . 5) - } - } -} +Similarly, the curvature of a slur is adjusted to stay clear of note +heads and stems. When that would increase the curvature too much, the +slur is reverted to its default shape. The threshold for this decision +is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely +related to the enclosed area between the slur and the notes. Usually, +the default setting works well, but in some cases you may prefer a +curved slur when LilyPond decides for a vertically moved one. You can +express this by increasing the @code{beautiful} value: + +@lilypond[verbatim,singleline,relative] + \property Voice.Beam \override #'direction = #-1 + \property Voice.Slur \override #'direction = #1 + c'16( a' f' a a f a, )c, + c( a' f' a a f d, )c + \property Voice.Slur \override #'beautiful = #5.0 + c( a' f' a a f d, )c @end lilypond -@end quotation -@cindex Adusting slurs +@refbugs +The definition for @code{beautiful} is vague, the default setting is +experimental computer science. +@cindex Adusting slurs -@c . {Tie} -@node Tie -@subsubsection Tie +@node Phrasing slur +@subsection Phrasing slur -@cindex Tie -@cindex ties -@cindex @code{~} +@cindex phrasing slur +@cindex phrasing mark -A tie connects two adjacent note heads of the same pitch. When used -with chords, it connects all of the note heads whose pitches match. -Ties are indicated using the tilde symbol `@code{~}'. -If you try to tie together chords which have no common pitches, a -warning message will appear and no ties will be created. +A phrasing slur (or phrasing mark) connects chords and is used to +indicate a musical sentence. It is entered using @code{\(} and +@code{\)}. -@lilypond[fragment,verbatim,center] - e' ~ e' ~ +@lilypond[fragment,verbatim,center,relative] + \time 6/4; c''\((d)e f(e)\)d @end lilypond -[sparseTies] +Typographically, the phrasing slur behaves almost exactly like a normal +slur. The grob associated with it is @code{Voice.PhrasingSlur}. +@node Breath marks +@subsection Breath marks -@c . {Tuplets} -@node Tuplets -@subsubsection Tuplets -@cindex Tuplets -@cindex Times +Breath marks are entered using @code{\breathe}: -Tuplets are made out of a music expression by multiplying their duration -with a fraction. +@lilypond[fragment,relative] +c'4 \breathe d4 +@end lilypond -@cindex @code{\times} -@example - \times @var{fraction} @var{musicexpr} -@end example +Currently, only tick marks are supported, comma style breath marks are +not. The grob for this object is called @code{Voice.BreathingSign}. -The duration of @var{musicexpr} will be multiplied by the fraction. -In print, the fraction's denominator will be printed over the notes, -optionally with a bracket. The most common tuplet is the triplet in -which 3 notes have the length of 2, so the notes are 2/3 of -their written length: -@lilypond[fragment,verbatim,center] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 -@end lilypond +@refbugs + + Currently, only tick marks are supported, comma style breath marks are +not. + + +@c . {Tempo} +@node Tempo +@subsection Tempo +@cindex Tempo +@cindex beats per minute +@cindex metronome marking -[todo: document tupletSpannerDuration] +@cindex @code{\tempo} +@example + \tempo @var{duration} = @var{perminute} @code{;} +@end example +Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests +output with 76 quarter notes per minute. + +@refbugs + +The tempo setting is not printed, but is currently only used in the MIDI +output. + -@c . {Text spanner} @node Text spanner -@subsubsection Text spanner +@subsection Text spanner @cindex Text spanner -@c . {Ottava} -@node Ottava -@subsubsection Ottava -@cindex Ottava -@unnumberedsubsubsec Ottava - -[move to trick. Not a supported feature.] +Some textual indications, e.g. rallentando, accelerando, often extend +over a many measures. This is indicated by following the text with a +dotted line. You can create such texts in LilyPond using +text spanners. The syntax is as follows: +@example +\spanrequest \start "text" +\spanrequest \stop "text" +@end example +LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The +string to be printed, as well as the style is set through grob +properties. +An application---or rather, a hack---is to fake octavation indications. @lilypond[fragment,relative,verbatim] - a'''' b c a + \relative c' { a'''' b c a \property Voice.TextSpanner \set #'type = #'dotted-line \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") \property Staff.centralCPosition = #-13 - a\spanrequest \start "text" b c a \spanrequest \stop "text" -@end lilypond - - - -@c . {Span requests} -@node Span requests -@subsubsection Span requests -@cindex Span requests - -@cindex @code{\spanrequest} - -@example - \spanrequest @var{startstop} @var{type} -@end example -@cindex @code{\start} -@cindex @code{\stop} - -Define a spanning request. The @var{startstop} parameter is either -1 -(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that -describes what should be started. Supported types are @code{crescendo}, -@code{decrescendo}, @code{beam}, @code{slur}. [FIXME: many more] This -is an internal command. Users should use the shorthands which are -defined in the initialization file @file{spanners.ly}. - -You can attach a (general) span request to a note using - -@lilypond[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" + a\spanrequest \start "text" b c a \spanrequest \stop "text" } @end lilypond -The slur syntax with parentheses is a shorthand for this. - @c . {Ornaments} @node Ornaments -@subsection Ornaments +@section Ornaments @cindex Ornaments @menu * Articulation:: * Text scripts:: +* Grace notes:: +* Glissando :: +* Dynamics:: @end menu @c . {Articulation} @node Articulation -@subsubsection Articulation +@subsection Articulation @cindex Articulation @cindex articulations @@ -1308,7 +1095,6 @@ respectively. Here is a chart showing symbols above notes, with the name of the corresponding symbol appearing underneath. @lilypond[] - \score { < \notes { \property Score.LyricSyllable \override #'font-family = @@ -1337,32 +1123,10 @@ name of the corresponding symbol appearing underneath. indent = 0.0; } } - @end lilypond -@c . {Text scripts} -@node Text scripts -@subsubsection Text scripts -@cindex Text scripts - -FIXME: markup - -In addition, it is possible to place arbitrary strings of text or -@TeX{} above or below notes by using a string instead of an -identifier: @code{c^"text"}. Fingerings -can be placed by simply using digits. All of these note ornaments -appear in the printed output but have no effect on the MIDI rendering of -the music. - -@c . {Fingerings} -@unnumberedsubsubsec Fingerings -@cindex Fingerings - -To save typing, fingering instructions (digits 0 to 9 are -supported) and single characters shorthands exist for a few -common symbols - -@lilypond[] +To save typing work, some shorthands are available: +@lilypond[singleline] \score { \notes \context Voice { \property Voice.TextScript \set #'font-family = #'typewriter @@ -1373,43 +1137,17 @@ common symbols c''4-|_"c-|" s4 c''4->_"c->" s4 c''4-^_"c-\\^{ }" s4 - c''4-1_"c-1" s4 - c''4-2_"c-2" s4 - c''4-3_"c-3" s4 - c''4-4_"c-4" s4 - } - \paper { - linewidth = 5.875 \in; - indent = 0.0; } } - @end lilypond +@cindex fingering -@cindex @code{\textscript} - -@example - - \textscript @var{text} @var{style} -@end example - -Defines a text to be printed over or under a note. @var{style} is a -string that may be one of @code{roman}, @code{italic}, @code{typewriter}, -@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}. - -You can attach a general textscript request using this syntax: - -@quotation - -@example -c4-\textscript "6" "finger" -c4-\textscript "foo" "normal" -@end example - -@end quotation +Fingering instructions can also be entered in this shorthand. +@lilypond[verbatim, singleline, fragment] + c'4-1 c'4-2 c'4-3 c'4-4 +@end lilypond -This is equivalent to @code{c4-6 c4-"foo"}. @cindex @code{\script} @cindex scripts @@ -1420,7 +1158,7 @@ This is equivalent to @code{c4-6 c4-"foo"}. \script @var{alias} @end example -Prints a symbol above or below a note. The argument is a string which +Defines a script printing request. The argument is a string which points into the script-alias table defined in @file{scm/script.scm}. Usually the @code{\script} keyword is not used directly. Various helpful identifier definitions appear in @file{script.ly}. @@ -1428,6 +1166,54 @@ helpful identifier definitions appear in @file{script.ly}. For information on how to add scripts, consult @file{scm/script.scm}. +@refbugs + +All of these note ornaments appear in the printed output but have no +effect on the MIDI rendering of the music. + +Unfortunately, there is no support adding fingering instructions or +ornaments to individual note heads. Some hacks exist, though. See +@file{input/test/script-horizontal.ly}. + + +@c . {Text scripts} +@node Text scripts +@subsection Text scripts +@cindex Text scripts + +In addition, it is possible to place arbitrary strings of text or markup +text (see @ref{Text markup}) above or below notes by using a string: +@code{c^"text"}. The text is typeset in italic by default. + +The amount of space taken by these indications by default does not +influence, spacing, but setting @code{Voice.textNonEmpty} to true will +take the widths into account. The identifier @code{\fattext} is defined +in the standard includes. +@lilypond[fragment,singleline,verbatim] +\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 } +@end lilypond + +Text scripts are created in form of @code{Voice.TextScript} grobs. + +For purposes of defining identifiers, a more verbose form also exists: + +@example + \textscript @var{text} +@end example + +Defines a text to be printed over or under a note. @var{text} is a +string or a markup text. +@quotation + +@example +foo = \textscript #'(finger "6") + [..] +c4-\foo +@end example + +@end quotation + +This is equivalent to @code{c4-6 c4-"foo"}. @c . {Grace notes} @@ -1446,36 +1232,27 @@ For information on how to add scripts, consult @file{scm/script.scm}. @cindex grace notes @cindex @code{graceAlignPosition} +Grace notes are ornaments that are written out, but do not take up any +logical time in a measure. LilyPond has limited support for grace notes. +The syntax is as follows. @example \grace @var{musicexpr} @end example -A grace note expression has duration 0; the next real note is -assumed to be the main note. - -You cannot have the grace note after the main note, in terms of -duration, and main notes, but you can typeset the grace notes to the -right of the main note using the property -@code{graceAlignPosition}. -@cindex @code{flagStyle} - When grace music is interpreted, a score-within-a-score is set up: @var{musicexpr} has its own time bookkeeping, and you could (for example) have a separate time signature within grace notes. While in this score-within-a-score, you can create notes, beams, slurs, etc. Unbeamed eighth notes and shorter by default have a slash through the stem. This behavior can be controlled with the -@code{flagStyle} property. +@code{Stem}.@code{flag-style} property. -@quotation @lilypond[fragment,verbatim] \relative c'' { \grace c8 c4 \grace { [c16 c16] } c4 - \grace { \property Grace.flagStyle = "" c16 } c4 + \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4 } - @end lilypond -@end quotation At present, nesting @code{\grace} notes is not supported. The following @@ -1483,38 +1260,35 @@ may cause run-time errors: @example @code{\grace @{ \grace c32 c16 @} c4} @end example -Since the meaning of such a construct is unclear, we don't consider -this a loss. Similarly, juxtaposing two @code{\grace} sections is +Since the meaning of such a construct is unclear, we don't consider this +a loss. Similarly, juxtaposing two @code{\grace} sections is syntactically valid, but makes no sense and may cause runtime errors. - Ending a staff or score with grace notes may also generate a run-time error, since there will be no main note to attach the grace notes to. -The present implementation is not robust and generally kludgy. We expect -it to change after LilyPond 1.4. Syntax changes might also be -implemented. +A grace note expression has duration 0; the next real note is assumed to +be the main note. If you want the note to appear after the main note, +set @code{Voice.graceAlignPosition} to @code{1}. +@refbugs +The present implementation of grace notes is not robust and generally +kludgy. We expect it to change after LilyPond 1.4. Syntax changes might +also be implemented. - -@c . {Stem tremolo} @menu * Glissando :: * Dynamics:: -* Crescendo and Decrescendo:: -* Bar lines:: -* Breath marks:: -* Rehearsal marks:: @end menu @c . {Glissando} @node Glissando -@subsubsection Glissando +@subsection Glissando @cindex Glissando @cindex @code{\glissando} @@ -1522,11 +1296,11 @@ implemented. A glissando line can be requested by attaching a @code{\glissando} to a note: -@quotation @lilypond[fragment,relative,verbatim] c'' \glissando c' @end lilypond -@end quotation + +@refbugs Printing of an additional text (such as @emph{gliss.}) must be done manually. @@ -1535,7 +1309,7 @@ manually. @c . {Dynamics} @node Dynamics -@subsubsection Dynamics +@subsection Dynamics @cindex Dynamics @@ -1558,19 +1332,16 @@ manually. @cindex @code{\rfz} +Absolute dynamic marks are specified by using an identifier after a +note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}. - - - -Dynamic marks are specified by using an identifier after a note: -@code{c4-\ff}. The available dynamic marks are: -@code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, -@code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, -@code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}. - -@c . {Crescendo and Decrescendo} -@node Crescendo and Decrescendo -@subsubsection Crescendo and Decrescendo +@lilypond[verbatim,singleline,fragment,relative] + c''\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff + c2\sf c\rfz +@end lilypond @cindex Crescendo and Decrescendo @cindex crescendo @@ -1583,9 +1354,8 @@ Dynamic marks are specified by using an identifier after a note: @cindex @code{\"!} - A crescendo mark is started with @code{\cr} and terminated with -@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is +@code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is started with @code{\decr} and terminated with @code{\rced}. There are also shorthands for these marks. A crescendo can be started with @code{\<} and a decrescendo can be started with @code{\>}. Either one @@ -1596,7 +1366,7 @@ want to get several marks during one note, you must use spacer notes. @lilypond[fragment,verbatim,center] c'' \< \! c'' d'' \decr e'' \rced - < f''1 { s4 \< \! s2 \> \! s4 } > + < f''1 { s4 s4 \< \! s4 \> \! s4 } > @end lilypond You can also use a text saying @emph{cresc.} instead of hairpins. Here @@ -1611,87 +1381,258 @@ is an example how to do it: @end lilypond +@refbugs -@c . {Bar lines} -@node Bar lines -@subsubsection Bar lines -@cindex Bar lines - -@cindex @code{\bar} -@cindex measure lines -@cindex repeat bars - -@example - \bar @var{bartype}; -@end example +When using spacer notes to subdivide note dynamics and @code{linewidth = +-1}, starting a hairpin on the first spacer note (the one coinciding +with the real note) exposes an embarassing bug. -This is a short-cut for doing -@example - \property Score.whichBar = @var{bartype} -@end example -You are encouraged to use @code{\repeat} for repetitions. See -@ref{Repeat}, and the documentation of @code{whichBar} in -@ref{(lilypond-internals)LilyPond context properties}. +@c . {Repeats} +@node Repeats +@section Repeats -[FIXME] -@c . {Breath marks} -@node Breath marks -@subsubsection Breath marks -@cindex Breath marks +@cindex repeats +@cindex @code{\repeat} -@c . {Rehearsal marks} -@node Rehearsal marks -@subsubsection Rehearsal marks -@cindex Rehearsal marks -@cindex mark -@cindex @code{\mark} +To specify repeats, use the @code{\repeat} keyword. Since repeats +should work differently when played or printed, there are a few +different variants of repeats. -@example - \mark @var{unsigned}; -@cindex @code{Mark_engraver} - \mark @var{string}; -@end example +@table @asis +@item unfolded +Repeated music is fully written (played) out. Useful for MIDI +output. -Prints a mark over or under the staff. +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (voltas) are printed, left to right. +@item folded +Alternative endings are written stacked. Which is unfortunately not +practical for anything right now. -@c . {Bar check} -@node Bar check -@subsection Bar check -@cindex Bar check +@item tremolo +Make tremolo beams. -@cindex bar check -@cindex @code{barCheckNoSynchronize} -@cindex @code{|} +@item percent +Make measure repeats. These look like percent signs. +@end table -Whenever a bar check is encountered during interpretation, a warning -message is issued if it doesn't fall at a measure boundary. This can -help you find errors in the input. Depending on the value of -@code{barCheckNoSynchronize}, the beginning of the measure will be -relocated, so this can also be used to shorten measures. +@menu +* Repeat syntax:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivision:: +* Measure repeats:: +@end menu -A bar check is entered using the bar symbol, @code{|} +@node Repeat syntax +@subsection Repeat syntax +The syntax for repeats is +@example + \repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example + +If you have alternative endings, you may add +@cindex @code{\alternative} +@example + \alternative @code{@{} @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @code{@}} +@end example +where each @var{alternative} is a music expression. + +Normal notation repeats are used like this: +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 { c'4 d' e' f' } + \repeat volta 2 { f' e' d' c' } +@end lilypond + +With alternative endings: +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } +@end lilypond + +Folded repeats look like this:@footnote{Folded repeats offer little +more over simultaneous music. However, it is to be expected that +more functionality -- especially for the MIDI backend -- will be +implemented at some point in the future.} + +@lilypond[fragment,verbatim] + c'1 + \repeat fold 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } + +@end lilypond + +If you don't give enough alternatives for all of the repeats, then +the first alternative is assumed to be repeated often enough to equal +the specified number of repeats. + +@lilypond[fragment,verbatim] +\context Staff { + \relative c' { + \partial 4; + \repeat volta 3 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b2. } } + } +} +@end lilypond + +@refbugs +As you can see, LilyPond doesn't remember the timing information, nor +are slurs or ties repeated, so you have to reset timing information +after a repeat, e.g. using a bar-check (See @ref{Bar check}), +@code{Score.measurePosition} or @code{\partial}. We hope to fix this +after 1.4. + +It is possible to nest @code{\repeat}, although it probably is only +meaningful for unfolded repeats. + +@node Manual repeat commands +@subsection Manual repeat commands + +@cindex @code{repeatCommands} + +The property @code{repeatCommands} can be used to control the layout of +repeats. Its value is a Scheme list of repeat commands, where each repeat +command can be + +@table @code +@item 'start-repeat + Print a |: bar line +@item 'stop-repeat + Print a :| bar line +@item (volta . @var{text}) + Print a volta bracket saying @var{text}. +@item (volta . #f) + Stop a running volta bracket +@end table + +@lilypond[verbatim, fragment] + c''4 + \property Score.repeatCommands = #'((volta "93") end-repeat) + c4 c4 + \property Score.repeatCommands = #'((volta #f)) + c4 c4 +@end lilypond + + +@node Tremolo repeats +@subsection Tremolo repeats +@cindex tremolo beams + +To place tremolo marks between notes, use @code{\repeat} with tremolo +style. +@lilypond[verbatim,center,singleline] +\score { + \context Voice \notes\relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } + \repeat "tremolo" 4 c16 + } +} +@end lilypond +@refbugs +At present, the spacing between tremolo beams is not regular, since the +spacing engine does not notice that not all notes are printed. + +@node Tremolo subdivision +@subsection Tremolo subdivision +@cindex tremolo marks +@cindex @code{tremoloFlags} + +Tremolo marks can be printed on a single note by adding +`@code{:}[@var{length}]' after the note. The length must be at least 8. +A @var{length} value of 8 gives one line across the note stem. If the +length is omitted, then then the last value (stored in +@code{Voice.tremoloFlags}) is used. + +@lilypond[verbatim,fragment,center] + c'2:8 c':32 +@end lilypond +Using this mechanism pays off when you entering many tremolos, since the +default argument saves a lot of typing. + +@refbugs + + +Tremolos in this style do not carry over into the MIDI output. + + +@node Measure repeats +@subsection Measure repeats + +@cindex percent repeats +@cindex measure repeats + +In the @code{percent} style, a note pattern can be repeated. It is +printed once, and then the pattern is replaced with a special sign. + +@lilypond[verbatim,singleline] + \context Voice { \repeat "percent" 4 { c'4 } + \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 } +} +@end lilypond + +@refbugs + +You can not nest percent repeats, filling in the first measure with +slashes, and repeating that measure with percents. + +@node Rhythmic music +@section Rhythmic music + + +@menu +* Rhythmic staffs:: +@end menu + +@node Rhythmic staffs +@subsection Rhythmic staffs + +Some times you might want to show only the rhythm of a melody. This can +be done with the rhythmic staff. All pitches of notes on such a staff +are squashed, and the staff itself looks has a single staff line: + +@lilypond[fragment,relative ] + \context RhythmicStaff { + \time 4/4; + c4 e8 f g2 | r4 g r2 | g1:32 | r1 | + } +@end lilypond @c . {Piano music} @node Piano music @section Piano music + +Piano music is an odd type of notation: two staffs are largely +independent, but sometimes voices can cross between the two staffs. The +@code{PianoStaff} is especially built to handle this cross-staffing +behavior. In this section we discuss the @code{PianoStaff} and some +other pianistic peculiarities. + @menu * Automatic staff changes:: * Manual staff switches:: * Pedals:: * Arpeggio:: -* Follow Thread:: +* VoiceFollower:: @end menu @@ -1700,7 +1641,31 @@ A bar check is entered using the bar symbol, @code{|} @subsection Automatic staff changes @cindex Automatic staff changes -[\autochange] +Voices can be switched from top to bottom staff automatically. The +syntax for this is +@example + \autochange @var{contexttype} @var{musicexp} +@end example +This will switch notation context of @var{musicexp} between a +@var{contexttype} named @code{up} and @code{down}. Typically, you use +@code{Staff} for @var{contexttype}. The autochanger switches on basis +of pitch (central C is the turning point), and it looks ahead skipping +over rests to switch rests in advance. + +@lilypond[verbatim,singleline] +\score { \notes \context PianoStaff < + \context Staff = "up" { + \autochange Staff \context Voice = VA < \relative c' { + g4 a b c d r4 a g } > } + \context Staff = "down" { + \clef bass; + s1*2 +} > } +@end lilypond + +Note how spacer rests are used to prevent the bottom staff from +terminating too soon. + @node Manual staff switches @subsection Manual staff switches @@ -1708,684 +1673,1236 @@ A bar check is entered using the bar symbol, @code{|} @cindex manual staff switches @cindex staff switch, manual +Voices can be switched between staffs manually, using the following command: +@example + \translator Staff = @var{which} @var{music} +@end example +The string @var{which} is the name of the staff. Typically it is +@code{"up"} or @code{"down"}. + +Formally, this construct is a music expression indicating that the +context which is a direct child of the a context of type +@var{contexttype} should be shifted to a context of type +@var{contexttype} and the specified name. + @cindex @code{\translator} @example \translator @var{contexttype} = @var{name} @end example -A music expression indicating that the context which is a direct -child of the a context of type @var{contexttype} should be shifted to -a context of type @var{contexttype} and the specified name. -Usually this is used to switch staffs in Piano music, e.g. +@c . {Pedals} +@node Pedals +@subsection Pedals +@cindex Pedals + +Piano pedal instruction can be expressed using +@code{\sustainDown}, @code{\sustainUp}, @code{\unaChorda}, +@code{\treChorde}, @code{\sostenutoDown} and @code{\sostenutoUp}. + +These identifiers are shorthands for spanner commands of the types +@code{Sustain}, @code{UnaChorda} and @code{Sostenuto}: + +@lilypond[fragment,verbatim] +c''4 \spanrequest \start "Sustain" c''4 c''4 \spanrequest \stop "Sustain" +@end lilypond + +The symbols that are printed can be modified by setting +@code{pedal@var{X}Strings}, where @var{X} is one of the pedal +types. Refer to the generated documentation for more information. + +@refbugs + + +Currently, brackets are not supported, only text markings (ie. *Ped +style). + + +@c . {Arpeggio} +@node Arpeggio +@subsection Arpeggio +@cindex Arpeggio + +@cindex broken arpeggio +@cindex @code{\arpeggio} + +You can specify an arpeggio sign on a chord by attaching an +@code{\arpeggio} to a note of the chord. + + +@lilypond[fragment,relative,verbatim] + \context Voice +@end lilypond + +When an arpeggio crosses staffs in piano music, you attach an arpeggio +to the chords in both staffs, and set +@code{PianoStaff.connectArpeggios}. + +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.connectArpeggios = ##t + \context Voice = one { } + \context Voice = other { \clef bass; } + > +@end lilypond + +This command creates @code{Arpeggio} grobs. + +@refbugs + + It is not possible to mix +connected arpeggios and unconnected arpeggios at the same time. + + +@c . {VoiceFollower} +@node VoiceFollower +@subsection VoiceFollower + +@cindex follow voice +@cindex staff switching +@cindex cross staff + +@cindex @code{followVoice} + +Whenever a voice switches to another staff a line connecting the notes +can be printed automatically. This is enabled if the property +@code{PianoStaff.followVoice} is set to true: + +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.followVoice = ##t + \context Staff \context Voice { + c'1 + \translator Staff=two + b2 a + } + \context Staff=two {\clef bass; \skip 1*2;} + > +@end lilypond + + +@c . {Lyrics} +@node Lyrics +@section Lyrics + + +@menu +* Lyrics mode:: +* Printing lyrics:: +* Automatic syllable durations:: +* More stanzas:: +@end menu + +@c . {Lyrics mode} +@node Lyrics mode +@subsection Lyrics mode +@cindex Lyrics mode + +To print lyrics in LilyPond, you must first make a music expression from +the lyric text. When they're in a music expression, that music +expression can be printed by selecting an appropriate context. We shall +discuss lyric printing in this order. + + +@cindex lyric mode +@cindex @code{\lyrics} + +You can enter lyrics in a special input mode of LilyPond. This mode is +called Lyrics mode, and it is introduced by the keyword @code{\lyrics}. +The purpose of this mode is that you can enter lyrics as plain text, +punctuation and accents without any hassle. + +The precise definition of this mode is in @ref{Lyrics mode +definition}. The definition itself is ludicrous, and this will remain so +until the authors of LilyPond acquire a deeper understanding of +character encoding, or someone else steps up to fix this. + +Syllables are entered like notes, with pitches replaced by text. For +example, @code{Twin- kle twin- kle} enters four syllables. Note that +the hyphen has no special meaning for lyrics, and does not introduce +special symbols. + +Spaces can be introduced into a lyric either by using quotes +(@code{"}) or by using an underscore without quotes: @code{He_could4 +not4}. All unquoted underscores are converted to spaces. + +@c . {Printing lyrics} +@node Printing lyrics +@subsection Printing lyrics +@cindex lyrics + +Normally, you will want to have notes and syllables matched +automatically. This is accomplished using @code{\addlyrics}, which is +documented in @ref{Automatic syllable durations}. Setting +@code{automaticMelismata} in the melody staff, will cause slurs to be +interpreted as melismata. Lyric syllables must be interpreted within a +@code{Lyrics} context in order to printing them. + +@lilypond[verbatim,singleline] +\addlyrics \notes \relative c' { + \time 7/4; + \property Staff.automaticMelismata = ##t + d'2 c4 b2 a2 + b2 c4 b4 () a4 g2 } + \context Lyrics \lyrics { + Join us now and + share the so -- ftware; } +@end lilypond + +@cindex extender +@cindex lyric extender +@cindex melisma + +As you can see, extender lines are entered as @code{__}. This will +create an extender, a line that extends over the entire duration of the +lyric. This line will run all the way to the start of the next lyric, +so you may want to shorten it by using a blank lyric (using @code{_}). + +@cindex hyphen + +If you want to have hyphens centered between syllables (rather than +attached to the end of the first syllable) you can use the special +`@code{-}@code{-}' lyric as a separate word between syllables. This +will result in a hyphen which length varies depending on the space +between syllables, and which will be centered between the syllables. + +@cindex Lyric hyphen + +@node Automatic syllable durations +@subsection Automatic syllable durations +@cindex Automatic syllable durations + +@cindex automatic lyric durations +@cindex @code{\addlyrics} + +If you have lyrics that are set to a melody, you can import the rhythm +of that melody into the lyrics using @code{\addlyrics}. The syntax for +this is +@example + \addlyrics @var{musicexpr1 musicexpr2} +@end example + +This means that both @var{musicexpr1} and @var{musicexpr2} are +interpreted, but that every non-command atomic music expression +(``every syllable'') in @var{musicexpr2} is interpreted using timing +of @var{musicexpr1}. +@cindex @code{automaticMelismata} + +If the property @code{automaticMelismata} is set in the +context of @var{musicexpr1}, no lyrics will be put on slurred or tied +notes. + +@lilypond[verbatim,fragment] +\addlyrics +\transpose c'' { + \property Voice.automaticMelismata = ##t + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics { + do4 re mi fa } +@end lilypond + +If you want the lyric lines to be above the melody staff, or in some +other, more complex configuration, then build that configuration first +using simultaneous music, and use @code{\addlyrics} after that. + +@lilypond[verbatim, singleline] +\notes < + \context Lyrics = LA { s1 } + \context Staff = SA { s1 } + \addlyrics + \context Staff = SA \relative c' { c4 e g g } + \context Lyrics = LA \lyrics { geen ge -- don -- der } > +@end lilypond + +For @code{\addlyrics} you should use a single rhythm melody, and single +rhythm lyrics (a constant duration is the obvious choice). If you do +not, you can get undesired effects when using multiple stanzas: + +@lilypond[verbatim,fragment] +\addlyrics +\transpose c'' { + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics +< { do4 re mi fa } + { do8 re mi fa } > +@end lilypond + +It is valid (but probably not very useful) to use notes instead of +lyrics for @var{musicexpr2}. + +@node More stanzas +@subsection More stanzas + +@cindex phrasing + +If you have multiple stanzas printed underneath each other, the separate +syllables should be aligned around punctuation. LilyPond can do this if +you explain it which lyric lines belong to which melody. + +To this end, give the Voice context an identity, and set the LyricsVoice +to name starting with that identity. In the following example, the Voice +identity is @code{duet}, and the identities of the LyricsVoices are +@code{duet-1} and @code{duet-2}. + + +@lilypond[singleline,verbatim] +\score { +\addlyrics + \notes \relative c'' \context Voice = duet { \time 3/4; + g2 e4 a2 f4 g2. } + \lyrics \context Lyrics < + \context LyricsVoice = "duet-1" { + \property LyricsVoice . stanza = "Bert" + Hi, my name is bert. } + \context LyricsVoice = "duet-2" { + \property LyricsVoice . stanza = "Ernie" + Ooooo, ch\'e -- ri, je t'aime. } + > +} +@end lilypond + +You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the +first system) and @code{LyricsVoice.stz} for the following systems. + +@cindex stanza numbering + + +@c . {Chords} +@node Chords +@section Chords +@cindex Chords + +LilyPond has support for both entering and printing chords. Chords are +a harmonic device that is characterized by a set of pitches. It is +something different from simultaneous music, although you can express a +chord using simultaneous music. In fact, chords are internally stored as +simultaneous music expressions. This means you can enter chords by name, +and print them as note head, or enter as notes and print as chord names: + + +@lilypond[verbatim,singleline] +twoWays = \notes \transpose c'' { + \chords { + c1 f:sus4 bes/f + } + + + + } + +\score { + < \context ChordNames \twoWays + \context Staff \twoWays > } +@end lilypond + +Note that this example also shows that the LilyPond chord does not +attempt to be intelligent, if you enter @code{f bes d}, it does no +attempt to find out whether it this is an inversion. + +@menu +* Chords mode:: +* Printing named chords:: +@end menu + +@c . {Chords mode} +@node Chords mode +@subsection Chords mode +@cindex Chords mode + +Chord mode is a mode where you can input sets of pitches using common +names. It is introduced by the keyword @code{\chords}. It is similar +to note mode, but words are also looked up in a chord modifier table +(containing @code{maj}, @code{dim}, etc). + +Dashes and carets are used to indicate chord additions and subtractions, +so articulation scripts can not be entered in Chord mode. + +The syntax for named chords is as follows: +@example + + @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. +@end example + +@var{tonic} should be the tonic note of the chord, and @var{duration} +is the chord duration in the usual notation. There are two kinds of +modifiers. One type is @emph{chord additions}, which are obtained by +listing intervals separated by dots. An interval is written by its +number with an optional @code{+} or @code{-} to indicate raising or +lowering by half a step. Chord additions has two effects: It adds +the specified interval and all lower odd numbered intervals to the +chord, and it may lower or raise the specified interval. Intervals +must be separated by a dot (@code{.}). + +Throughout these examples, chords have been shifted around the staff +using @code{\transpose}. + +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1 c:3- c:7 c:8 + c:9 c:9-.5+.7+ c:3-.5- c:4.6.8 + } +} +@end lilypond + +@cindex @code{aug} +@cindex @code{dim} +@cindex @code{maj} +@cindex @code{sus} + +The second type of modifier that may appear after the @code{:} is a +named modifier. Named modifiers are listed in the file +@file{chord-modifiers.ly}. The available modifiers are @code{m} and +@code{min} which lower the 3rd half a step, `@code{aug}' which +raises the 5th, `@code{dim}' which lowers the 5th, +`@code{maj}' which adds a raised 7th, and `@code{sus}' +which replaces the 5th with a 4th. + +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1:m c:min7 c:maj c:aug c:dim c:sus + } +} +@end lilypond + + +Chord subtractions are used to eliminate notes from a chord. The +notes to be subtracted are listed after a @code{^} character, +separated by dots. + +@lilypond[fragment,verbatim,center] + \transpose c'' { + \chords { + c1^3 c:7^5.3 c:8^7 + } + } +@end lilypond +@cindex @code{/} + +Chord inversions can be specified by appending `@code{/}' and the name +of a single note to a chord. In a chord inversion, the inverted note is +transposed down until it is the lowest note in the chord. If the +specified note is not in the chord, a warning will be printed. + +@lilypond[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/e c/g c:7/e + } + } -@example - \translator Staff = top @var{Music} -@end example +@end lilypond +@cindex @code{/+} +Bass notes can be added by `@code{/+}' and +the name of a single note to a chord. This has the effect of +adding the specified note to the chord, lowered by an octave, +so it becomes the lowest note in the chord. -@c . {Pedals} -@node Pedals -@subsection Pedals -@cindex Pedals +@lilypond[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/+c c/+g c:7/+b + } + } -[todo] +@end lilypond -@c . {Arpeggio} -@node Arpeggio -@subsection Arpeggio -@cindex Arpeggio -@cindex broken arpeggio -@cindex @code{\arpeggio} -You can specify an arpeggio sign on a chord by attaching an -@code{\arpeggio} to a note of the chord. +@c . {Printing named chords} +@node Printing named chords +@subsection Printing named chords +@cindex printing chord names +@cindex chord names +@cindex chords +@cindex @code{ChordNames} -@quotation -@lilypond[fragment,relative,verbatim] - \context Voice -@end lilypond -@end quotation -When an arpeggio crosses staffs in piano music, you attach an arpeggio -to the chords in both staffs, and set -@code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios -in both staffs. +For displaying printed chord names, use the @code{ChordNames} context. +The chords may be entered either using the notation described above, or +directly using simultaneous music. -@quotation -@lilypond[fragment,relative,verbatim] - \context PianoStaff < - \property PianoStaff.connectArpeggios = ##t - \context Voice = one { } - \context Voice = other { \clef bass; } - > +@lilypond[verbatim,singleline] +scheme = \notes { + \chords {a1 b c} +} +\score { + \notes< + \context ChordNames \scheme + \context Staff \transpose c'' \scheme + > +} @end lilypond -@end quotation +You can make the chord changes stand out by setting property +@code{ChordNames.chordChanges} to true. This will only display chord +names when there's a change in the chords scheme and at the start of the +line. +@lilypond[verbatim] +scheme = \chords { + c1:m \break c:m c:m c:m d +} -@c . {Follow Thread} -@node Follow Thread -@subsection Follow Thread -@cindex follow thread -@cindex staff switching -@cindex cross staff +\score { + \notes < + \context ChordNames { + \property ChordNames.chordChanges = ##t + \scheme } + \context Staff \transpose c'' \scheme + > } +@end lilypond -[todo: different name, eg. voice line ? ] +LilyPond examines chords specified as lists of notes to determine a name +to give the chord. LilyPond will not try to identify chord inversions or +added base, which may result in strange chord names when chords are +entered as a list of pitches: -@cindex @code{followThread} +[base vs. bass ?] -Whenever a voice switches to another staff a line connecting the notes -can be printed automatically. This is enabled if the property -@code{PianoStaff.followThread} is set to true: +@lilypond[verbatim,center,singleline] +scheme = \notes { + + + +} -@quotation -@lilypond[fragment,relative,verbatim] - \context PianoStaff < - \property PianoStaff.followThread = ##t - \context Staff \context Voice { - c'1 - \translator Staff=two - b2 a - } - \context Staff=two {\clef bass; \skip 1*2;} - > +\score { + < + \context ChordNames \scheme + \context Staff \scheme + > +} @end lilypond -@end quotation +By default LilyPond uses chord name system proposed by Harald Banter +(See @ref{Literature}). The system is is unambiguous and has a logical +structure. Typical American style chord names may be selected by +setting the @code{style} property of the @code{ChordNames.ChordName} +grob to @code{'american}. Similarly @code{'jazz} selects Jazz +chordnames. +Routines that determine the names to be printed are written in Scheme, +and may be customized by the user. The code can be found in +@file{scm/chord-name.scm}. +[3 short examples showing differences between american, banter and jazz] +@node Writing parts +@section Writing parts +Orchestral music involves some special notation, both in the full score, +as in the individual parts. This section explains how to tackle common +problems in orchestral music. -@c . {Lyrics} -@node Lyrics -@section Lyrics - - +@c . {Transpose} @menu -* Lyrics mode:: -* Printing lyrics:: -* Automatic syllable durations:: +* Rehearsal marks:: +* Bar numbers:: +* Instrument names:: +* Transpose:: +* Sound output for transposing instruments:: +* Multi measure rests:: +* Automatic part combining:: +* Hara-kiri staffs:: @end menu -@c . {Lyrics mode} -@node Lyrics mode -@subsection Lyrics mode -@cindex Lyrics mode - -@cindex lyric mode -@cindex @code{\lyrics} - -Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has -rules that make it easy to include punctuation and diacritical marks in -words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{} -format or a standard encoding without needing quotes. The precise -definition of this mode is ludicrous, and this will remain so until the -authors of LilyPond acquire a deeper understanding of character -encoding, or someone else steps up to fix this. - -A word in Lyrics mode begins with: an alphabetic character, @code{_}, -@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} -through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, -any 8-bit character with ASCII code over 127, or a two-character -combination of a backslash followed by one of @code{`}, @code{'}, -@code{"}, or @code{^}. - -Subsequent characters of a word can be any character that is not a digit -and not white space. One important consequence of this is that a word -can end with `@code{@}}', which may be confusing. However, LilyPond will -issue a warning. Any @code{_} character which appears in an unquoted -word is converted to a space. This provides a mechanism for introducing -spaces into words without using quotes. Quoted words can also be used -in Lyrics mode to specify words that cannot be written with the above -rules. Here are some examples. Not all of these words are printable by -@TeX{}. +@c . {Rehearsal marks} +@node Rehearsal marks +@subsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} +@cindex @code{Mark_engraver} -@example -Ah! % a word -2B_||_!2B % not a word because it starts with a digit -``Hello'' % not a word because it starts with ` -_ _ _ _ % 4 words, each one a space -@end example +@example + \mark @var{unsigned}; + \mark @var{string}; + \mark ; +@end example -Since combinations of numbers and dots are used for indicating -durations, you can not enter real numbers in this mode. +With this command, you can print a rehearsal mark above the system. You +can provide a number, a string or a markup text as argument. If there is +no argument, the property @code{rehearsalMark} is used and automatically +incremented. -@cindex lyrics expressions +@lilypond[fragment,verbatim] +\relative c'' { + c1 \mark "A2"; + c1 \mark ; + c1 \mark ; + c1 \mark "12"; + c1 \mark #'(music "scripts-segno") ; + c1 +} +@end lilypond -Syllables are entered like notes, with pitches replaced by text. For -example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each -with quarter note duration. Note that the hyphen has no special -meaning for lyrics, and does not introduce special symbols. See -section @ref{Lexical modes} for a description of what is interpreted as -lyrics. +@node Bar numbers +@subsection Bar numbers -Spaces can be introduced into a lyric either by using quotes -(@code{"}) or by using an underscore without quotes: @code{He_could4 -not4}. All unquoted underscores are converted to spaces. Printing -lyrics is discussed in the next section. +Bar numbers are printed at the start of the line by default. This is +done by the @code{Bar_number_engraver} in the Score context. +@refbugs -@c . {Printing lyrics} -@node Printing lyrics -@subsection Printing lyrics -@cindex lyrics +It is currently not possible to make boxed bar numbers, or print them at +regular intervals. -Lyric syllables must be interpreted within a @code{Lyrics} context for -printing them. Here is a full example: +@node Instrument names +@subsection Instrument names -@quotation -@lilypond[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va-4 der Ja- cob Va- der Ja- cob - Slaapt gij nog?2 Slaapt4 gij nog?2 - } - > -} +You can specify an instrument name for a staff by setting +@code{Staff.instrument} and @code{Staff.instr}. This will print a string +before the start of the staff. For the first start, @code{instrument} is +used, for the next ones @code{instr} is used. +@lilypond[verbatim,singleline] +\score { \notes { + \property Staff.instrument = "ploink " { c''4 } } + \paper { + \translator { \StaffContext + \consists "Instrument_name_engraver"; } } } @end lilypond -@end quotation +This requires that you add the @code{Instrument_name_engraver} to the +staff context. +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} -@cindex extender -@cindex lyric extender +A music expression can be transposed with @code{\transpose}. The syntax +is +@example + \transpose @var{pitch} @var{musicexpr} +@end example -You may want a continuous line after the syllables to show melismata. -To achieve this effect, add a @code{__} lyric as a separate word -after the lyric to be extended. This will create an extender, a line -that extends over the entire duration of the lyric. This line will -run all the way to the start of the next lyric, so you may want to -shorten it by using a blank lyric (using @code{_}). +This means that middle C in @var{musicexpr} is transposed to +@var{pitch}. -@quotation +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose cis'} or @code{\transpose des'} will transpose up half +a tone. The first version will print sharps and the second version +will print flats. -@lilypond[verbatim] -\score { - < - \notes \relative c'' { - a4 () b () c () d | c () d () b () a | c () d () b () a - } - \context Lyrics \lyrics { - foo1 __ | bar2. __ _4 | baz1 __ - } - > +@lilypond[fragment,verbatim] +\context Staff { + \clef "F"; + { \key e \major; c d e f } + \clef "G"; + \transpose des'' { \key e \major; c d e f } + \transpose cis'' { \key e \major; c d e f } } - @end lilypond -@end quotation -@cindex Lyric hyphen +If you want to use both @code{\transpose} and @code{\relative}, then +you must use @code{\transpose} first. @code{\relative} will have no +effect music that appears inside a @code{\transpose}. -If you want to have hyphens centered between syllables (rather than -attached to the end of the first syllable) you can use the special -`@code{-}@code{-}' lyric as a separate word between syllables. This -will result in a hyphen which length varies depending on the space -between syllables, and which will be centered between the syllables. -For example: +@node Sound output for transposing instruments +@subsection Sound output transposing instruments -@quotation +When you want to play a score containing transposed and untransposed +instruments, you have to instruct LilyPond the pitch offset (in +semitones) for the transposed instruments. This is done using the +@code{transposing} property. It does not affect printed output. -@lilypond[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va4 -- der Ja -- cob | Va -- der Ja -- cob | - Slaapt gij nog?2 | Slaapt4 gij nog?2 - } - > -} +@cindex @code{transposing} + +@example + \property Staff.instrument = #"Cl. in B-flat" + \property Staff.transposing = #-2 +@end example + + +@c . {Multi measure rests} +@node Multi measure rests +@subsection Multi measure rests +@cindex Multi measure rests + +@cindex @code{R} + +Multi measure rests are entered using `@code{R}'. It is specifically +meant for entering parts: the rest can expand to fill a score with +rests, or it can be printed as a single multimeasure rest This expansion +is controlled by the property @code{Score.skipBars}. If this is set to true, +Lily will not expand empty measures, and the appropriate number is added +automatically. +@lilypond[fragment,verbatim] + \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 @end lilypond -@end quotation +Currently, there is no way to condense multiple rests into a single +multimeasure rest. -@c . {Automatic syllable durations} -@node Automatic syllable durations -@subsection Automatic syllable durations -@cindex Automatic syllable durations +@cindex condensing rests +@node Automatic part combining +@subsection Automatic part combining +@cindex automatic part combining +@cindex part combiner -[explain automatic phrasing] -@cindex automatic lyric durations -@cindex @code{\addlyrics} +Automatic part combining is used to merge two parts of music onto on +staff in an intelligent way. It is aimed primarily at typesetting Hymns +and orchestral scores. When the two parts are identical for a period of +time, only one is shown. In places where the two parts differ, stem +directions are set automatically. Also, soli and @emph{a due} parts can be +identified and marke. + +The syntax for part combining is -If you have lyrics that are set to a melody, you can import the rhythm -of that melody into the lyrics using @code{\addlyrics}. The syntax for -this is @example - \addlyrics @var{musicexpr1 musicexpr2} + \partcombine @var{context} @var{musicexpr1} @var{musicexpr2} @end example -This means that both @var{musicexpr1} and @var{musicexpr2} are -interpreted, but that every non-command atomic music expression -(``every syllable'') in @var{musicexpr2} is interpreted using timing -of @var{musicexpr1}. -@cindex @code{automaticMelismata} +where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be +combined into one context @var{context}. The names of the music +expressions must start with the prefixes @code{one} and @code{two}. -If the property @code{automaticMelismata} is set in the -context of @var{musicexpr1}, no lyrics will be put on slurred or tied -notes. +[Name of music expressions? is that context name? ] + +The most useful function of the part combiner to combining threads into +one voice, as common for wind parts in orchestral scores: + +@lilypond[verbatim,singleline,fragment] + \context Staff < + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + g a b r + } + \context Thread=two \relative c'' { + g r2 f4 + } + > +@end lilypond -@quotation -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - \property Voice.automaticMelismata = ##t - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics { - do4 re mi fa } +Notice that the first @code{g} appears only once, although it was +specified twice (once in each Thread). Also note that stem, slur and tie +directions are set automatically, depending whether there is a solo or +unisono. The Thread called @code{one} always gets up stems, and "solo", +while @code{two} always gets down stems and "Solo II". + +If you just want the splitting of Threads and setting of directions, and +not the textual markings, you may set the property @var{soloADue} to +false. This mode can be used to set hymns: + +@lilypond[verbatim,singleline,fragment] + \context Staff < + \property Staff.soloADue = ##f + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + b4 a c g + } + \context Thread=two \relative c'' { + d,2 a4 g' + } + > @end lilypond -@end quotation -You should use a single rhythm melody, and single rhythm lyrics (a -constant duration is the obvious choice). If you do not, you will get -undesired effects when using multiple stanzas: +There are a number of other properties that you can use to tweak +the behavior of part combining, refer to the automatically generated +documentation. Look for @code{Thread_devnull_engraver} +@code{Voice_devnull_engraver} and @code{A2_engraver}. -@quotation -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics -< { do4 re mi fa } - { do8 re mi fa } > +@refbugs +In @code{soloADue} mode, when the two voices play the same notes on and +off, the part combiner may typeset @code{a2} more than once in a +measure. + +@lilypond[fragment,singleline] + \context Staff < + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + c b c b c a c a + } + \context Thread=two \relative c'' { + b b b b f a f a + } + > @end lilypond -@end quotation -It is valid (but probably not very useful) to use notes instead of -lyrics for @var{musicexpr2}. +@cindex @code{Thread_devnull_engraver} +@cindex @code{Voice_engraver} +@cindex @code{A2_engraver} +@node Hara-kiri staffs +@subsection Hara-kiri staffs +In orchestral scores, staffs that only have rests are usually removed. +This saves some space. LilyPond also supports this through the +hara-kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide +of the Japanese Samourai warriors.} staff. This staff commits suicide +when it finds itself to be empty after the line-breaking process---note +that it will not disappear when it contains normal rests, you must use +multi measure rests. -@c . {Chords} -@node Chords -@section Chords -@cindex Chords +The hara kiri staff is specialized version of the Staff context. It is +available as the context identifier @code{\HaraKiriStaffContext}. +Observe how the second staff in this example disappears in the second +line. -[chords vs. simultaneous music] +@lilypond[verbatim] +\score { + \notes \relative c' < + \context Staff = SA { e4 f g a \break c1 } + \context Staff = SB { c4 d e f \break R1 } + > + \paper { + linewidth = 6.\cm ; + \translator { \HaraKiriStaffContext } + } +} +@end lilypond -@menu -* Chords mode:: -* Entering named chords:: -* Printing named chords:: -@end menu -@c . {Chords mode} -@node Chords mode -@subsection Chords mode -@cindex Chords mode -Chord mode is introduced by the keyword -@code{\chords}. It is similar to Note mode, but -words are also looked up in a chord modifier table (containing -@code{maj}, @code{dim}, etc). +@c . {Custodes} +@node Custodes +@section Custodes +@cindex Custos +@cindex Custodes + +A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a +staff context symbol that appears at the end of a staff line. It +anticipates the pitch of the first note(s) of the following line and +thus helps the player or singer to manage line breaks during +performance, thus enhancing readability of a score. -Since combinations of numbers and dots are used for indicating -durations, you can not enter real numbers in this mode. Dashes -and carets are used to indicate chord additions and subtractions, -so scripts can not be entered in Chord mode. +@lilypond[verbatim] +\score { + \notes { c'1 d' e' d' \break c' d' e' d' } + \paper { + \translator { + \StaffContext + \consists Custos_engraver; + Custos \override #'style = #'mensural; + } + } +} +@end lilypond -@c . {Entering named chords} -@node Entering named chords -@subsection Entering named chords -@cindex Chords names +Custodes were frequently used in music notation until the 16th century. +There were different appearences for different notation styles. +Nowadays, they have survived only in special forms of musical notation +such as via the @emph{editio vaticana} dating back to the beginning of +the 20th century. -Chord names are a way to generate simultaneous music expressions that -correspond with traditional chord names. It can only be used in -Chord mode (see section @ref{Lexical modes}). +For typesetting custodes, just put a @code{Custos_engraver} into the +@code{StaffContext} when declaring the @code{\paper} block. In this +block, you can also globally control the appearance of the custos symbol +by setting the custos @code{style} property. Currently supported styles +are @code{vaticana}, @code{medicaea}, @code{hufnagel} and +@code{mensural}. @example +\paper @{ + \translator @{ + \StaffContext + \consists Custos_engraver; + Custos \override #'style = #'mensural; + @} +@} +@end example - @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. +The property can also be set locally, for example in a @code{\notes} +block: + +@example +\notes @{ + \property Staff.Custos \override #'style = #'vaticana + c'1 d' e' d' \break c' d' e' d' +@} @end example -@var{tonic} should be the tonic note of the chord, and @var{duration} -is the chord duration in the usual notation. There are two kinds of -modifiers. One type is @emph{chord additions}, which are obtained by -listing intervals separated by dots. An interval is written by its -number with an optional @code{+} or @code{-} to indicate raising or -lowering by half a step. Chord additions has two effects: It adds -the specified interval and all lower odd numbered intervals to the -chord, and it may lower or raise the specified interval. Intervals -must be separated by a dot (@code{.}). +@c . {Tuning output} +@node Tuning output +@section Tuning output +LilyPond tries to take as much formatting as possible out of your +hands. Nevertheless, there are situations where it needs some help, or +where you want to override its decisions. In this section we discuss +ways to do just that. -Throughout these examples, chords have been shifted around the staff -using @code{\transpose}. +Notation output is specified in so called grobs (graphic objects). Each +grob carries with it a set of properties (grob properties) specific to +that object. For example, a stem grob has properties that specify its +direction, length and thickness. -@quotation +The most common way of tuning the output is to alter the values of these +properties. There are two ways of doing that: first, you can temporarily +change the definition of a certain type of grob, thus affecting a whole +set of objects. Second, you can select one specific object, and set a +grob property. -@lilypond[fragment,verbatim] -\transpose c'' { - \chords { - c1 c:3- c:7 c:8 - c:9 c:9-.5+.7+ c:3-.5- c:4.6.8 - } -} +@menu +* Tuning groups of grobs :: +* Tuning per grob :: +* What to tune?:: +* Font selection:: +* Text markup:: +@end menu -@end lilypond -@end quotation +@node Tuning groups of grobs +@subsection Tuning groups of grobs -@cindex @code{aug} -@cindex @code{dim} -@cindex @code{maj} -@cindex @code{sus} +@cindex grob description -The second type of modifier that may appear after the @code{:} is a -named modifier. Named modifiers are listed in the file -@file{chord-modifiers.ly}. The available modifiers are @code{m} and -@code{min} which lower the 3rd half a step, `@code{aug}' which -raises the 5th, `@code{dim}' which lowers the 5th, -`@code{maj}' which adds a raised 7th, and `@code{sus}' -which replaces the 5th with a 4th. +A grob definition is a Scheme association list, that is stored in a context +property. By assigning to that property (using plain @code{\property}), +you can change the resulting grobs. -@quotation +@lilypond[verbatim, fragment] +c'4 \property Voice.Stem \override #'meta = #'((interfaces . ())) c'4 +@end lilypond -@lilypond[fragment,verbatim] -\transpose c'' { - \chords { - c1:m c:min7 c:maj c:aug c:dim c:sus - } -} +The @code{\property} statement effectively empties the definition of the +Stem object. One of the effects is that property specifying how it +should be printed is erased, with the effect of rendering it invisible. + +@cindex \override +@cindex \revert +@cindex \set + +This mechanism is fairly crude, since you can only set, but not modify, +the definition of a grob. For this reason, there is a more advanced +mechanism: you can add a property on top of an existing definition, or +remove a property: @code{\override} adds a settings, @code{\revert} +removes that setting. +@lilypond[verbatim] +c'4 \property Voice.Stem \override #'thickness = #4.0 +c'4 \property Voice.Stem \revert #'thickness +c'4 @end lilypond -@end quotation - -Chord subtractions are used to eliminate notes from a chord. The -notes to be subtracted are listed after a @code{^} character, -separated by dots. +For the digirati, the grob description is an Scheme association +list. Since it is singly linked, we can treat it as a stack, and +@code{\override} and @code{\revert} are just push and pop +operations. This pushing and popping is also used for overriding automatic +beaming settings. -@lilypond[fragment,verbatim,center] - \transpose c'' { - \chords { - c1^3 c:7^5.3 c:8^7 - } - } -@end lilypond -@cindex @code{/} +If you revert a setting which was not set in the first place, then it +has no effect. However, if the setting was set as a system default, it +may remove the default value, and this may give surprising results, +including crashes. In other words, if you use @code{\override} and +@code{\revert}, be sure to balance the overrides and reverts. -Chord inversions can be specified by appending `@code{/}' and -the name of a single note to a chord. This has the effect of -lowering the specified note by an octave so it becomes the lowest -note in the chord. If the specified note is not in the chord, a -warning will be printed. +If balancing them is too much work, use the @code{\set} shorthand. It +performs a revert followed by an override: +@example +\property Voice.Stem \set #'thickness = #2.0 +@end example -@lilypond[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/e c/g c:7/e - } - } +Formally the syntax for these constructions is +@example +\property @var{context}.@var{grobname} \override @var{symbol} = @var{value} +\property @var{context}.@var{grobname} \set @var{symbol} = @var{value} +\property @var{context}.@var{grobname} \revert @var{symbol} +@end example +Here @var{symbol} is a Scheme expression of symbol type, @var{context} +and @var{grobname} are strings and @var{value} is a Scheme expression. -@end lilypond -@cindex @code{/+} +If you want to be +Correct nesting of @code{\override}, @code{\set}, @code{\revert} is as +follows -Bass notes can be added by `@code{/+}' and -the name of a single note to a chord. This has the effect of -adding the specified note to the chord, lowered by an octave, -so it becomes the lowest note in the chord. +@example +\override \set \set \set \set +\revert +@end example -@lilypond[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/+c c/+g c:7/+b - } - } +This is always correct, but if you know the default value, you can also use +@example +\set \set \set \set +\set @var{to default value} +@end example -@end lilypond +If there is no default (i.e. by default, the grob property is unset), +then you can use +@example +\set \set \set \set \set +\revert +@end example -The most interesting application is printing chord names, which is -explained in the next subsection. -You should not combine @code{\relative} with named chords. [FIXME] +@refbugs -@c . {Printing named chords} -@node Printing named chords -@subsection Printing named chords +LilyPond will hang or crash if @var{value} contains cyclic references. +The backend is not very strict in type-checking grob properties. If you +@code{\revert} properties that are expected to be set by default, +LilyPond may crash. +@node Tuning per grob +@subsection Tuning per grob +@cindex \outputproperty -@cindex printing chord names -@cindex chord names -@cindex chords -@cindex @code{ChordNames} -@cindex @code{ChordNameVoice} +A second way of tuning grobs is the more arcane @code{\outputproperty} +feature. +Syntax is as follows +@example +\outputproperty @var{predicate} @var{symbol} = @var{value} +@end example +Here @code{predicate} is a Scheme function taking a grob argument, and +returning a boolean. This statement is processed by the +@code{Output_property_engraver}. It instructs the engraver to feed all +grobs that it sees to @var{predicate}. Whenever the predicate returns +true, the grob property @var{symbol} will be set to @var{value}. -For displaying printed chord names, use the @code{ChordNames} and -@code{ChordNameVoice} contexts. The chords may be entered either using -the notation described above, or directly using simultaneous music. +You will need to combine this statement with @code{\context} to select +the appropriate context to apply this to. -@quotation -@lilypond[verbatim] -scheme = \notes { - \chords {a1 b c} -} -\score { - \notes< - \context ChordNamesVoice \scheme - \context Staff \transpose c'' \scheme - > - \paper { linewidth = -1.; } -} +If possible, avoid this feature: the semantics are not very clean, and +the syntax and semantics are up for rewrite. + +Here are some random examples: + +@lilypond[fragment,verbatim,singleline] +\relative c'' { c4 + \context Staff \outputproperty + #(make-type-checker 'note-head-interface) + #'extra-offset = #'(0.5 . 0.75) + } @end lilypond -@end quotation -You can make the chord changes stand out more by setting property -@code{ChordNames.chordChanges} to true. This will only display chord -names when there's a change in the chords scheme, but always display the -chord name after a line break: +@cindex @code{extra-offset} -@c bug -@quotation -@lilypond[verbatim] -scheme = \chords { - c1:m \break c:m c:m c:m d -} +This selects all note heads occurring at current staff level, and sets +the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting +them up and right. -\score { - \notes < - \context ChordNames \scheme - \context Staff \transpose c'' \scheme - > - \paper{ - linewidth = 40 * \staffspace; - \translator { - \ChordNamesContext - chordChanges = ##t - } +Move the text "m.d.", but not the fingering instruction "2". +@lilypond[verbatim,singleline] +#(define (make-text-checker text) + (lambda (grob) (equal? text (ly-get-grob-property grob 'text)))) + +\score { + \notes\relative c''' { + \property Voice.Stem \set #'direction = #1 + \outputproperty #(make-text-checker "m.d.") + #'extra-offset = #'(-3.5 . -4.5) + a^2^"m.d." } } @end lilypond -@end quotation -LilyPond examines chords specified as lists of notes to determine a -name to give the chord. LilyPond will not try to -identify chord inversions or added base, which may result in strange -chord names when chords are entered as a list of pitches: -@quotation -@lilypond[verbatim,center] -scheme = \notes { - - - -} +@node What to tune? +@subsection What to tune? -\score { - < - \context ChordNamesVoice \scheme - \context Staff \scheme - > - \paper { linewidth = -1.; } -} -@end lilypond -@end quotation +This all tells you how to tune grobs, but what variables are there? The +question is not answered in this manual (although you may encounter +some examples.). -To specify chord inversions, append @code{/}. To specify an -added bass note, append @code{/+ - \paper { linewidth = -1.; } -} -@end lilypond -@end quotation +Included with the automatically generated documentation is a master list +of grobs. Each one can be clicked, taking you to a overview of the +available properties. -The chord names that LilyPond should print are fully customizable. The -code to print chord names is written in Scheme. It can be found in -@file{scm/chord-name.scm}. Chord names are based on Banter style -naming, which is unambiguous and has a logical structure. Typical -American style chord names are implemented as a variation on Banter -names, they can be selected by setting property @code{ChordName.style} -to @code{american}: +There is also a master list of contexts. Clicking each takes you to an +overview of the context, listing which grob types are created there. -@quotation -@lilypond[verbatim] -\include "english.ly" -scheme = \chords { - c % Major triad - cs:m % Minor triad - df:m5- % Diminished triad - c:5^3 % Root-fifth chord - c:4^3 % Suspended fourth triad - c:5+ % Augmented triad - c:2^3 % "2" chord - c:m5-.7- % Diminished seventh - c:7+ % Major seventh - c:7.4^3 % Dominant seventh suspended fourth - c:5+.7 % Augmented dominant seventh - c:m5-.7 % "Half" diminished seventh - c:5-.7 % Dominant seventh flat fifth - c:5-.7+ % Major seventh flat fifth - c:m7+ % Minor-major seventh - c:m7 % Minor seventh - c:7 % Dominant seventh - c:6 % Major sixth - c:m6 % Minor sixth - c:9^7 % Major triad w/added ninth - c:6.9^7 % Six/Nine chord - c:9 % Dominant ninth - c:7+.9 % Major ninth - c:m7.9 % Minor ninth -} +@node Font selection +@subsection Font selection -\score { - \notes < - \context ChordNames \scheme - \context Staff \transpose c'' \scheme - > - \paper { - \translator { - \ChordNamesContext - ChordName \override #'word-space = #1 - ChordName \override #'style = #'american - } - } -} -@end lilypond -@end quotation +Most graphics in LilyPond are composed of characters of fonts. You can +alter the characteristics of the font by setting certain grob +properties. The mechanism that is used for this resembles LaTeX's New +Font Selection Scheme. Within this scheme, a font is entirely +characterized by its font name. + +For each grob that uses fonts (in other words, each grob that supports +@code{font-interface}) a font-name must be selected before it can be +printed. The font name is selected by looking at a number of grob +properties: + +@table @code +@item font-family + The general class of the typeface. Supported are roman (Computer +Modern), braces (for piano staff braces), music (the standard music +font), dynamic (font for dynamic signs) and typewriter + +@item font-shape + A symbol indicating the shape of the font, a finer gradation than + font-family. Choices are italic and upright +@item font-series + Symbol indicating the serie of the font. Series form a finer gradation + than font-shape. Choices are medium and bold. + +@item font-relative-size + A number indicating the size relative the standard size. For example, + with 20pt staff height, relative size -1 corresponds to 16pt staff + height, and relative size +1 corresponds to 23 pt staff height. + +@item font-design-size +A number indicating the design size of the font. + +This is a feature of the Computer Modern Font: each point size has a +slightly different design. Smaller design sizes are relatively wider, +which enhances readability. Scalable type faces such TrueType and Adobe +Type1 usually come as ``one design fits all sizes''. + +@item font-name + The name of the font, without the design size, eg. @code{cmr}, +@code{cmti}, etc. Setting this overrides font-family, font-shape and +font-series. + +@end table + +The font is selected by taking the first font that satisfies all +qualifiers specified. You can override any of these fields through +@code{\override} and @code{\revert}. The special value @code{*} matches +any value for that qualifier. + +@example + \property Lyrics.LyricText \override #'font-series = #'bold + \property Lyrics.LyricText \override #'font-shape = #'* +@end example + +@cindex @code{font-style} + +There are also pre-cooked font selection qualifiers. These are selected +through the grob property @code{font-style}. For example, the style +@code{finger} selects family @code{number} and relative size @code{-3}. +Styles available include: volta, finger, tuplet, timesig, mmrest, +script, large, Large and dynamic. + +The style sheets and tables for selecting fonts are located in +@file{scm/font.scm}. Refer to this file for more information. + +@refbugs -Similarly, Jazz style chord names are implemented as a variation on -American style names: -@quotation -@lilypond[verbatim] -scheme = \chords { - % major chords - c - c:6 % 6 = major triad with added sixth - c:maj % triangle = maj - c:6.9^7 % 6/9 - c:9^7 % add9 - - % minor chords - c:m % m = minor triad - c:m.6 % m6 = minor triad with added sixth - c:m.7+ % m triangle = minor major seventh chord - c:3-.6.9^7 % m6/9 - c:m.7 % m7 - c:3-.9 % m9 - c:3-.9^7 % madd9 - - % dominant chords - c:7 % 7 = dominant - c:7.5+ % +7 = augmented dominant - c:7.5- % 7b5 = hard diminished dominant - c:9 % 7(9) - c:9- % 7(b9) - c:9+ % 7(#9) - c:13^9.11 % 7(13) - c:13-^9.11 % 7(b13) - c:13^11 % 7(9,13) - c:13.9-^11 % 7(b9,13) - c:13.9+^11 % 7(#9,13) - c:13-^11 % 7(9,b13) - c:13-.9-^11 % 7(b9,b13) - c:13-.9+^11 % 7(#9,b13) - - % half diminished chords - c:m5-.7 % slashed o = m7b5 - c:9.3-.5- % o/7(pure 9) - - % diminished chords - c:m5-.7- % o = diminished seventh chord -} +Relative size is not linked to any real size. There is no mechanism to +select magnifications of fonts, meaning that you can not scale fonts +continuoussly. There is no style sheet provided for other fonts besides +the @TeX{} family. -\score { - \notes < - \context ChordNames \scheme - \context Staff \transpose c'' \scheme - > - \paper { - \translator { - \ChordNamesContext - ChordName \override #'word-space = #1 - ChordName \override #'style = #'jazz - } +@cindex font selection +@cindex font magnification +@cindex @code{font-interface} + + +@node Text markup +@subsection Text markup +@cindex text markup +@cindex markup text + +LilyPond has an internal mechanism to typeset texts. You can +form text markup expressions by composing scheme expressions +in the following way. + +@lilypond[verbatim, singleline] + \relative c' { + \fatText + a^#"upright" + b_#'(bold "bold") + c^#'(italic "italic") + d_#'((bold italic) "ff") + e^#'(dynamic "ff") + f_#'(lines "one" (bold "two")) + g^#'(music "noteheads-2" "flags-u3") } -} @end lilypond -@end quotation +Normally, the Scheme markup text is stored in the @code{text} property +of a grob. Formally, it is defined as follows: + +@example +text: string | (head? text+) +head: markup | (markup+) +markup-item: property | abbrev +property: (@var{key} . @var{value}) +abbrev: @code{rows lines roman music bold italic named super sub text} + @code{finger volta timesig mmrest mark script large Large dynamic} +@end example + +The markup is broken down and converted into a list of grob properties, +which are prepended to the property list. The @var{key}-@var{value} +pair is a grob property. + +The following abbreviations are currently defined: +@table @code +@item rows +horizontal mode: set all text on one line (default) +@item lines + vertical mode: set every text on new line +@item roman + select roman font +@item music + select feta font +@item bold + select bold series +@item italic + select italic shape +@item named + lookup by character name +@item text + plain text lookup (by character value) +@item super + superscript +@item sub + subscript +@item finger + select fingering number fontstyle +@item volta + select volta number fontstyle +@item timesig + select time signature number fontstyle +@item mmrest + select multi measure rest number fontstyle +@item mark + select mark number fontstyle +@item script + select scriptsize roman fontstyle +@item large + select large roman fontstyle +@item Large + select Large roman fontstyle +@item dynamic + select dynamics fontstyle +@end table +It is possible to use @TeX{} commands in the strings, but this should be +avoided because this makes it impossible for LilyPond to compute the +exact length of the string, which may lead to collisions. Also, @TeX{} +commands won't work with direct postscript output. @c . {Page layout} @node Page layout @@ -2419,7 +2936,7 @@ where each of the items is one of @item An assignment. The assignment must be terminated by a semicolon. - @item A context definition. See section @ref{Context definitions} for + @item A context definition. See @ref{Notation Contexts} for more information on context definitions. @item \stylesheet declaration. Its syntax is @@ -2427,7 +2944,13 @@ where each of the items is one of \stylesheet @var{alist} @end example - See @file{font.scm} for details of @var{alist}. + See @file{scm/font.scm} for details of @var{alist}. + @item an \elementdescriptions declaration. + @example + \elementdescriptions @var{alist} + @end example + See @file{scm/grob-description.scm} for details of @var{alist}. + @end itemize @c . {Paper variables} @@ -2445,32 +2968,42 @@ The paper block has some variables you may want to use or change: @item @code{staffspace} The distance between two staff lines, calculated from the center - of the lines. You should use either this or @code{stafflinethickness} + of the lines. If you want scale independent output, then you should +use either this or @code{stafflinethickness} as a unit for distances you modify. @cindex @code{linewidth} @item @code{linewidth} Sets the width of the lines. -If set to a negative value, a single - unjustified line is produced. +If set to a negative value, a single unjustified line is produced. +@c rename to singleLinePaper ? +The shorthand @code{\singleLine} defines a default paper block that +produces a single line. @cindex @code{textheight} @item @code{textheight} Sets the total height of the music on each page. Only used by - ly2dvi. +@code{ly2dvi}. + @cindex @code{interscoreline} @item @code{interscoreline} - Sets the spacing between the score lines. Defaults to 16 pt. + Sets the spacing between systems. +Not set by default. @cindex @code{interscorelinefill} + + @item @code{interscorelinefill} If set to a positive number, the distance between the score lines will stretch in order to fill the full page. In that case @code{interscoreline} specifies the minimum spacing. - Defaults to 0. + + Not set by default. + + @cindex @code{stafflinethickness} @item @code{stafflinethickness} @@ -2528,7 +3061,7 @@ not take effect if the font is not loaded and selected afterwards. @} @end example -The file "paper16.ly" will now include a file named @file{a4.ly}, which +The file @code{paper16.ly} will now include a file named @file{a4.ly}, which will set the paper variables @code{hsize} and @code{vsize} (used by @code{ly2dvi}) @@ -2553,7 +3086,7 @@ Occasionally you might want to override the automatic breaks; you can do this by specifying @code{\break}. This will force a line break at this point. Do remember that line breaks can only occur at places where there are barlines. If you want to have a line break where there is no -barline, you can force a barline by entering @code{\bar "";}. +barline, you can force an invisible barline by entering @code{\bar "";}. Similarly, @code{\noBreak} forbids a line break at a certain point. @@ -2565,11 +3098,13 @@ the penalty command: \penalty @var{int} @code{;} @end example -This imposes encourages or discourages LilyPond to make a line break -at this point. +This encourages or discourages LilyPond to make a line break at this +point. + +@refbugs -@strong{Warning} do not use @code{\penalty} directly. It is rather -kludgy, and slated for rewriting. +The scaling of the @code{\penalty} argument is not well-defined. The +command is rather kludgy, and slated for rewriting. @c . {Page break} @node Page break @@ -2579,13 +3114,10 @@ kludgy, and slated for rewriting. @cindex breaking pages -Page breaks are normally computed by @TeX{}, so they are not under direct -control. However, you can insert a commands into the @file{.tex} output to -instruct @TeX{} where to break pages. For more details, see the -example file @file{input/test/between-systems.ly} - -[or -> Tricks? ] - +Page breaks are normally computed by @TeX{}, so they are not under +direct control of LilyPond. However, you can insert a commands into the +@file{.tex} output to instruct @TeX{} where to break pages. For more +details, see the example file @file{input/test/between-systems.ly} @@ -2595,10 +3127,24 @@ example file @file{input/test/between-systems.ly} @node Sound @section Sound @cindex Sound + +LilyPond can produce MIDI output. The performance lacks lots of +interesting effects, such as swing, articulation, slurring, tieing, +etc., but it is good enough for proof-hearing the music you enter. + +Dynamics and tempo changes are interpreted. + +[TODO: mention volume control/Instrument Equaliser] + + +@refbugs + +It is currently not possible to use the percussion channel (generally +channel 10 of a MIDI file). + @menu * MIDI block:: * MIDI instrument names:: -* Tempo:: @end menu @c . {MIDI block} @@ -2627,86 +3173,26 @@ Context definitions follow precisely the same syntax as within the The contexts for MIDI output are defined in @file{ly/performer.ly}. -@c . {MIDI instrument names} @node MIDI instrument names @subsection MIDI instrument names + @cindex instrument names @cindex @code{Staff.midiInstrument} @cindex @code{Staff.instrument} The MIDI instrument name is set by the @code{Staff.midiInstrument} property or, if that property is not set, the @code{Staff.instrument} -property. The instrument name should be chosen from the following list. -If the selected string does not exactly match, then LilyPond uses the -default piano. - -[FIXME: to appendix ] - - -@example -"acoustic grand" "contrabass" "lead 7 (fifths)" -"bright acoustic" "tremolo strings" "lead 8 (bass+lead)" -"electric grand" "pizzicato strings" "pad 1 (new age)" -"honky-tonk" "orchestral strings" "pad 2 (warm)" -"electric piano 1" "timpani" "pad 3 (polysynth)" -"electric piano 2" "string ensemble 1" "pad 4 (choir)" -"harpsichord" "string ensemble 2" "pad 5 (bowed)" -"clav" "synthstrings 1" "pad 6 (metallic)" -"celesta" "synthstrings 2" "pad 7 (halo)" -"glockenspiel" "choir aahs" "pad 8 (sweep)" -"music box" "voice oohs" "fx 1 (rain)" -"vibraphone" "synth voice" "fx 2 (soundtrack)" -"marimba" "orchestra hit" "fx 3 (crystal)" -"xylophone" "trumpet" "fx 4 (atmosphere)" -"tubular bells" "trombone" "fx 5 (brightness)" -"dulcimer" "tuba" "fx 6 (goblins)" -"drawbar organ" "muted trumpet" "fx 7 (echoes)" -"percussive organ" "french horn" "fx 8 (sci-fi)" -"rock organ" "brass section" "sitar" -"church organ" "synthbrass 1" "banjo" -"reed organ" "synthbrass 2" "shamisen" -"accordion" "soprano sax" "koto" -"harmonica" "alto sax" "kalimba" -"concertina" "tenor sax" "bagpipe" -"acoustic guitar (nylon)" "baritone sax" "fiddle" -"acoustic guitar (steel)" "oboe" "shanai" -"electric guitar (jazz)" "english horn" "tinkle bell" -"electric guitar (clean)" "bassoon" "agogo" -"electric guitar (muted)" "clarinet" "steel drums" -"overdriven guitar" "piccolo" "woodblock" -"distorted guitar" "flute" "taiko drum" -"guitar harmonics" "recorder" "melodic tom" -"acoustic bass" "pan flute" "synth drum" -"electric bass (finger)" "blown bottle" "reverse cymbal" -"electric bass (pick)" "skakuhachi" "guitar fret noise" -"fretless bass" "whistle" "breath noise" -"slap bass 1" "ocarina" "seashore" -"slap bass 2" "lead 1 (square)" "bird tweet" -"synth bass 1" "lead 2 (sawtooth)" "telephone ring" -"synth bass 2" "lead 3 (calliope)" "helicopter" -"violin" "lead 4 (chiff)" "applause" -"viola" "lead 5 (charang)" "gunshot" -"cello" "lead 6 (voice)" -@end example - +property. The instrument name should be chosen from the list in +@ref{MIDI instruments}. +@refbugs +If the selected string does not exactly match, then LilyPond uses the +default piano. It is not possible to select an instrument by number. -@c . {Tempo} -@node Tempo -@subsection Tempo -@cindex Tempo -@cindex beats per minute -@cindex metronome marking -@cindex @code{\tempo} -@example - \tempo @var{duration} = @var{perminute} @code{;} -@end example -Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests -output with 76 quarter notes per minute. @@ -2718,10 +3204,14 @@ output with 76 quarter notes per minute. @cindex Music entry @menu * Relative:: +* Bar check:: * Point and click:: @end menu - +One of the applications of LilyPond is to enter music from existing +written or printed material. When you're doing this kind of copying +work, you can easily make mistakes. This section deals with tricks and +features that help you enter music, and find and correct mistakes. @c . {Relative} @node Relative @@ -2751,16 +3241,14 @@ This distance is determined without regarding accidentals: a @code{fisis} following a @code{ceses} will be put above the @code{ceses}. -Entering scales is straightforward in relative mode. - -@lilypond[fragment,verbatim,center] +Entering music that changes octave frequently is easy in relative mode. +@lilypond[fragment,singleline,verbatim,center] \relative c'' { - g a b c d e f g g, g + b c d c b c bes a } @end lilypond And octave changing marks are used for intervals greater than a fourth. - @lilypond[fragment,verbatim,center] \relative c'' { c g c f, c' a, e'' } @@ -2785,355 +3273,444 @@ the pitch as a notename, you have to be in note mode, so there must be a surrounding @code{\notes} keyword (which is not shown here). -The relative conversion will not affect @code{\transpose} or -@code{\relative} sections in its argument. If you want to use -relative within transposed music, you must place an additional -@code{\relative} inside the @code{\transpose}. +The relative conversion will not affect @code{\transpose}, +@code{\chords} or @code{\relative} sections in its argument. If you +want to use relative within transposed music, you must place an +additional @code{\relative} inside the @code{\transpose}. + + +@c . {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check + +@cindex bar check +@cindex @code{barCheckNoSynchronize} +@cindex @code{|} + + +Whenever a bar check is encountered during interpretation, a warning +message is issued if it doesn't fall at a measure boundary. This can +help you find errors in the input. Depending on the value of +@code{barCheckNoSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. + +A bar check is entered using the bar symbol, @code{|} + @c . {Point and click} @node Point and click @subsection Point and click -[todo] +Point and click lets you find notes in the input by clicking on them in +the Xdvi window. This makes it very easy to find input that causes some +error in the sheet music. + +To use it, you need the following software + +@itemize +@item +@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain +Xdvi} version 22.36 or newer. + + Note that most @TeX{} distributions ship with xdvik, which is a + different and less well maintained program. To find out which xdvi you + are running, try @code{xdvi --version} or @code{xdvi.bin --version}. +@item emacs +@end itemize + + +Add one these lines to the top of your .ly file. The first one is for +line location only. The second one is more convenient, but requires +patching @code{emacsclient}. + +@example +#(set! point-and-click line-location) +#(set! point-and-click line-column-location) +@end example + +In the emacs startup file (usually @file{~/.emacs}), add the following +@example +(server-start) +@end example + +If you want emacs to jump to the exact spot (and not just the line) on a +click, you must enable column positioning. To do so, you need to patch +emacsclient. Apply @file{emacsclient.patch} (included with the source +package) to @file{emacsclient.c} and @file{server.el} from the emacs +source code. Recompile and stick the recompiled emacsclient into a bin +directory, and put @file{server.el} into a elisp directory +(eg. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs} +init file, before invoking server-start. + +@example + (setq load-path (cons "~/usr/share/emacs" load-path)) +@end example + + +Xdvi must be configured to use the emacs editor. Before starting, set +the environment variable @code{XEDITOR} to +@example +emacsclient --no-wait +%c:%l %f +@end example +Xdvi also must be configured to find the fonts. Refer to the +xdvi documentation for more information. + +When viewing, control-mousebutton 1 will take you to the originating +line and column. Control-mousebutton 2 will show all clickable boxes. + +@refbugs + +When you convert the TeX file to PostScript using dvips, dvips +will complain about not finding @code{src:X:Y} files. Those complaints are +harmless, and can be ignored. + + +@node Interpretation context +@section Interpretation context -@c . {Engravers} -@node Engravers -@section Engravers -@cindex engravers @menu -* Context definitions:: * Notation Contexts:: +* Creating contexts:: +* Default contexts:: +* Context properties:: +* Changing context definitions:: +* Defining new contexts:: @end menu -[rewrite this entirely] -@c . {Context definitions} -@node Context definitions -@subsection Context definitions +@c . {Notation Contexts} +@node Notation Contexts +@subsection Notation Contexts -@cindex context definition -@cindex translator definition -@cindex engraver hacking +@cindex notation contexts +Notation contexts are objects that only exist during a run of LilyPond. +During the interpretation phase of LilyPond (when it prints +"interpreting music"), the music expresiion in a @code{\score} block is +interpreted in time order. This is the same order that humans hear and +play music. -A notation contexts is defined by the following information +During this interpretation, the notation context is holds the state for +the current point within the music. It contains information like -@enumerate 1 - @item A name. +@itemize @bullet + @item What notes are playing at this point? + @item What symbols will be printed at this point? + @item What is the current key signature, time signature, point within + the measure, etc.? +@end itemize - @item The LilyPond modules that do the actual conversion of music to - notation. Each module is a so-called - @emph{engraver} -@cindex engraver -. +Contexts are grouped hierarchically: A @code{Voice} context is +contained in a @code{Staff} context (because a staff can contain +multiple voices at any point), a @code{Staff} context is contained in +a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because +these can all contain multiple staffs). - @item How these modules should cooperate, i.e. which ``cooperation - module'' should be used. This cooperation module is a special - type of engraver. - @item What other contexts the context can contain, +Contexts associated with sheet music output are called @emph{notation +contexts}, those for sound output are called performance contexts. - @item What properties are defined. -@end enumerate -A context definition has this syntax: +@node Creating contexts +@subsection Creating contexts -@example +@cindex @code{\context} +@cindex context selection - \translator @code{@{} - @var{translatorinit} @var{translatormodifierlist} - @code{@}} -@end example +Contexts for a music expression can be selected manually, using the +following music expression. -@var{translatorinit} can be an identifier or @example - \type @var{typename} @code{;} + \context @var{contexttype} [= @var{contextname}] @var{musicexpr} @end example -where @var{typename} is one of -@table @code -@cindex @code{Engraver_group_engraver} - @item @code{Engraver_group_engraver} - The standard cooperation engraver. -@cindex @code{Score_engraver} +This instructs lilypond to interpret @var{musicexpr} within the context + of type @var{contexttype} and with name @var{contextname}. If this +context does not exist, it will be created. - @item @code{Score_engraver} - This is cooperation module that should be in the top level context. -@cindex @code{Grace_engraver_group} +@lilypond[verbatim,singleline] +\score { + \notes \relative c'' { + c4 f + } +} - @item @code{Grace_engraver_group} - This is a special cooperation module (resembling - @code{Score_engraver}) that is used to created an embedded - `miniscore'. -@end table +@end lilypond -@var{translatormodifierlist} is a list of items where each item is -one of +In this example, the @code{c} and @code{d} are printed on the +default staff. For the @code{e}, a context Staff called +@code{another} is specified; since that does not exist, a new +context is created. Within @code{another}, a (default) Voice context +is created for the @code{e4}. When all music referring to a +context is finished, the context is ended as well. So after the +third quarter, @code{another} is removed. -@itemize @bullet - @item @code{\consists} @var{engravername} @code{;} - Add @var{engravername} to the list of modules in this context. - The order of engravers added with @code{\consists} is - significant. - - @item @code{\consistsend} @var{engravername} @code{;} - Analogous to @code{\consists}, but makes sure that - @var{engravername} is always added to the end of the list of - engravers. - Some engraver types need to be at the end of the list; this - insures they are put there, and stay there, if a user adds or - removes engravers. This command is usually not needed for - end-users. - - @item @code{\accepts} @var{contextname} @code{;} - Add @var{contextname} to the list of context this context can - contain. The first listed context is the context to create by - default. - @item @code{\denies}. The opposite of @code{\accepts}. Added for -completeness, but is never used in practice. - - - @item @code{\remove} @var{engravername} @code{;} - Remove a previously added (with @code{\consists}) engraver. - - @item @code{\name} @var{contextname} @code{;} - This sets name of the context, e.g. @code{Staff}, @code{Voice}. If - the name is not specified, the translator won't do anything. +@node Default contexts +@subsection Default contexts - @item @var{propname} @code{=} @var{value} @code{;} - A property assignment. -@end itemize +Most music expressions don't need @code{\context}: they inherit the +notation context from their parent. Each note is a music expression, and +as you can see in the following example, only the sequential music +enclosing the three notes has an explicit context. -In the @code{\paper} block, it is also possible to define translator -identifiers. Like other block identifiers, the identifier can only -be used as the very first item of a translator. In order to define -such an identifier outside of @code{\score}, you must do +@lilypond[verbatim,singleline] +\score { \notes \context Voice = goUp { c'4 d' e' } } +@end lilypond -@quotation +There are some quirks that you must keep in mind when dealing with +defaults: -@example -\paper @{ - foo = \translator @{ @dots{} @} -@} -\score @{ - \notes @{ - @dots{} - @} - \paper @{ - \translator @{ \foo @dots{} @} - @} -@} -@end example +First, every top-level music is interpreted by the Score context, in other +words, you may think of @code{\score} working like +@example + \score @{ + \context Score @var{music} + @} +@end example -@end quotation +Second, sequential music follows the contexts of its +``children''. Consider the following example. +@lilypond[verbatim, singleline] +\score { \context Score \notes { c'4 ( d' )e' } } +@end lilypond -@cindex paper types, engravers, and pre-defined translators +The sequential music is interpreted by the Score context initially +(notice that the @code{\context} specification is redundant), but when a +note is encountered, contexts are setup to accept that note. In this +case, a Thread, Voice and Staff are created. The rest of the sequential +music is also interpreted with the same Thread, Voice and Staff context, +putting the notes on the same staff, in the same voice. -Some pre-defined identifiers can simplify modification of -translators. The pre-defined identifiers are: +This is a convenient mechanism, but do not expect opening chords to work +without @code{\context}. For every note, a separate staff is +instantiated. -@table @code -@cindex @code{StaffContext} - @item @code{StaffContext} - Default Staff context. -@cindex @code{RhythmicStaffContext} +@lilypond[verbatim, singleline] +\score { \notes } +@end lilypond - @item @code{RhythmicStaffContext} - Default RhythmicStaff context. -@cindex @code{VoiceContext} +Of course, if the chord is preceded by a normal note in sequential +music, the chord will be interpreted by the Thread of the preceding +note: +@lilypond[verbatim,singleline] +\score { \notes { c'4 } } +@end lilypond - @item @code{VoiceContext} - Default Voice context. -@cindex @code{ScoreContext} - @item @code{ScoreContext} - Default Score context. -@cindex @code{HaraKiriStaffContext} +@node Context properties +@subsection Context properties - @item @code{HaraKiriStaffContext} - Staff context that does not print if it only contains rests. - Useful for orchestral scores.@footnote{Harakiri, also called - Seppuku, is the ritual suicide of the Japanese Samourai warriors.} +Notation contexts can be modified from within the @file{.ly} file. The +following music expression does that job: -@end table +@cindex @code{\property} +@example + \property @var{contextname}.@var{propname} = @var{value} +@end example -Using these pre-defined values, you can remove or add items to the -translator: +Sets the @var{propname} property of the context @var{contextname} to the +specified Scheme expression @var{value}. All @var{propname} and +@var{contextname} are strings, which are typically unquoted. -@quotation +Properties that are set in one context are inherited by all of the +contained contexts. This means that a property valid for the +@code{Voice} context can be set in the @code{Score} context (for +example) and thus take effect in all @code{Voice} contexts. -@example +Properties can be unset using the following expression: +@example + \property @var{contextname}.@var{propname} \unset +@end example + +This removes the definition of @var{propname} in @var{contextname}. If +@var{propname} was not defined in @var{contextname} (but was inherited +from a higher context), then this has no effect. + + +@refbugs + +@code{\property \unset} is not the inverse of @code{\property \set} + + + + +@c . {Context definitions} +@node Changing context definitions +@subsection Changing context definitions + +@cindex context definition +@cindex translator definition + +The most common way to define a context is by extending an existing +context. You can change an existing context from the paper block, by +first initializing a translator with an existing context identifier: +@example \paper @{ \translator @{ - \StaffContext - \remove Some_engraver; - \consists Different_engraver; - @} -@} -@end example + @var{context-identifier} + @} @} +@end example +Then you can add engravers, remove engravers. +The syntax for these operations are respectively +@example + \remove @var{engravername} + \consists @var{engravername} +@end example -@end quotation - +Here @var{engravername} is a string, the name of an engraver in the +system. +@example + @var{propname} = @var{value} +@end example + +@lilypond[verbatim,singleline] +\score { \notes { + c'4 c'4 } + \paper { + \translator { \StaffContext + \remove Clef_engraver; + } } } +@end lilypond -@c . {Notation Contexts} -@node Notation Contexts -@subsection Notation Contexts +@cindex engraver -@cindex notation contexts +You can also set properties in a translator definition. The syntax is as +follows: -Notation contexts are objects that only exist during a run of -LilyPond. During the interpretation phase of LilyPond, the Music -expression contained in a @code{\score} block is interpreted in time -order. This is the order in which humans read, play, and write -music. +@var{propname} is a string and @var{value} is a Scheme +expression. +@example + @var{propname} = @var{value} + @var{propname} \set @var{symbol} = @var{value} + @var{propname} \override @var{symbol} = @var{value} + @var{propname} \revert @var{symbol} -A context is an object that holds the reading state of the -expression; it contains information like +@end example -@itemize @bullet - @item What notes are playing at this point? - @item What symbols will be printed at this point? - @item In what style will they printed? - @item What is the current key signature, time signature, point within - the measure, etc.? -@end itemize +These type of property assignments happen before interpretation starts, +so a @code{\property} expression will override any predefined settings. -Contexts are grouped hierarchically: A @code{Voice} context is -contained in a @code{Staff} context (because a staff can contain -multiple voices at any point), a @code{Staff} context is contained in -a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because -these can all contain multiple staffs). -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called performance contexts. + To simplify editing translators, all standard contexts have standard +identifiers called @var{name}@code{Context}, e.g. @code{StaffContext}, +@code{VoiceContext}. -Contexts are created either manually or automatically. Initially, the -top level music expression is interpreted by the top level context (the -@code{Score} context). When a atomic music expression (i.e. a note, a -rest, etc.), a nested set of contexts is created that can process these -atomic expressions, as in this example: +@node Defining new contexts +@subsection Defining new contexts -@example -\score @{ \notes @{ c4 @} @} -@end example +If you want to build a context from scratch, you must also supply the +following extra information: +@itemize @bullet + @item A name, specified by @code{\name @var{contextname};}. -The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score} -context. When the note @code{c4} itself is interpreted, a set of -contexts is needed that will accept notes. The default for this is a -@code{Voice} context, contained in a @code{Staff} context. Creation of -these contexts results in the staff being printed. + @item A cooperation module. This is specified by @code{\type +@var{typename};}. +@end itemize -@cindex context +This is an example: +@example +\translator @code{ + \type "Engraver_group_engraver"; + \name "SimpleStaff"; + \alias "Staff"; + \consists "Staff_symbol_engraver"; + \consists "Note_head_engraver"; + \consistsend "Axis_group_engraver"; +}@ +@end example -You can also create contexts manually, and you probably have to do so -if you want to typeset complicated multiple part material. If a -`@code{\context} @var{name} @var{musicexpr}' expression is encountered -during the interpretation phase, the @var{musicexpr} argument will be -interpreted with a context of type @var{name}. If you specify a name, -the specific context with that name is searched. +Basic building blocks of translation are called engravers; they are +special C++ classes. -[type vs id] +The argument of @code{\type} is the name for a special engraver that +handles cooperation between simple engravers such as +@code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives +for this engraver are the following: +@table @code +@cindex @code{Engraver_group_engraver} + @item @code{Engraver_group_engraver} + The standard cooperation engraver. -If a context of the specified type and name can not be found, a new -one is created. For example, +@cindex @code{Score_engraver} -@quotation + @item @code{Score_engraver} + This is cooperation module that should be in the top level context, +and only the toplevel context. -@lilypond[verbatim] -\score { - \notes \relative c'' { - c4 f - } -} +@cindex @code{Grace_engraver_group} -@end lilypond -@end quotation + @item @code{Grace_engraver_group} + This is a special cooperation module (resembling + @code{Score_engraver}) that is used to created an embedded + `miniscore'. +@end table -In this example, the @code{c} and @code{d} are printed on the -default staff. For the @code{e}, a context Staff called -@code{another} is specified; since that does not exist, a new -context is created. Within @code{another}, a (default) Voice context -is created for the @code{e4}. When all music referring to a -context is finished, the context is ended as well. So after the -third quarter, @code{another} is removed. +Other modifiers are -Almost all music expressions inherit their interpretation context -from their parent. In other words, suppose that the syntax for a -music expression is +@itemize @bullet + @item @code{\alias} @var{alternate-name} @code{;} + This specifies a different name. In the above example, +@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s -@example + @item @code{\consistsend} @var{engravername} @code{;} + Analogous to @code{\consists}, but makes sure that + @var{engravername} is always added to the end of the list of + engravers. - \keyword @var{musicexpr1} @var{musicexpr2} @dots{} -@end example + Some engraver types need to be at the end of the list; this + insures they are put there, and stay there, if a user adds or + removes engravers. This command is usually not needed for + end-users. + + @item @code{\accepts} @var{contextname} @code{;} + Add @var{contextname} to the list of context this context can + contain. The first listed context is the context to create by + default. -When the interpretation of this music expression starts, the context -for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total -expression. + @item @code{\denies}. The opposite of @code{\accepts}. Added for +completeness, but is never used in practice. + + + @item @code{\name} @var{contextname} @code{;} + This sets name of the context, e.g. @code{Staff}, @code{Voice}. If + the name is not specified, the translator won't do anything. +@end itemize -Lastly, you may wonder, why this: +In the @code{\paper} block, it is also possible to define translator +identifiers. Like other block identifiers, the identifier can only +be used as the very first item of a translator. In order to define +such an identifier outside of @code{\score}, you must do @quotation - @example +\paper @{ + foo = \translator @{ @dots{} @} +@} \score @{ - \notes \relative c'' @{ - c4 d4 e4 + \notes @{ + @dots{} + @} + \paper @{ + \translator @{ \foo @dots{} @} @} @} @end example @end quotation -doesn't result in this: - -@lilypond[] - - \score { - \notes \relative c'' { - - } - } - -@end lilypond - -For the @code{c4}, a default @code{Staff} (with a contained -@code{Voice}) context is created. After the @code{c4} ends, no -music refers to this default staff, so it would be ended, with the -result shown. To prevent this inconvenient behavior, the context to -which the sequential music refers is adjusted during the -interpretation. So after the @code{c4} ends, the context of the -sequential music is also the default @code{Voice} context. -The @code{d4} gets interpreted in the same context -as @code{c4}. -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@code{Voice} context can be set in the @code{Score} context (for -example) and thus take effect in all @code{Voice} contexts. - -Properties can be preset within the @code{\translator} block -corresponding to the appropriate context. In this case, the syntax -is - -@example - @var{propname} @code{=} @var{value} -@end example +@cindex paper types, engravers, and pre-defined translators -This assignment happens before interpretation starts, so a -@code{\property} expression will override any predefined settings. + -The property settings are used during the interpretation phase. They -are read by the LilyPond modules where interpretation contexts are -built of. These modules are called @emph{translators}. Translators for -notation are called @emph{engravers}, and translators for sound are -called @emph{performers}. @@ -3141,11 +3718,15 @@ called @emph{performers}. @node Syntactic details @section Syntactic details @cindex Syntactic details + +This section describes details that were too boring to be put elsewhere. + @menu * Top level:: * Identifiers:: +* Music expressions:: +* Manipulating music expressions:: * Assignments:: -* Lexical details:: * Lexical modes:: * Ambiguities:: @end menu @@ -3158,7 +3739,10 @@ called @emph{performers}. This section describes what you may enter at top level. -@unnumberedsubsec Score definition +@c . {Score} +@subsubsection Score +@cindex Score + @cindex score definition The output is generated combining a music expression with an output @@ -3168,42 +3752,37 @@ definition. A score block has the following syntax: \score @{ @var{musicexpr} @var{outputdefs} @} @end example -@var{outputdefs} are zero or more output definitions. If no output -definition is supplied, the default @code{\paper} block will be added. +@var{outputdefs} are zero or more output definitions. If none is +supplied, the default @code{\paper} block will be added. -@c . {Score} -@subsubsection Score -@cindex Score -@c . {Paper} -@subsubsection Paper -@cindex Paper +@c . {Default output} +@subsubsection Default output -@c . {Midi} -@subsubsection Midi -@cindex Midi +Default values for the @code{\paper} and @code{\midi} block are set by +entering such a block at top-level. @c . {Header} @subsubsection Header @cindex Header @cindex @code{\header} -The syntax is +A header describes bibilographic information of the file's contents. It +can also appear in a @code{\score} block. Tools like @code{ly2dvi} can +use this information for generating titles. Key values that are used by +@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, +metre, arranger, piece and tagline. + +@cindex @code{ly2dvi} + +The syntax is @example \header @{ @var{key1} = @var{val1}; -@cindex @code{ly2dvi} @var{key2} = @var{val2}; @dots{} @} @end example - -A header describes the file's contents. It can also appear in a -@code{\score} block. Tools like @code{ly2dvi} can use this -information for generating titles. Key values that are used by -@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, -metre, arranger, piece and tagline. - It is customary to put the @code{\header} at the top of the file. @subsubsection Default output @@ -3221,35 +3800,175 @@ All of the information in a LilyPond input file, is represented as a Scheme value. In addition to normal Scheme data types (such as pair, number, boolean, etc.), LilyPond has a number of specialized data types, -@itemize @bullet -@item Input -@item c++-function -@item Music -@item Identifier -@item Translator_def -@item Duration -@item Pitch -@item Score -@item Music_output_def -@item Moment (rational number) -@end itemize +@itemize @bullet +@item Input +@item c++-function +@item Music +@item Identifier +@item Translator_def +@item Duration +@item Pitch +@item Score +@item Music_output_def +@item Moment (rational number) +@end itemize + +LilyPond also includes some transient object types. Objects of these +types are built during a LilyPond run, and do not `exist' per se within +your input file. These objects are created as a result of your input +file, so you can include commands in the input to manipulate them, +during a lilypond run. + +@itemize @bullet +@item Grob: short for Graphical object. See @ref{Grobs}. +@item Molecule: device-independent page output object, +including dimensions. Produced by some Grob functions +See @ref{Molecules} +@item Translator: object that produces audio objects or Grobs. This is +not yet user accessible. +@item Font_metric: object representing a font. (See @ref{Font metrics}) + +@end itemize + + +@node Music expressions +@subsection Music expressions + +@cindex music expressions + +Music in LilyPond is entered as a music expression. Notes, rests, lyric +syllables are music expressions, and you can combine music expressions +to form new ones, for example by enclosing a list of expressions in +@code{\sequential @{ @}} or @code{< >}. In the following example, a +compound expression is formed out of the quarter note @code{c} and a +quarter note @code{d}: + +@example +\sequential @{ c4 d4 @} +@end example + +@cindex Sequential music +@cindex @code{\sequential} +@cindex sequential music +@cindex @code{<} +@cindex @code{>} +@cindex Simultaneous music +@cindex @code{\simultaneous} + +The two basic compound music expressions are simultaneous and +sequential music. + +@example + \sequential @code{@{} @var{musicexprlist} @code{@}} + \simultaneous @code{@{} @var{musicexprlist} @code{@}} +@end example +For both, there is a shorthand: +@example + @code{@{} @var{musicexprlist} @code{@}} +@end example +for sequential and +@example + @code{<} @var{musicexprlist} @code{>} +@end example +for simultaneous music. +In principle, the way in which you nest sequential and simultaneous to +produce music is not relevant. In the following example, three chords +are expressed in two different ways: + +@lilypond[fragment,verbatim,center] + \notes \context Voice { + + < { a b c' } { c' d' e' } > + } +@end lilypond + + +Other compound music expressions include +@example + \repeat @var{expr} + \transpose @var{pitch} @var{expr} + \apply @var{func} @var{expr} + \context @var{type} = @var{id} @var{expr} + \times @var{fraction} @var{expr} +@end example + + +@c . {Manipulating music expressions} +@node Manipulating music expressions +@subsection Manipulating music expressions + +The @code{\apply} mechanism gives you access to the internal +representation of music. You can write Scheme-functions that operate +directly on it. The syntax is +@example + \apply #@var{func} @var{music} +@end example +This means that @var{func} is applied to @var{music}. The function +@var{func} should return a music expression. + +This example replaces the text string of a script. It also shows a dump +of the music it processes, which is useful if you want to know more +about how music is stored. +@lilypond[verbatim] +#(define (testfunc x) + (if (equal? (ly-get-mus-property x 'text) "foo") + (ly-set-mus-property x 'text "bar")) + ;; recurse + (ly-set-mus-property x 'elements + (map testfunc (ly-get-mus-property x 'elements))) + (display x) + x +) +\score { \notes + \apply #testfunc { c4_"foo" } +} +@end lilypond + +For more information on what is possible, see the @ref{Tricks} and the +automatically generated documentation. + + +Directly accessing internal representations is dangerous: the +implementation is subject to changes, so you should avoid this feature +if possible. + + + +@c . {Span requests} +@menu +* Span requests:: +@end menu + +@node Span requests +@subsubsection Span requests +@cindex Span requests + +Notational constructs that start and end on different notes can be +entered using span requests. The syntax is as follows: + + +@example + \spanrequest @var{startstop} @var{type} +@end example + + +@cindex @code{\start} +@cindex @code{\stop} -LilyPond also includes some transient object types. Objects of these -types are built during a LilyPond run, and do not `exist' per se within -your input file. These objects are created as a result of your input -file, so you can include commands in the input to manipulate them, -during a lilypond run. +This defines a spanning request. The @var{startstop} parameter is either +-1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that +describes what should be started. Much of the syntactic sugar is a +shorthand for @code{\spanrequest}, for example, -@itemize @bullet -@item Grob: short for Graphical object. See @ref{Grobs}. -@item Molecule: device-independent page output object, -including dimensions. Produced by some Grob functions -See @ref{Molecules} -@item Translator: object that produces audio objects or Grobs. This is -not yet user accessible. -@item Font_metric: object representing a font. (See @ref{Font metrics}) +@lilypond[fragment,verbatim,center] + c'4-\spanrequest \start "slur" + c'4-\spanrequest \stop "slur" +@end lilypond -@end itemize +Among the supported types are @code{crescendo}, @code{decrescendo}, +@code{beam}, @code{slur}. This is an internal command. Users are +encouraged to use the shorthands which are defined in the initialization +file @file{spanners.ly}. @c . {Assignments} @@ -3287,35 +4006,134 @@ copied. For this reason, an identifier reference must always be the first item in a block. @example \paper @{ - foo = 1.0 - \paperIdent % wrong and invalid + foo = 1.0 + \paperIdent % wrong and invalid @} \paper @{ - \paperIdent % correct - foo = 1.0 @} + \paperIdent % correct + foo = 1.0 @} @end example + +@c . {Lexical modes} +@node Lexical modes +@subsection Lexical modes +@cindex Lexical modes +@cindex input mode +@cindex mode, input +@cindex @code{\notes} +@cindex @code{\chords} +@cindex @code{\lyrics} + +To simplify entering notes, lyrics, and chords, LilyPond has three +special input modes on top of the default mode: note, lyrics and chords +mode. These input modes change the way that normal, unquoted words are +interpreted: for example, the word @code{cis} may be interpreted as a +C-sharp, as a lyric syllable `cis' or as a C-sharp major triad +respectively. + +A mode switch is entered as a compound music expressions +@example +@code{\notes} @var{musicexpr} +@code{\chords} @var{musicexpr} +@code{\lyrics} @var{musicexpr}. +@end example + +In each of these cases, these expressions do not add anything to the +meaning of their arguments. They are just a way to indicate that the +arguments should be parsed in indicated mode. The modes are treated in +more detail in the @ref{Note entry}, @ref{Lyrics} and +@ref{Chords}. + +You may nest different input modes. + +@c . {Ambiguities} +@node Ambiguities +@subsection Ambiguities +@cindex ambiguities +@cindex grammar + + +The grammar contains a number of ambiguities. We hope to resolve them at +some time. + +@itemize @bullet + @item The assignment + + @example +foo = bar +@end example + + can be interpreted as making a string identifier @code{\foo} + containing @code{"bar"}, or a music identifier @code{\foo} + containing the syllable `bar'. + + @item The assignment + + @example +foo = -6 +@end example + + can be interpreted as making an integer identifier + containing -6, or a Request identifier containing the + fingering `6' (with neutral direction). + + @item If you do a nested repeat like + + @quotation + +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example + + @end quotation + + then it is ambiguous to which @code{\repeat} the + @code{\alternative} belongs. This is the classic if-then-else + dilemma. It may be solved by using braces. + + @item (an as yet unidentified ambiguity :-) +@end itemize + + @c . {Lexical details} @node Lexical details -@subsection Lexical details -@cindex Lexical details +@section Lexical details + +Even more boring details, now on lexical side of the input parser. + @menu +* Comments:: +* Direct Scheme:: +* Keywords:: +* Integers:: +* Reals:: +* Strings:: +* Main input:: +* File inclusion:: +* Version information:: @end menu -@c . {Comments} -@subsubsection Comments -@cindex Comments -@cindex @code{%} +@node Comments +@subsection Comments +@cindex comments +@cindex block comment +@cindex line comment + +@cindex @code{%} A one line comment is introduced by a @code{%} character. Block comments are started by @code{%@{} and ended by @code{%@}}. They cannot be nested. -@c . {Direct Scheme} -@subsubsection Direct Scheme +@node Direct Scheme +@subsection Direct Scheme + @cindex Scheme @cindex GUILE @cindex Scheme, in-line code @@ -3343,8 +4161,8 @@ the website @uref{http://www.schemers.org/} for more information on Scheme. -@c . {Keywords} -@subsubsection Keywords +@node Keywords +@subsection Keywords @cindex Keywords @@ -3364,8 +4182,8 @@ script stylesheet skip textscript tempo translator transpose type @end example -@c . {Integers} -@subsubsection Integers +@node Integers +@subsection Integers @cindex integers @cindex @code{+} @@ -3377,8 +4195,8 @@ Formed from an optional minus sign followed by digits. Arithmetic operations cannot be done with integers, and integers cannot be mixed with reals. -@c . {Reals} -@subsubsection Reals +@node Reals +@subsection Reals @cindex real numbers @@ -3400,11 +4218,11 @@ by a @emph{required} decimal point and an optional exponent such as A real constant can be followed by one of the dimension keywords: @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters, points, inches and centimeters, respectively. This converts the number -to a real that is the internal representation of dimensions. +a number that is the internal representation of that dimension. -@c . {Strings} -@subsubsection Strings +@node Strings +@subsection Strings @cindex string @cindex concatenate @@ -3420,8 +4238,8 @@ The tokenizer accepts the following commands. They have no grammatical function, hence they can appear anywhere in the input. -@c . {Main input} -@subsubsection Main input +@node Main input +@subsection Main input @cindex Main input @cindex @code{\maininput} @@ -3429,11 +4247,8 @@ function, hence they can appear anywhere in the input. The @code{\maininput} command is used in init files to signal that the user file must be read. This command cannot be used in a user file. -@c . {File inclusion} -@subsubsection Main input -@cindex Main input - -@subsubsection File inclusion +@node File inclusion +@subsection File inclusion @cindex @code{\include} @example \include @var{filename} @@ -3443,7 +4258,9 @@ Include @var{filename}. The argument @var{filename} may be a quoted string (an unquoted string will not work here!) or a string identifier. The full filename including the @file{.ly} extension must be given, -@subsubsection Version information + +@node Version information +@subsection Version information @cindex @code{\version} @example \version @var{string} ; @@ -3458,185 +4275,6 @@ See @ref{convert-ly} for more information on @code{convert-ly}. @cindex convert-ly -@c . {Pitch names} -@subsubsection Defining pitch names -@cindex Lexical modes -@cindex definining pitch names -@cindex pitch names, definining -@cindex note names -@cindex chord modifier names - -A @code{\paper} block at top level sets the default paper block. A -@code{\midi} block at top level works similarly. - -@c . {Assignments} -@subsubsection Assignments -@cindex assignments -@cindex @code{#} - -Identifier assignments may appear at top level. @ref{Assignments} - - - -@c . {Direct scheme} -@subsubsection Direct scheme -@cindex Direct scheme - -Scheme statements maybe issued to produce interesting side-effects. - - -@c . {Lexical modes} -@node Lexical modes -@subsection Lexical modes -@cindex Lexical modes -@cindex input mode -@cindex mode, input -@cindex @code{\notes} -@cindex @code{\chords} -@cindex @code{\lyrics} - -To simplify entering notes, lyrics, and chords, LilyPond has three -special input modes on top of the default mode: note, lyrics and chords -mode. These input modes change the way that normal, unquoted words are -interpreted: for example, the word @code{cis} may be interpreted as a -C-sharp, as a lyric syllable `cis' or as a C-sharp major triad -respectively. - -A mode switch is entered as a compound music expressions -@example -@code{\notes} @var{musicexpr} -@code{\chords} @var{musicexpr} -@code{\lyrics} @var{musicexpr}. -@end example - -In each of these cases, these expressions do not add anything to the -meaning of their arguments. They are just a way to indicate that the -arguments should be parsed in indicated mode. The modes are treated in -more detail in the sections @ref{Note entry}, @ref{Lyrics} and -@ref{Chords}. - -You may nest different input modes. - -@c . {Ambiguities} -@node Ambiguities -@subsection Ambiguities -@cindex ambiguities -@cindex grammar - - -The grammar contains a number of ambiguities. We hope to resolve them at -some time. - -@itemize @bullet - @item The assignment - - @example -foo = bar -@end example - - can be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. - - @item The assignment - - @example -foo = -6 -@end example - - can be interpreted as making an integer identifier - containing -6, or a Request identifier containing the - fingering `6' (with neutral direction). - - @item If you do a nested repeat like - - @quotation - -@example -\repeat @dots{} -\repeat @dots{} -\alternative -@end example - - @end quotation - - then it is ambiguous to which @code{\repeat} the - @code{\alternative} belongs. This is the classic if-then-else - dilemma. It may be solved by using braces. - - @item (an as yet unidentified ambiguity :-) -@end itemize - - - - -@c . {Unsorted} -@node Unsorted -@section Unsorted - -[mucho todo] - -Translation? - -@cindex properties -@unnumberedsubsec Translation property - -[todo: add \set/\override/\revert] - - -@cindex @code{\property} -@example - \property @var{contextname}.@var{propname} = @var{value} -@end example - -Sets the @var{propname} property of the context @var{contextname} to -the specified @var{value}. All three arguments are strings. -Depending on the context, it may be necessary to quote the strings or -to leave space on both sides of the dot. - - -@cindex output properties -@unnumberedsubsec Output properties - -These allow you to tweak what is happening in the back-end -directly. If you want to control every detail of the output -formatting, this is the feature to use. The downside to this is that -you need to know exactly how the backend works. Example: - - -@lilypond[fragment,verbatim] -\relative c'' { c4 - \context Staff \outputproperty - #(make-type-checker 'note-head-interface) - #'extra-offset = #'(0.5 . 0.75) - } -@end lilypond - -This selects all note heads occurring at current staff level, and sets -the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting them -up and right. - -Use of this feature is entirely on your own risk: if you use this, the -result will depend very heavily on the implementation of the backend, -which we change regularly and unscrupulously. - - -Don't move the finger 2, only text "m.d." ... -@lilypond[verbatim] -#(define (make-text-checker text) - (lambda (grob) (equal? text (ly-get-elt-property grob 'text)))) - -\score { - \notes\relative c''' { - \property Voice.Stem \set #'direction = #1 - \outputproperty #(make-text-checker "m.d.") - #'extra-offset = #'(-3.5 . -4.5) - a^2^"m.d." - } - \paper { linewidth = -1.; } -} -@end lilypond -