X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=20f2dd6b06ffdf1cf00db4dacef7b8524287679e;hb=d182d030b396d66a84efa13d947fbbdfb7240874;hp=139209c90dbe0a7ac514efc3f748eb1e467eb62f;hpb=e5990be98bd154f5dd6b2aa8259a56c546168450;p=lilypond.git diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 139209c90d..20f2dd6b06 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,6 +1,4 @@ - - -@c Note: +@c Note: -*-texinfo-*- @c @c A menu is needed before every deeper *section nesting of @node's; run @c M-x texinfo-all-menus-update @@ -14,26 +12,6 @@ @end macro -@ifhtml -@macro internalsref{NAME} -@uref{../lilypond-internals/\NAME\.html,\NAME\} -@cindex \NAME\ -@end macro -@macro seeinternals{NAME} -See @internalsref{\NAME\} -@end macro -@end ifhtml - - -@ifnothtml -@macro seeinternals{NAME} -@end macro -@macro internalsref{NAME} -\NAME\ -@cindex \NAME\ - -@end macro -@end ifnothtml @c .{Reference Manual} @@ -49,105 +27,49 @@ revision of this document was made for LilyPond 1.4.1. It supposes a passing familiarity with how LilyPond input works. New users are encouraged to study the tutorial first. -The reference manual is ordered according to different tasks. -More details on the property setting mechanisms and context handling is -provided in @ref{Tuning output} and @ref{Interpretation context}. The -syntactical details are described at the end of the manual. @menu -* Overview:: * Note entry:: +* Easier music entry:: * Staff notation:: * Polyphony:: * Beaming:: +* Accidentals:: * Expressive marks:: * Ornaments:: * Repeats:: * Rhythmic music:: * Piano music:: -* Lyrics:: +* Tablatures:: * Chords:: * Writing parts:: -* Custodes:: -* Figured bass:: +* Ancient notation :: * Tuning output:: -* Page layout:: -* Output formats:: +* Global layout:: * Sound:: -* Music entry:: -* Skipping corrected music:: -* Interpretation context:: -* Syntactic details:: -* Lexical details:: @end menu -@c . {Overview} -@node Overview -@section Overview - - -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 aesthetic 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'. - -LilyPond is linked to GUILE, GNU's Scheme library for extension -programming. The Scheme library provides the glue that holds together -the low-level routines and separate modules which are written in 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 @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. The result of this step is a typesetting -specification. - -@item typesetting: -The typesetting specification is solved: positions and formatting is -calculated. - -@item the visible results ("virtual ink") are written to the output file. -@end itemize - -During these stages different types of data play the the main role: -during parsing, @strong{Music} objects are created. During the -interpretation, @strong{contexts} are constructed, and with these contexts -a network of @strong{graphical objects} (``grobs'') is created. These -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 -design of the program. - @c FIXME: Note entry vs Music entry at top level menu is confusing. @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 obligatory lint such as @code{\score} blocks and -@code{\paper} declarations. +The most basic forms of music are notes. Notes on their own don't +form valid input, but for the sake of brevity we omit @code{\score} +blocks and @code{\paper} declarations. @menu * Notes:: * Pitches:: +* Chromatic alterations:: * Rests:: * Skips:: * Durations:: * Ties:: +* Automatic note splitting :: * Tuplets:: -* Defining pitch names:: * Easy Notation note heads :: @end menu @@ -155,31 +77,12 @@ brevity we omit obligatory lint such as @code{\score} blocks and @node Notes @subsection Notes -A note specification has the form - -@example - @var{pitch}[!][?][@var{duration}] -@end example - -The alteration refers to what note is heard, not to whether an -accidental is printed. This is done depending on the key and context. -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 -@cindex parenthesized 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'! +A note is printed by specifying its pitch, and then its duration. +@lilypond[fragment,verbatim] + cis'4 d'8 e'16 c'16 @end lilypond -The grob for a note head is called @internalsref{NoteHead}. - - @c . {Pitches} @node Pitches @subsection Pitches @@ -196,7 +99,7 @@ The verbose syntax for pitch specification is \pitch @var{scmpitch} @end example -@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}. +@var{scmpitch} is a pitch scheme object. 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 @@ -226,6 +129,8 @@ 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 +espanol.ly do re mi fa sol la sib si -s -b + @end example @cindex @code{'} @@ -242,6 +147,23 @@ octave; each @code{,} lowers the pitch by an octave. c' c'' es' g' as' gisis' ais' @end lilypond +@node Chromatic alterations +@subsection Chromatic alterations + +Normally, accidentals are printed automatically, but you may force +accidentals in the following ways: 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 +@cindex parenthesized accidental +i.e., an accidental within parentheses can be obtained by adding the +question mark `@code{?}' after the pitch. + +The automatic production of accidentals can be tuned in many +ways. Refer to @ref{Accidentals} for more information. + @c . {Rests} @node Rests @subsection Rests @@ -253,8 +175,8 @@ A rest is entered like a note, with note name `@code{r}': r1 r2 r4 r8 @end lilypond -The grob is @internalsref{Rest}. Whole bar rests centered in the bar are -specified using @code{R}, see @ref{Multi measure rests}. +Whole bar rests centered in the bar are specified using @code{R}, see +@ref{Multi measure rests}. See also @seeinternals{Rest}. For polyphonic music, it can be convenient to specify the rest position directly. You can do that by entering a note, with the keyword @@ -274,13 +196,14 @@ a'4\rest d'4\rest @cindex Space note An invisible rest, or skip, can be entered like a note with note name -`@code{s}': +@code{s}, or with @code{\skip @var{duration}}: @lilypond[singleline,verbatim] -a2 s4 a4 s1 a4 +a2 s4 a4 \skip 1 a4 @end lilypond -Actually, this is a shorthand for the @code{\skip} command, and it is +The @code{s} syntax is only available in Note mode and Chord mode. +In other situations, you should use the @code{\skip} command, and it is only available in Note mode and Chord mode. @c FIXME: in lyrics mode, we have " " and _ @@ -305,7 +228,8 @@ note mode: } @end lilypond -Note that the skip does not produce any output, not even transparent output. +The skip command is merely a empty musical placeholder. It does not +produce any output, not even transparent output. @c . {Durations} @@ -316,13 +240,6 @@ Note that the skip does not produce any output, not even transparent output. @cindex duration @cindex @code{\duration} -The syntax for a verbose duration specification is -@example - \duration @var{scmduration} -@end example -Here, @var{scmduration} is a Scheme object of type @code{Duration}. See -@ref{Duration} for more information. - In Note, Chord, and Lyrics mode, durations may be designated by numbers and dots: durations are entered as their reciprocal values. For notes @@ -356,16 +273,6 @@ r1 r2 r4 r8 r16 r32 r64 r64 } @end lilypond - To get a longa note head, you have to use mensural note heads. This -is accomplished by setting the @code{style} property of the -NoteHead grob to @code{mensural}. There is also a note head style -@code{baroque} which gives mensural note heads for @code{\longa} and -@code{\breve} but standard note heads for shorter notes. - -@lilypond[fragment,singleline,verbatim] - \property Voice.NoteHead \set #'style = #'mensural - a'\longa -@end lilypond 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 @@ -383,7 +290,18 @@ You can alter the length of duration by a fraction @var{N/M} by appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This will not affect the appearance of the notes or rests produced. +Durations can also be produced through GUILE extension mechanism. +@lilypond[verbatim,fragment] + c\duration #(make-duration 2 1) +@end lilypond + + +@refbugs +Dot placement for chords is not perfect. In some cases, dots overlap: +@lilypond[] + \context Voice { } +@end lilypond @node Ties @@ -393,19 +311,21 @@ will not affect the appearance of the notes or rests produced. @cindex ties @cindex @code{~} -A tie connects two adjacent note heads of the same pitch. When used -with chords, it connects all 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 then no ties will be -created. +A tie connects two adjacent note heads of the same pitch. The tie in +effect extends the length of a note. A tie is entered with @code{~}. @lilypond[fragment,verbatim,center] e' ~ e' ~ @end lilypond -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: +When ties are used with chords, all note heads whose pitches match are +connected. Ties are indicated using the tilde symbol `@code{~}'. If +you try to tie together chords which have no common pitches then no +ties will be created. + +If you want less ties created for a chord, you can set +@code{Voice.sparseTies} to true. In this case, a single tie is used +for every tied chord. @lilypond[fragment,verbatim,center] \property Voice.sparseTies = ##t ~ @@ -418,20 +338,51 @@ exactly the same concept. @lilypond[fragment, singleline] \time 3/4 c'2. c'2 ~ c'4 @end lilypond +Ties should not be confused with slurs, which indicate articulation, +and phrasing slurs, which indicate musical phrasing. + +See also @seeinternals{Tie}. -The name of the tie grob is @internalsref{Tie}, and it is created in the -@internalsref{Voice} context. @refbugs -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. +At present, the tie is represented as a separate event, temporally +located in between the notes. 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 the Thread context and turning on and off +ties per Thread. -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 the Thread -context and turning on and off ties per Thread. +Switching staffs when a tie is active will not work. + +@node Automatic note splitting +@subsection Automatic note splitting +@c FIXME: This subsection doesn't belong in @ref{Note entry}. + +There is a facility for automatically converting long notes to tied +notes. This is done by replacing the @code{Note_heads_engraver} by the +@code{Completion_heads_engraver}. + +@lilypond[verbatim,center] +\score{ + \notes\relative c'{ \time 2/4 + c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 + } + \paper{ \translator{ + \ThreadContext + \remove "Note_heads_engraver" + \consists "Completion_heads_engraver" + } } } +@end lilypond + +This engraver splits all running notes at the bar line, and inserts +ties. One of its uses is to debug complex scores: if the measures are +not entirely filled, then the ties exactly show how much each measure +is off. + +@refbugs +Not all durations (especially those containing tuplets) can be +represented exactly; the engraver will not insert tuplets. @node Tuplets @subsection Tuplets @@ -473,48 +424,16 @@ denominator, but if you set it to the Scheme function @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den} instead. -The typesetting of brackets and numbers is controlled by the properties -@code{tuplet-bracket-visibility} and @code{tuplet-number-visibility}. - -@lilypond[fragment, relative, singleline, verbatim] -\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t -\times 2/3{c'8 d e} \times 2/3{d4 e8} -\property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam -\times 2/3{c d e} \times 2/3{d4 e8} -\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f -\times 2/3{c d e} \times 2/3{d4 e8} -\property Voice.TupletBracket \set #'tuplet-number-visibility = ##f -\times 2/3{c d e} \times 2/3{d4 e8} -\property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam -\times 2/3{c d e} \times 2/3{d4 e8} -@end lilypond @cindex @code{tupletNumberFormatFunction} @cindex tuplet formatting -Tuplet brackets are printed as @internalsref{TupletBracket} grobs, most -often in the @internalsref{Voice} context. - -@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 customized 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 also @seeinternals{TupletBracket}. -See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for -specific examples on how to do this. +@refbugs +Nested tuplets are not formatted automatically. In this case, outer +tuplet brackets should be moved automatically. @node Easy Notation note heads @subsection Easy Notation note heads @@ -526,185 +445,418 @@ 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. -@lilypond[singleline,verbatim] -\include "paper23.ly" +@lilypond[singleline,verbatim,26pt] \score { \notes { c'2 e'4 f' | g'1 } \paper { \translator { \EasyNotation } } } @end lilypond -Note that @internalsref{EasyNotation} overrides a @internalsref{Score} context. You -probably will want to print it with magnification to make it more -readable, see @ref{Output scaling}. +Note that @code{EasyNotation} overrides a @internalsref{Score} context. You +probably will want to print it with magnification or a large font size to make it more +readable. @cindex Xdvi @cindex ghostscript -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 produces the correct result. +If you view the result with Xdvi, then staff lines will show through +the letters. Printing the PostScript file obtained with ly2dvi does +produce the correct result. + + +@node Easier music entry +@section Easier music entry +@cindex Music entry +@menu +* Graphical interfaces:: +* Relative octaves:: +* Bar check:: +* Point and click:: +* Skipping corrected music:: +@end menu +When entering music with LilyPond, it is easy to introduce errors. This +section deals with tricks and features that help you enter music, and +find and correct mistakes. +@node Graphical interfaces +@subsection Graphical interfaces -@node Staff notation -@section Staff notation +@cindex GUI +@cindex graphical interface +@cindex sequencer +@cindex RoseGarden +@cindex Denemo +@cindex NoteEdit +@cindex MIDI -@cindex Staff notation +One way to avoid entering notes using the keyboard is to use a +graphical user interface. The following programs are known to have +a lilypond export option: -@menu -* Key signature:: -* Clef:: -* Time signature:: -* Unmetered music:: -* Bar lines:: -@end menu +@itemize @bullet +@item +@uref{http://denemo.sourceforge.net/, Denemo} was once intended as +a LilyPond graphical user interface. It run on Gnome/GTK. +@item +@uref{http://rnvs.informatik.tu-chemnitz.de/~jan/noteedit/noteedit.html, Noteedit} + is a graphical score editor that runs under KDE/Qt. +@item +@uref{http://rosegarden.sf.net/, RoseGarden} + was the inspiration for naming LilyPond. Nowadays it has been +rewritten from scratch and supports LilyPond export as of version +0.1.6. +@end itemize -@c . {Key} -@node Key signature -@subsection Key signature -@cindex Key +Another option is to enter the music using your favorite MIDI +sequencer, and then import it using midi2ly. midi2ly is described in +@ref{Invoking midi2ly}. -@cindex @code{\key} +@c . {Relative} +@node Relative octaves +@subsection Relative octaves +@cindex Relative +@cindex relative octave specification -Setting or changing the key signature is done with the @code{\key} -command. +Octaves are specified by adding @code{'} and @code{,} to pitch names. +When you copy existing music, it is easy to accidentally put a pitch in +the wrong octave and hard to find such an error. To prevent these +errors, LilyPond features octave entry. + +@cindex @code{\relative} @example - @code{\key} @var{pitch} @var{type} + \relative @var{startpitch} @var{musicexpr} @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} +The octave of notes that appear in @var{musicexpr} are calculated as +follows: If no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or less +(This distance is determined without regarding alterations; a +@code{fisis} following a @code{ceses} will be put above the +@code{ceses}) -Here, @var{type} should be @code{\major} or @code{\minor} to get -@var{pitch}-major or @var{pitch}-minor, respectively. -The standard mode names @code{\ionian}, -@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, -@code{\phrygian}, and @code{\dorian} are also defined. +The octave changing marks @code{'} and @code{,} can be added to raise or +lower the pitch by an extra octave. Upon entering relative mode, an +absolute starting pitch must be specified that will act as the +predecessor of the first note of @var{musicexpr}. -This command sets the context property @code{Staff.keySignature}. -Non-standard key signatures can be specified by setting this property -directly. +Entering music that changes octave frequently is easy in relative mode. +@lilypond[fragment,singleline,verbatim,center] + \relative c'' { + b c d c b c bes a + } +@end lilypond -The printed signature is a @internalsref{KeySignature} grob, typically -created in @internalsref{Staff} context. +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'' } +@end lilypond -@cindex @code{keySignature} +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord. However, other notes +within the second chord are determined by looking at the immediately +preceding note. -@c . {Clef} -@node Clef -@subsection Clef -@cindex @code{\clef} +@lilypond[fragment,verbatim,center] + \relative c' { + c + + + } +@end lilypond +@cindex @code{\notes} -The clef can be set or changed with the @code{\clef} command. -@example - \clef @var{clefname} -@end example +The pitch after the @code{\relative} contains a note name. To parse +the pitch as a note name, you have to be in note mode, so there must +be a surrounding @code{\notes} keyword (which is not +shown here). -Shortcut for +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}. -@example - \property Staff.clefGlyph = @var{glyph associated with clefname} - \property Staff.clefPosition = @var{clef Y-position for clefname} - \property Staff.centralCPosition = @var{position for central C} - \property Staff.clefOctavation = @var{extra transposition of clefname} -@end example +@c . {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check -Any change in these properties creates a clef (A @internalsref{Clef} grob). +@cindex bar check +@cindex @code{barCheckSynchronize} +@cindex @code{|} -Supported clef-names include -@c Moved standard clefs to the top /MB -@table @code -@item treble, violin, G, G2 -G clef on 2nd line -@item alto, C - C clef on 3rd line -@item tenor - C clef on 4th line -@item bass, F - F clef on 4th line -@item french - G clef on 1st line, so-called French violin clef -@item soprano - C clef on 1st line -@item mezzosoprano - C clef on 2nd line -@item baritone - C clef on 5th line -@item varbaritone - F clef on 3rd line -@item subbass - F clef on 5th line -@item percussion - percussion clef -@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{barCheckSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. -By adding @code{_8} or @code{^8} to the clef name, the clef is -transposed one octave down or up, respectively. Note that you have to -enclose @var{clefname} in quotes if you use underscores or digits in the -name. For example, +A bar check is entered using the bar symbol, @code{|}: @example - \clef "G_8" -@end example + \time 3/4 c2 e4 | g2. +@end example -Supported associated glyphs (for @code{Staff.clefGlyph}) are: -@table @code -@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 + +@cindex skipTypesetting + +Failed bar checks are most often caused by entering incorrect +durations. Incorrect durations often completely garble up the score, +especially if it is polyphonic, so you should start correcting the score +by scanning for failed bar checks and incorrect durations. To speed up +this process, you can use @code{skipTypesetting} (See @ref{Skipping +corrected music})). + +@c . {Point and click} +@node Point and click +@subsection Point and click +@cindex poind and click + +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 @bullet +@item A dvi viewer that supports src specials. +@itemize @bullet +@item Xdvi, version 22.36 or newer. Available from +@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}. + + Note that most @TeX{} distributions ship with xdvik, which is always + a few versions behind the official Xdvi. To find out which xdvi you + are running, try @code{xdvi -version} or @code{xdvi.bin -version}. +@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or +newer. Enablle the menu Settings -> Inverse search. +@end itemize +@item An editor with a client/server interface (or a lightweight GUI editor). +@itemize @bullet +@item Emacs. Emacs is an extensible text-editor. It is available from +@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use +column location. +@item XEmacs. Xemacs is very similar to emacs. +@item NEdit. NEdit runs under Windows, and Unix. + It is available from @uref{http://www.nedit.org}. +@item GVim. GVim is a GUI variant of VIM, the popular VI +clone. It is available from @uref{http://www.vim.org}. +@end itemize +@end itemize + + +Xdvi must be configured to find the @TeX{} fonts and music +fonts. Refer to the Xdvi documentation for more information. + +To use point-and-click, add one of these lines to the top of your .ly +file. +@example +#(set! point-and-click line-location) +@end example +@cindex line-location + +When viewing, Control-Mousebutton 1 will take you to the originating +spot in the @file{.ly} file. Control-Mousebutton 2 will show all +clickable boxes. + +If you correct large files with point-and-click, be sure to start +correcting at the end of the file. When you start at the top, and +insert one line, all following locations will be off by a line. + +@cindex Emacs +For using point-and-click with emacs, add the following +In your emacs startup file (usually @file{~/.emacs}), +@example +(server-start) +@end example + +Make sure that the environment variable @var{XEDITOR} is set to +@example +emacsclient --no-wait +%l %f +@end example +@cindex @var{XEDITOR} +If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in +your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f} + +For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or use this +argument with xdvi's @code{-editor} option. +@cindex NEdit +For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or +use this argument with xdvi's @code{-editor} option. + +If can also make your editor jump to the exact location of the note +you clicked. This is only supported on Emacs. Users of version 20 must +apply the patch @file{emacsclient.patch}. Users of version 21 must +apply @file{server.el.patch} (version 21.2 and earlier). At the top +of the @code{ly} file, replace the @code{set!} line with the following +line, +@example +#(set! point-and-click line-column-location) +@end example +@cindex line-colomn-location +and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. + +@refbugs + +When you convert the @TeX{} file to PostScript using @code{dvips}, it +will complain about not finding @code{src:X:Y} files. These complaints +are harmless, and can be ignored. + +@node Skipping corrected music +@subsection Skipping corrected music + +The property @code{Score.skipTypesetting} can be used to switch on and +off typesetting completely during the interpretation phase. When +typesetting is switched off, the music is processed much more quickly. +You can use this to skip over the parts of a score that you have already +checked for errors. + +@lilypond[fragment,singleline,verbatim] +\relative c'' { c8 d +\property Score.skipTypesetting = ##t + e f g a g c, f e d +\property Score.skipTypesetting = ##f +c d b bes a g c2 } +@end lilypond + + + + +@node Staff notation +@section Staff notation + +This section deals with music notation that occurs on staff level, +such as keys, clefs and time signatures. + +@cindex Staff notation + +@menu +* Staff symbol:: +* Key signature:: +* Clef:: +* Time signature:: +* Unmetered music:: +* Bar lines:: +@end menu + +@node Staff symbol +@subsection Staff symbol + + +@cindex adjusting staff symbol +@cindex StaffSymbol, using \property +@cindex staff lines, setting number of + + +The lines of the staff symbol are formed by the +@internalsref{StaffSymbol} grob. This grob is created at the moment +that their context is created. You can not change the appearance of +the staff symbol by using @code{\override} or @code{\set}. At the +moment that @code{\property Staff} is interpreted, a Staff context is +made, and the StaffSymbol is created before any @code{\override} is +effective. You can deal with this either overriding properties in a +@code{\translator} definition, or by using @code{\outputproperty}. + + +@refbugs + +If you end a staff half way a piece, the staff symbol may not end +exactly on the barline. + + +@c . {Key} +@node Key signature +@subsection Key signature +@cindex Key + +@cindex @code{\key} + +Setting or changing the key signature is done with the @code{\key} +command. +@example + @code{\key} @var{pitch} @var{type} +@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} + +Here, @var{type} should be @code{\major} or @code{\minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. +The standard mode names @code{\ionian}, +@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, +@code{\phrygian}, and @code{\dorian} are also defined. + +This command sets the context property @code{Staff.keySignature}. +Non-standard key signatures can be specified by setting this property +directly. + +The printed signature is a @internalsref{KeySignature} grob, typically +created in @internalsref{Staff} context. + +@cindex @code{keySignature} + +@c . {Clef} +@node Clef +@subsection Clef +@cindex @code{\clef} + +The clef can be set or changed with the @code{\clef} command: +@lilypond[fragment,verbatim] + \key f\major c''2 \clef alto g'2 +@end lilypond + +Supported clef-names include +@c Moved standard clefs to the top /MB +@table @code +@item treble, violin, G, G2 +G clef on 2nd line +@item alto, C + C clef on 3rd line +@item tenor + C clef on 4th line +@item bass, F + F clef on 4th line +@item french + G clef on 1st line, so-called French violin clef +@item soprano + C clef on 1st line +@item mezzosoprano + C clef on 2nd line +@item baritone + C clef on 5th line +@item varbaritone + F clef on 3rd line +@item subbass + F clef on 5th line +@item percussion + percussion clef @end table -@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.'' +By adding @code{_8} or @code{^8} to the clef name, the clef is +transposed one octave down or up, respectively. Note that you have to +enclose @var{clefname} in quotes if you use underscores or digits in the +name. For example, +@example + \clef "G_8" +@end example -@cindex Vaticana, Editio -@cindex Medicaea, Editio -@cindex hufnagel clefs +The grob for this symbol is @internalsref{Clef}. + + +This command is equivalent to setting @code{clefGlyph}, +@code{clefPosition} (which controls the Y position of the clef), +@code{centralCPosition} and @code{clefOctavation}. A clef is created +when any of these properties are changed. @c . {Time signature} @@ -715,42 +867,27 @@ Editio XXX.'' @cindex @code{\time} The time signature is set or changed by the @code{\time} -command. Syntax: -@example - \time @var{n}@code{/}@var{d} -@end example -Internally, this is a shortcut for doing -@example -\property Score.timeSignatureFraction = #'(@var{n} . @var{d}) -\property Score.beatLength = #(make-moment 1 @var{d}) -\property Score.measureLength = #(make-moment @var{n} @var{d}) -@end example - -These properties @code{timeSignatureFraction} determine where bar lines -should be inserted, and how automatic beams should be -generated. +command. +@lilypond[fragment,verbatim] + \time 2/4 c'2 \time 3/4 c'2. +@end lilypond -Changing the value of @code{timeSignatureFraction} also causes a -fraction to be printed. This grob is @internalsref{TimeSignature}. +The actual symbol that's printed can be customized with the @code{style} +property. Setting it to @code{#'()} uses fraction style for 4/4 and +2/2 time. -The actual symbol that's printed can be customized with the style -property. -@lilypond[fragment, verbatim, singleline] -\time 3/4 s2 -\property Staff.TimeSignature \override #'style = #'C -\time 4/4 s2 -\property Staff.TimeSignature \override #'style = #'() -\time 4/4 s2 -\property Staff.TimeSignature \override #'style = #'C -\time 2/2 s2 -@end lilypond -There are many more options for the layout of this grob. They are -selected through the @code{style} grob property. +The grob for this symbol is @internalsref{TimeSignature}. There are +many more options for its layout. They are selected through the +@code{style} grob property. See @file{input/test/time.ly} for more +examples. -@c FIXME: this isn't documented except in example? -See -@file{input/test/time.ly} for examples. +This command sets the property @code{timeSignatureFraction}, +@code{beatLength} and @code{measureLength}. The property +@code{timeSignatureFraction} determine where bar lines should be +inserted, and how automatic beams should be generated. Changing the +value of @code{timeSignatureFraction} also causes a time signature +symbol to be printed. @c . {Partial} @subsection Partial @@ -763,41 +900,42 @@ See @cindex @code{\partial} Partial measures, for example in upbeats, are entered using the -@code{\partial} command: +@code{\partial} command: +@lilypond[fragment,verbatim] +\partial 4* 5/16 c'16 c4 f16 a'2. ~ a'8. a'16 | g'1 +@end lilypond + +The syntax for this command is @example \partial @var{duration} @end example - -Internally, this is a shortcut for - +This is internally translated into @example \property Score.measurePosition = -@var{length of duration} @end example @cindex @code{|} - The property @code{measurePosition} contains a rational number -indicating how much of the measure has passed at this point. +indicating how much of the measure has passed at this point. @node Unmetered music @subsection Unmetered music 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 +music (e.g. cadenzas), this is not desirable. The commands +@code{\cadenzaOn} and @code{\cadenzaOff} can be used to switch off the +timing information: @lilypond[fragment,relative,singleline,verbatim] c'2. -\property Score.timing = ##f +\cadenzaOn c2 -\property Score.timing = ##t +\cadenzaOff c4 c4 c4 @end lilypond -The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as -shortcuts. - - +The property @code{Score.timing} can be used to switch off this +automatic timing @c . {Bar lines} @node Bar lines @@ -808,16 +946,12 @@ shortcuts. @cindex measure lines @cindex repeat bars -@example - \bar @var{bartype} -@end example +Bar lines are inserted automatically, but if you need a special type +of barline, you can force one using the @code{\bar} command: +@lilypond[fragment,verbatim] c4 \bar "|:" c4 +@end lilypond -This is a shortcut for doing -@example - \property Score.whichBar = @var{bartype} -@end example The following bar types are available - @lilypond[fragment, relative, singleline, verbatim] c4 \bar "|" c @@ -830,16 +964,26 @@ c4 \bar "|." @end lilypond - You are encouraged to use @code{\repeat} for repetitions. See @ref{Repeats}. +In scores with many staffs, the barlines are automatically placed at +top level, and they are connected between different staffs of a +@internalsref{StaffGroup}: +@lilypond[fragment, verbatim] +< \context StaffGroup < + \context Staff = up { e'4 d' + \bar "||" + f' e' } + \context Staff = down { \clef bass c4 g e g } > +\context Staff = pedal { \clef bass c2 c2 } > +@end lilypond -@cindex Bar_line_engraver -@cindex whichBar -@cindex repeatCommands -@cindex defaultBarType +The grobs that are created at @internalsref{Staff} level. The name is +@internalsref{BarLine}. +The command @code{\bar @var{bartype}} is a short cut for +doing @code{\property Score.whichBar = @var{bartype}} Whenever @code{whichBar} is set to a string, a bar line of that type is created. @code{whichBar} is usually set automatically: at the start of a measure it is set to @code{defaultBarType}. The contents of @@ -849,45 +993,51 @@ a measure it is set to @code{defaultBarType}. The contents of @code{\bar }. These settings take precedence over the automatic @code{whichBar} settings. -@internalsref{BarLine} grobs are created by the @code{Bar_engraver}. + +@cindex Bar_line_engraver +@cindex whichBar +@cindex repeatCommands +@cindex defaultBarType + + @c . {Polyphony} @node Polyphony @section Polyphony @cindex polyphony -Polyphonic parts, i.e. parts with more than one voice on a staff can be -typeset with LilyPond. - -The easiest way to enter such fragments, is the Scheme function -@code{voicify-music}. It will split chords using the separator -@code{\\}, to make multiple voices. You can use it for small, -short-lived voices (make a chord of voices) or for single chords: +The easiest way to enter such fragments with more than one voice on a +staff is to split chords using the separator @code{\\}. You can use +it for small, short-lived voices (make a chord of voices) or for +single chords: @lilypond[verbatim,fragment] -\context Voice = VA \apply #voicify-music \relative c'' { - c4 < { f d e } \\ { b c2 } > c4 < g' \\ c, \\ f \\ d > +\context Voice = VA \relative c'' { + c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d > } @end lilypond -The function @code{voicify-music} instantiates @internalsref{Voice} -contexts, bearing the names @code{"1"}, @code{"2"}, etc. +The separator causes @internalsref{Voice} contexts to be instantiated, +bearing the names @code{"1"}, @code{"2"}, etc. -To explicity typeset polyphonic music, instantiate a separate Voice -context for each part, and assign a stem direction to each part. +Sometimes, it is necessary to instantiate these contexts by hand: For +Instantiate a separate Voice context for each part, and use +@code{\voiceOne}, up to @code{\voiceFour} to assign a stem directions +and horizontal shift for each part. @c -@lilypond[fragment,verbatim] -\context Staff -< \context Voice = VA { \stemUp b'4 a' g' f' e' } - \context Voice = VB { \stemDown g'4 g' g' g' g' } > + +@lilypond[singleline, verbatim] +\relative c'' +\context Staff < \context Voice = VA { \voiceOne cis2 b } + \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } + \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } > @end lilypond -When there are more than two voices on a staff, you must also indicate -which voice should moved horizontally in case of a collision. This can -be done with the identifiers @code{\shiftOff}, @code{\shiftOn}, -@code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift} -in @internalsref{NoteColumn}). +The identifiers @code{\voiceOne} to @code{\voiceFour} set directions +ties, slurs and stems, and set shift directions. +If you want more than four voices, you can also manually set +horizontal shifts and stem directions, as is shown in the following example: @lilypond[fragment, verbatim] \context Staff \notes\relative c''< \context Voice=one { @@ -905,72 +1055,180 @@ in @internalsref{NoteColumn}). > @end lilypond -The most convenient way is to use the identifiers @code{\voiceOne} -through @code{\voiceFour}, which also set slur and tie directions in the -correct manner. - -@lilypond[singleline, verbatim] -\relative c'' -\context Staff < \context Voice = VA { \voiceOne cis2 b } - \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } - \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } > -@end lilypond Normally, note heads with a different number of dots are not merged, but if you set the grob property @code{merge-differently-dotted}, they are: - @lilypond[verbatim,fragment,singleline] - \context Staff < - \context Voice = VA { \voiceOne +\context Voice < { g'8 g'8 - \property Staff.NoteCollision \override #'merge-differently-dotted = ##t + \property Staff.NoteCollision \override + #'merge-differently-dotted = ##t g'8 g'8 - } - \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] } + } \\ { [g'8. f16] [g'8. f'16] } > @end lilypond -LilyPond also vertically shifts rests that are opposite of a stem. - -@lilypond[singleline,verbatim] -\context Staff < -\context Voice { \stemUp c''4 } -\context Voice =VB { r4 } -> +Similarly, you can merge half note heads with eighth notes, by setting +@code{merge-differently-headed}: +@lilypond[fragment, relative=2,verbatim] +\context Voice < { + c8 c4. + \property Staff.NoteCollision + \override #'merge-differently-headed = ##t + c8 c4. } \\ { c2 c2 } > @end lilypond -Note head collisions (horizontal shifting of note heads) are handled by -the @internalsref{NoteCollision} grob. @internalsref{RestCollision} -handles vertical shifting of rests. - - +LilyPond also vertically shifts rests that are opposite of a stem. +@lilypond[singleline,fragment,verbatim] +\context Voice < c''4 \\ r4 > +@end lilypond +See also @internalsref{NoteCollision} and @internalsref{RestCollision} @refbugs Resolving collisions is a very intricate subject, and LilyPond only handles a few situations. When it can not cope, you are advised to use -@code{force-hshift} of the NoteColumn grob and @code{staff-position} of -the Rest grob to override typesetting decisions. +@code{force-hshift} of the @internalsref{NoteColumn} grob and pitched +rests to override typesetting decisions. @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. If you're -not satisfied with the automatic beaming, you can specify which patterns -to beam automatically. In specific cases, you can also enter the beams -explicitly. +the metrum. They are inserted automatically in most cases. + +@lilypond[fragment,verbatim, relative=2] +\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 +@end lilypond + +If you're not satisfied with the automatic beaming, you can enter the +beams explicitly. If you have beaming patterns that differ from the +defaults, you can also set the patterns for automatic beamer. + +See also @internalsref{Beam}. + +@c . {Manual beams} +@cindex Automatic beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} + +In some cases it may be necessary to override LilyPond's automatic +beaming algorithm. For example, the auto beamer will not beam over +rests or bar lines, If you want that, specify the begin and end point +manually using a @code{[} before the first beamed note and a @code{]} +after the last note: + +@lilypond[fragment,relative,verbatim] + \context Staff { + r4 [r8 g' a r8] r8 [g | a] r8 + } +@end lilypond + +@cindex @code{stemLeftBeamCount} + +Normally, beaming patterns within a beam are determined automatically. +When this mechanism fouls up, the properties +@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can +be used to control the beam subdivision on a stem. If you set either +property, its value will be used only once, and then it is erased. + +@lilypond[fragment,relative,verbatim] + \context Staff { + [f8 r16 f g a] + [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] + } +@end lilypond +@cindex @code{stemRightBeamCount} + + +The property @code{subdivideBeams} can be set in order to subdivide +all 16th or shorter beams at beat positions. This accomplishes the +same effect as twiddling with @code{stemLeftBeamCount} and +@code{stemRightBeamCount}, but it take less typing. + + +@example +[c16 c c c c c c c] +\property Voice.subdivideBeams = ##t +[c16 c c c c c c c] +[c32 c c c c c c c c c c c c c c c] +\property Score.beatLength = #(make-moment 1 8) +[c32 c c c c c c c c c c c c c c c] +@end example +@lilypond[] +\score { + \notes \relative c' { + [c16 c c c c c c c] + \property Voice.subdivideBeams = ##t + [c16 c c c c c c c] + [c32 c c c c c c c c c c c c c c c] + \property Score.beatLength = #(make-moment 1 8) + [c32 c c c c c c c c c c c c c c c] + } +} +@end lilypond +@cindex subdivideBeams + +Kneed beams are inserted automatically, when a large gap between two +adjacent beamed notes is detected. This behavior can be tuned through +the grob property @code{auto-knee-gap}. + +@cindex beams, kneed +@cindex kneed beams +@cindex auto-knee-gap +@cindex hara kiri + + +@c TODO -> why this ref? Document? +@cindex @code{neutral-direction} + +@refbugs + +Auto knee beams can not be used together with hara kiri staffs. + +[TODO from bugs] + +The Automatic beamer does not put @strong{unfinished} beams on the +last notes of a score. + +Formatting of ties is a difficult subject. LilyPond often does not +give optimal results. + +@menu +* Setting automatic beam behavior :: +@end menu + +@ignore +@no de Beam typography +@sub section Beam typography + +One of the strong points of LilyPond is how beams are formatted. Beams +are quantized, meaning that the left and right endpoints beams start +exactly on staff lines. Without quantization, small wedges of white +space appear between the beam and staff line, and this looks untidy. +Beams are also slope-damped: melodies that go up or down should also +have beams that go up or down, but the slope of the beams should be +less than the slope of the notes themselves. + +Some beams should be horizontal. These are so-called concave beams. + +[TODO: some pictures.] +@end ignore @c . {Automatic beams} -@subsection Automatic beams +@node Setting automatic beam behavior +@subsection Setting automatic beam behavior -@cindex @code{Voice.autoBeamSettings} +@cindex @code{autoBeamSettings} @cindex @code{(end * * * *)} @cindex @code{(begin * * * *)} - +@cindex automatic beams, tuning +@cindex tuning automatic beaming In normal time signatures, automatic beams can start on any note but can only end in a few positions within the measure: beams can end on a beat, @@ -1033,11 +1291,13 @@ accepting notes, this last beam will not be typeset at all. @cindex automatic beam generation @cindex autobeam -@cindex @code{Voice.noAutoBeaming} +@cindex @code{Voice.autoBeaming} +@cindex lyrics + +For melodies that have lyrics, you may want to switch off +automatic beaming. This is done by setting @code{Voice.autoBeaming} to +@code{#f}. -Automatic beaming is on by default, but can be switched off by setting -@code{Voice.noAutoBeaming} to true. You you may find this necessary for -a melody that goes with lyrics. @refbugs @@ -1054,75 +1314,233 @@ It is not possible to specify beaming parameters that act differently in different parts of a measure. This means that it is not possible to use automatic beaming in irregular meters such as @code{5/8}. -@c . {Manual beams} -@cindex Automatic beams -@subsection Manual beams -@cindex beams, manual -@cindex @code{]} -@cindex @code{[} +@node Accidentals +@section Accidentals +@cindex Accidentals +This section describes how to change the way that LilyPond automatically +inserts accidentals before the running notes. -In some cases it may be necessary to override LilyPond's automatic -beaming algorithm. For example, the auto beamer will not beam over -rests or bar lines, If you want that, specify the begin and end point -manually using a @code{[} before the first beamed note and a @code{]} -after the last note: +@menu +* Using the predefined accidental macros:: +* Defining your own accidental typesettings:: +@end menu -@lilypond[fragment,relative,verbatim] - \context Staff { - r4 [r8 g' a r8] r8 [g | a] r8 - } +@node Using the predefined accidental macros +@subsection Using the predefined accidental macros +The constructs for describing the accidental typesetting rules are +quite hairy, so non-experts should stick to the macros defined in +@file{ly/property-init.ly}. +@cindex @file{property-init.ly} + +The macros operate on the ``Current'' context (see @ref{Context properties}). This +means that the macros shuold normally be invoked right after the +creation of the context in which the accidental typesetting described +by the macro is to take effect. I.e. if you want to use +piano-accidentals in a pianostaff then you issue +@code{\pianoAccidentals} first thing after the creation of the piano +staff: +@example +\score @{ + \notes \relative c'' < + \context Staff = sa @{ cis4 d e2 @} + \context GrandStaff < + \pianoAccidentals + \context Staff = sb @{ cis4 d e2 @} + \context Staff = sc @{ es2 c @} + > + \context Staff = sd @{ es2 c @} + > +@} +@end example +@lilypond[singleline] +\score { + \notes \relative c'' < + \context Staff = sa { cis4 d e2 } + \context GrandStaff < + \pianoAccidentals + \context Staff = sb { cis4 d e2 } + \context Staff = sc { es2 c } + > + \context Staff = sd { es2 c } + > + \paper { + \translator { + \StaffContext + minimumVerticalExtent = #'(-4.0 . 4.0) + } + } +} @end lilypond -Whenever an manual beam is busy, the automatic beamer will not produce -anything. - -@cindex @code{stemLeftBeamCount} -Normally, beaming patterns within a beam are determined automatically. -When this mechanism fouls up, the properties -@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. can -be used to control the beam subdivision on a stem. If you set either -property, it's value will be used only once, and then it is erased. - -@lilypond[fragment,relative,verbatim] - \context Staff { - [f8 r16 f g a] - [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] - } +The macros are: +@table @code +@item \defaultAccidentals + @cindex @code{\defaultAccidentals} + This is the default typesetting behaviour. It should correspond + to 18th century common practice: Accidentals are + remembered to the end of the measure in which they occur and + only on their own octave. + +@item \voiceAccidentals + @cindex @code{\voiceAccidentals} + The normal behaviour is to remember the accidentals on + Staff-level. + This macro, however, typesets accidentals individually for each + voice. + Apart from that the rule is similar to + @code{\defaultAccidentals}. + + Warning: This leads to some weird and often unwanted results + because accidentals from one voice DO NOT get cancelled in other + voices: +@lilypond[singleline,relative,fragment,verbatim] + \context Staff < + \voiceAccidentals + \context Voice=va { \voiceOne es g } + \context Voice=vb { \voiceTwo c, e } + > +@end lilypond + Hence you should only use @code{\voiceAccidentals} + if the voices are to be read solely by + individual musicians. if the staff should be readable also + by one musician/conductor then you should use + @code{\modernVoiceAccidentals} or @code{\modernVoiceCautionaries} + instead. + +@item \modernAccidentals + @cindex @code{\modernAccidentals} + This rule should correspond to the common practice in the 20th + century. + The rule is a bit more complex than @code{\defaultAccidentals}: + You get all the same accidentals, but temporary + accidentals also get cancelled in other octaves. Further more, + in the same octave, they also get cancelled in the following measure: +@lilypond[singleline,fragment,verbatim] + \modernAccidentals + cis' c'' cis'2 | c'' c' @end lilypond -@cindex @code{stemRightBeamCount} -The beam symbol (grob @internalsref{Beam} in @internalsref{Voice} -context), both for automatic and manual beams) can be tweaked through -grob-properties @code{height} and @code{staff-position}. These specify -vertical location and vertical span. Both are measured in half -staff-spaces, @code{staff-position=0} corresponds to the middle staff -line. +@item \modernCautionaries + @cindex @code{\modernCautionaries} + This rule is similar to @code{\modernAccidentals}, but the + ``extra'' accidentals (the ones not typeset by + @code{\defaultAccidentals}) are typeset as cautionary accidentals + (i.e. in reduced size): +@lilypond[singleline,fragment,verbatim] + \modernCautionaries + cis' c'' cis'2 | c'' c' +@end lilypond -Set @code{height} to zero, to get horizontal beams: +@item \modernVoiceAccidentals + @cindex @code{\modernVoiceAccidentals} + Multivoice accidentals to be read both by musicians playing one voice + and musicians playing all voices. + + Accidentals are typeset for each voice, but they ARE cancelled + across voices in the same @internalsref{Staff}. + +@item \modernVoiceCautionaries + @cindex @code{\modernVoiceCautionaries} + The same as @code{\modernVoiceAccidentals}, but with the + extra accidentals (the ones not typeset by + @code{\voiceAccidentals}) typeset as cautionaries. + Notice that even though all accidentals typeset by + @code{\defaultAccidentals} ARE typeset by this macro then some + of them are typeset as cautionaries. + +@item \pianoAccidentals + @cindex @code{\pianoAccidentals} + 20th century practice for piano notation. Very similar to + @code{\modernAccidentals} but accidentals also get cancelled + across the staves in the same @internalsref{GrandStaff} or + @internalsref{PianoStaff}. + +@item \pianoCautionaries + @cindex @code{\pianoCautionaries} + As @code{\pianoAccidentals} but with the extra accidentals + typeset as cationaries. + +@item \noResetKey + @cindex @code{\noResetKey} + Same as @code{\defaultAccidentals} but with accidentals lasting + ``forever'' and not only until the next measure: +@lilypond[singleline,fragment,verbatim,relative] + \noResetKey + c1 cis cis c +@end lilypond -@lilypond[fragment,relative,verbatim] - \property Voice.Beam \set #'direction = #1 - \property Voice.Beam \set #'height = #0 - [a'8 e' d c] +@item \forgetAccidentals + @cindex @code{\forgetAccidentals} + This is sort of the opposite of @code{\noResetKey}: Accidentals + are not remembered at all - and hence all accidentals are + typeset relative to the key signature, regardless of what was + before in the music: +@lilypond[singleline,fragment,verbatim,relative] + \forgetAccidentals + \key d\major c4 c cis cis d d dis dis @end lilypond +@end table -Here's how you'd specify a weird looking beam that instead of being -horizontal, falls two staff spaces: +@node Defining your own accidental typesettings +@subsection Defining your own accidental typesettings +This section must be considered gurus-only, and hence it must be +sufficient with a short description of the system and a reference to +the internal documentation. -[FIXME] +The idea of the algorithm is to try several different rules and then +use the rule that gives the highest number of accidentals. +Each rule cosists of +@table @asis +@item Context: + In which context is the rule applied. I.e. if context is + @internalsref{Score} then all staves share accidentals, and if + context is @internalsref{Staff} then all voices in the same + staff share accidentals, but staves don't - like normally. +@item Octavation: + Whether the accidental changes all octaves or only the current + octave. +@item Lazyness: + Over how many barlines the accidental lasts. + If lazyness is @code{-1} then the accidental is forget + immidiately, and if lazyness is @code{#t} then the accidental + lasts forever. +@end table +As described in the internal documentation of +@reng{Accidental_engraver}, the properties @code{autoAccidentals} and +@code{autoCautionaries} contain lists of rule descriptions. Notice +that the contexts must be listed from in to out - that is +@internalsref{Thread} before @internalsref{Voice}, +@internalsref{Voice} before @internalsref{Staff}, etc. +see the macros in @file{ly/property-init.ly} for examples of how the +properties are set. -@lilypond[fragment,relative,verbatim] - \property Voice.Beam \set #'staff-position = #4 - \property Voice.Beam \set #'height = #-4 - [c8 c] -@end lilypond +@refbugs -[TODO: doc autokneeing ? ] +Currently the simultaneous notes are considered to be entered in +sequential mode. This means that in a chord the accidentals are +typeset as if the notes in the chord happened one at a time - in the +order in which they appear in the input file. + +Of course this is only a problem when you have simultainous notes +which accidentals should depend on each other. +Notice that the problem only occurs when using non-default accidentals +- as the default accidentals only depend on other accidentals on the +same staff and same pitch and hence cannot depend on other +simultainous notes. + +This example shows two examples of the same music giving different +accidentals depending on the order in which the notes occur in the +input file: + +@lilypond[singleline,fragment,verbatim] +\property Staff.autoAccidentals = #'( Staff (any-octave . 0) ) +cis'4 r2 | cis'4 r2 | r | r | +@end lilypond -@c TODO -> why this ref? Document? -@cindex @code{neutral-direction} +The only solution is to manually insert the problematic +accidentals using @code{!} and @code{?}. @node Expressive marks @section Expressive marks @@ -1138,15 +1556,15 @@ horizontal, falls two staff spaces: @node Slurs @subsection Slurs -@cindex slurs +@cindex Slurs A slur indicates that notes are to be played bound or @emph{legato}. They are entered using parentheses: - @lilypond[fragment,verbatim,center] f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 @end lilypond +See also @seeinternals{Slur}. Slurs avoid crossing stems, and are generally attached to note heads. However, in some situations with beams, slurs may be attached to stem @@ -1156,7 +1574,7 @@ grob-property @code{attachment} of @internalsref{Slur} in the attachment type of the left and right end points. @lilypond[fragment,relative,verbatim] - \property Voice.Slur \set #'direction = #1 + \slurUp \property Voice.Stem \set #'length = #5.5 g'8(g)g4 \property Voice.Slur \set #'attachment = #'(stem . stem) @@ -1168,36 +1586,44 @@ away upward or downward. If this happens, attaching the slur to the stems might look better: @lilypond[fragment,relative,verbatim] - \property Voice.Stem \set #'direction = #1 - \property Voice.Slur \set #'direction = #1 + \stemUp \slurUp d32( d'4 )d8.. \property Voice.Slur \set #'attachment = #'(stem . stem) d,32( d'4 )d8.. @end lilypond - +@ignore 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 @internalsref{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 -indicate this preference by increasing the @code{beautiful} value: - -@lilypond[verbatim,singleline,relative] - \property Voice.Beam \override #'direction = #-1 - \property Voice.Slur \override #'direction = #1 +slur is reverted to its default shape. The threshold for this +decision is in @internalsref{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 indicate this preference by increasing the +@code{beautiful} value: + +@lilyp ond[verbatim,singleline,relative] + \stemDown \slurUp c16( 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 ignore @refbugs -@code{beautiful} is an arbitrary parameter in the slur formatter. -Useful values can only be determined by trial and error. +Producing nice slurs is a difficult problem, and LilyPond currently +uses a simple, empiric method to produce slurs. In some cases, the +results of this method are ugly. + +@ignore +This is reflected by the +@code{beautiful} property, which it is an arbitrary parameter in the +slur formatter. Useful values can only be determined by trial and +error. +@end ignore @cindex Adjusting slurs @@ -1212,34 +1638,24 @@ indicate a musical sentence. It is started using @code{\(} and @code{\)} respectively. @lilypond[fragment,verbatim,center,relative] - \time 6/4 c' \( ( d ) e f ( e ) \) d + \time 6/4 c' \( d () e f () e \) d @end lilypond Typographically, the phrasing slur behaves almost exactly like a normal -slur. The grob associated with it is @internalsref{PhrasingSlur}, in -@internalsref{Voice} context. +slur. See also @seeinternals{PhrasingSlur}. + @node Breath marks @subsection Breath marks -Breath marks are entered using @code{\breathe}. The result is a -@internalsref{BreathingSign} grob in @internalsref{Voice} context. +Breath marks are entered using @code{\breathe}. See also +@seeinternals{BreathingSign}. @lilypond[fragment,relative] c'4 \breathe d4 @end lilypond - - -@refbugs - -The current layout of the default comma style breath marks -could be improved and more optional symbols should be added to the -font. - - - @c . {Tempo} @node Tempo @subsection Tempo @@ -1314,19 +1730,68 @@ An application---or rather, a hack---is to fake octavation indications. @cindex ornaments A variety of symbols can appear above and below notes to indicate -different characteristics of the performance. These symbols can be -added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols -are defined in @file{script.ly}. Symbols can be forced to appear above -or below the note by writing `@var{note}@code{^\}@var{name}' and -`@var{note}@code{_\}@var{name}' respectively. Here is a chart showing -symbols on notes, with the name of the corresponding symbol appearing -underneath. +different characteristics of the performance. They are added to a note +by adding a dash and the the character signifying the +articulation. They are demonstrated here. +@lilypond[singleline] + \score { + \notes \context Voice { + \property Voice.TextScript \set #'font-family = #'typewriter + \property Voice.TextScript \set #'font-shape = #'upright + c''4-._"c-." s4 + c''4--_"c-{}-" s4 + c''4-+_"c-+" s4 + c''4-|_"c-|" s4 + c''4->_"c->" s4 + c''4-^_"c-\\^{ }" s4 + } + } +@end lilypond + +The script is automatically placed, but if you need to force +directions, you can use @code{_} to force them down, or @code{^} to +put them up: +@lilypond[fragment, verbatim] + c''4^^ c''4_^ +@end lilypond + + +Other symbols can be added using the syntax +@var{note}@code{-\}@var{name}. Again, they can be forced up or down +using @code{^} and @code{_}. + +@cindex accent +@cindex marcato +@cindex staccatissimo +@cindex fermata +@cindex stopped +@cindex staccato +@cindex tenuto +@cindex upbow +@cindex downbow +@cindex foot marks +@cindex organ pedal marks +@cindex turn +@cindex open +@cindex flageolet +@cindex reverseturn +@cindex trill +@cindex prall +@cindex mordent +@cindex prallprall +@cindex prallmordent +@cindex prall, up +@cindex prall, down +@cindex mordent +@cindex thumb marking +@cindex segno +@cindex coda @lilypond[] \score { < - \property Score.LyricSyllable \override #'font-family =#'typewriter - \property Score.LyricSyllable \override #'font-shape = #'upright + \property Score.LyricText \override #'font-family =#'typewriter + \property Score.LyricText \override #'font-shape = #'upright \context Staff \notes { c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata c''-\stopped c''-\staccato c''-\tenuto c''-\upbow @@ -1355,26 +1820,12 @@ underneath. } @end lilypond -To save typing work, some shorthands are available: -@lilypond[singleline] - \score { - \notes \context Voice { - \property Voice.TextScript \set #'font-family = #'typewriter - \property Voice.TextScript \set #'font-shape = #'upright - c''4-._"c-." s4 - c''4--_"c-{}-" s4 - c''4-+_"c-+" s4 - c''4-|_"c-|" s4 - c''4->_"c->" s4 - c''4-^_"c-\\^{ }" s4 - } - } -@end lilypond @cindex fingering -Fingering instructions can also be entered in this shorthand. For -changes, some markup texts would be needed: +Fingering instructions can also be entered in this shorthand. For +finger changes, use markup texts: +@c @lilypond[verbatim, singleline, fragment] c'4-1 c'4-2 c'4-3 c'4-4 c^#'(finger "2-3") @@ -1386,18 +1837,7 @@ changes, some markup texts would be needed: @cindex superscript @cindex subscript -You can add scripts by editing @file{scm/script.scm}. This file contains -a table, listing script definitions and aliases. The following syntax -accesses a script definition from the table: - -@example - \script @var{alias} -@end example - -Usually the @code{\script} keyword is not used directly. Various -helpful identifier definitions appear in @file{script.ly}. - -Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}. +See also @seeinternals{Script} and @seeinternals{Fingering}. @refbugs @@ -1419,47 +1859,88 @@ text (see @ref{Text markup}) above or below notes by using a string: @code{c^"text"}. By default, these indications do not influence the note spacing, but -if @code{Voice.textNonEmpty} is set to true the widths will be taken -into account. The identifier @code{\fatText} is defined in the standard -includes. -@lilypond[fragment,singleline,verbatim] -\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 } +by using the command @code{\fatText}, the widths will be taken into +account. +@c +@lilypond[fragment,singleline,verbatim] \relative c' { +c4^"longtext" \fatText c4_"longlongtext" c4 } @end lilypond +It is possible to use @TeX{} commands in the strings, but this should be +avoided because it 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 (see @ref{PostScript output}). + Text scripts are created in form of @internalsref{TextScript} grobs, in -@internalsref{Voice} context. +@internalsref{Voice} context. @ref{Text markup} describes how to change the font or access special symbols in text scripts. + @c . {Grace notes} @node Grace notes @subsection Grace notes +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes + +Grace notes are ornaments are written out ornaments +@lilypond[relative=2,verbatim,ifragment] + c4 \grace c16 c4 \grace { [c16 d16] } c4 +@end lilypond + +In normal notation, grace notes are supposed to take up no logical +time in a measure. Such an idea is practical for normal notation, but +is not strict enough to put it into a program. The model that LilyPond +uses for grace notes internally is that all timing is done in two +steps: + +Every point in musical time consists of two rational numbers: one +denotes the logical time, one denotes the grace timing. The above +example is shown here with timing tuples. +@lilypond[] +\score { \notes \relative c''{ + c4^"(0,0)" \grace c16_" "_"(1/4,-1/16)" c4^"(1/4,0)" \grace { + [c16_"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4_" "_"(2/4,0)" + } +\paper { linewidth = 8.\cm } +} +@end lilypond +The advantage of this approach is that you can use almost any lilypond +construction together with grace notes, for example slurs and clef +changes may appear halfway in between grace notes: +@lilypond[relative=2,verbatim,fragment] + c4 \grace { [ c16 c, \clef bass c, b(] } )c4 +@end lilypond -@cindex Grace music -@cindex @code{\grace} -@cindex ornaments -@cindex grace notes -@cindex @code{graceAlignPosition} +The placement of these grace notes is synchronized between different +staffs, using this grace timing. + +@lilypond[relative=2,verbatim,fragment] +< \context Staff = SA { e4 \grace { c16 d e f } e4 } + \context Staff = SB { c4 \grace { g8 b } c4 } > +@end lilypond -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 Unbeamed eighth notes and shorter by default have a slash through the -stem. +stem. This can be controlled with grob property @code{flag-style} of +@internalsref{Stem}. The change in formatting is accomplished by +inserting @code{\startGraceMusic} before handling the grace notes, and +@code{\stopGraceMusic} after finishing the grace notes. You can add to +these definitions to globally change grace note formatting. The +standard definitions are in @file{ly/grace-init.ly}. + @lilypond[fragment,verbatim] -\relative c'' { +\relative c'' \context Voice { \grace c8 c4 \grace { [c16 c16] } c4 \grace { \property Voice.Stem \override #'flag-style = #'() @@ -1469,21 +1950,32 @@ stem. } @end lilypond -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}. +If you want to end a note with a grace note, then the standard trick +is to put the grace notes before a phantom ``space note'', e.g. +@lilypond[fragment,verbatim, relative=2] +\context Voice { + < { d1^\trill ( } + { s2 \grace { [c16 d] } } > + )c4 +} +@end lilypond + @refbugs -Nesting @code{\grace} notes is not supported. The following 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 -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. +Grace note synchronization can also lead to surprises. Staff notation, +such as key signatures, barlines, etc. are also synchronized. Take +care when you mix staffs with grace notes and staffs without. + +@lilypond[relative=2,verbatim,fragment] +< \context Staff = SA { e4 \bar "|:" \grace c16 d4 } + \context Staff = SB { c4 \bar "|:" d4 } > +@end lilypond + +Grace sections should only be used within sequential music +expressions. Nesting, juxtaposing, or ending sequential music with a +grace section is not supported, and might produce crashes or other +errors. @menu * Glissando :: @@ -1499,8 +1991,8 @@ error, since there will be no main note to attach the grace notes to. @cindex @code{\glissando} -A glissando line (grob @internalsref{Glissando}) can be requested by -attaching a @code{\glissando} to a notte: +A glissando line can be requested by attaching a @code{\glissando} to +a note: @lilypond[fragment,relative,verbatim] c'-\glissando c' @@ -1509,7 +2001,7 @@ attaching a @code{\glissando} to a notte: @refbugs Printing of an additional text (such as @emph{gliss.}) must be done -manually. +manually. See also @seeinternals{Glissando}. @@ -1576,28 +2068,32 @@ want several marks during one note, you have to use spacer notes. You can also use a text saying @emph{cresc.} instead of hairpins. Here is an example how to do it: +@lilypond[fragment,relative=2,verbatim] + c4 \cresc c4 \endcresc c4 +@end lilypond + + @cindex crescendo @cindex decrescendo +You can also supply your own texts: @lilypond[fragment,relative,verbatim] \context Voice { - \property Voice.crescendoText = "cresc." + \property Voice.crescendoText = "cresc. poco" \property Voice.crescendoSpanner = #'dashed-line a'2\mf\< a a \!a } @end lilypond -For everyday use, we recommend the identifiers @code{\cresc}, -@code{endcresc}, @code{\dim} and @code{\enddim}. - @cindex diminuendo Dynamics are grobs of @internalsref{DynamicText} and -@internalsref{Hairpin}. Vertical positioning of these symbols is handled -by the @internalsref{DynamicLineSpanner} grob. If you want to adjust -padding or vertical direction of the dynamics, you must set properties -for the @internalsref{DynamicLineSpanner} grob. Predefined identifiers -to set the vertical direction are \dynamicUp and \dynamicDown. +@internalsref{Hairpin}. Vertical positioning of these symbols is +handled by the @internalsref{DynamicLineSpanner} grob. If you want to +adjust padding or vertical direction of the dynamics, you must set +properties for the @internalsref{DynamicLineSpanner} grob. Predefined +identifiers to set the vertical direction are \dynamicUp and +\dynamicDown. @cindex direction, of dynamics @cindex @code{\dynamicDown} @@ -1615,12 +2111,12 @@ 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. -@table @asis +@table @code @item unfold Repeated music is fully written (played) out. Useful for MIDI output, and entering repetitive music. -@item volta +@item volta This is the normal notation: Repeats are not written out, but alternative endings (voltas) are printed, left to right. @@ -1639,6 +2135,7 @@ Make beat or measure repeats. These look like percent signs. @menu * Repeat syntax:: +* Repeats and MIDI:: * Manual repeat commands:: * Tremolo repeats:: * Tremolo subdivisions:: @@ -1701,11 +2198,13 @@ the specified number of repeats. } @end lilypond -@subsection Unfolding repeats for MIDI output. +@node Repeats and MIDI +@subsection Repeats and MIDI @cindex expanding repeats -See @file{input/test/unfold-all-repeats.ly}. +For instructions on how to unfoldi repeats for MIDI output, see +the example file @file{input/test/unfold-all-repeats.ly}. @refbugs @@ -1719,16 +2218,7 @@ are also not repeated. It is possible to nest @code{\repeat}s, although this probably is only meaningful for unfolded repeats. -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. - -Volta repeats are printed over all staves in a score. You must turn them -off explicitly, for example by doing -@example - \property Staff.VoltaBracket = \turnOff -@end example -in all but the top staff. +Folded repeats offer little more over simultaneous music. @node Manual repeat commands @subsection Manual repeat commands @@ -1742,7 +2232,7 @@ command can be @table @code @item 'start-repeat Print a |: bar line -@item 'stop-repeat +@item 'end-repeat Print a :| bar line @item (volta . @var{text}) Print a volta bracket saying @var{text}. @@ -1779,13 +2269,12 @@ style. @end lilypond Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are -@internalsref{StemTremolo}. +@internalsref{StemTremolo}. The single stem tremolo @emph{must} be +entered without @code{@{} and @code{@}}. @refbugs - -At present, the spacing between tremolo beams is not regular, since the -spacing engine does not notice that not all notes are printed. +Only powers of two and undotted notes are supported repeat counts. @node Tremolo subdivisions @subsection Tremolo subdivisions @@ -1836,14 +2325,6 @@ with slashes, and repeating that measure with percents. @node Rhythmic music @section Rhythmic music - -@menu -* Rhythmic staves:: -@end menu - -@node Rhythmic staves -@subsection Rhythmic staves - Sometimes 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: @@ -1855,11 +2336,307 @@ are squashed, and the staff itself looks has a single staff line: } @end lilypond +@menu +* Percussion staves:: +@end menu + +@node Percussion staves +@subsection Percussion staves +@cindex percussion +@cindex drums +To typeset more than one piece of percussion to be played by the same +musician one typically uses a multiline staff where each staff +position refers to a specific piece of percussion. + +LilyPond is shipped with a bunch of scheme functions which allows you +to do this fairly easily. + +The system is based on the general midi drum-pitches. +In order to use the drum pitches you include +@file{ly/drumpitch-init.ly}. This file defines the pitches from the scheme +variable @code{drum-pitch-names} - which definition can be read in +@file{scm/drums.scm}. You see that each piece of percussion has a full +name and an abbreviated name - and you may freely select whether to +refer to the full name or the abbreviation in your music definition. + +To typeset the music on a staff you apply the scheme function +@code{drums->paper} to the percussion music. This function takes a +list of percussion instrument names, notehead scripts and staff +positions (that is: pitches relative to the C-clef) and uses this to +transform the input music by moving the pitch, changing the notehead +and (optionally) adding a script: +@lilypond[singleline,verbatim] +\include "drumpitch-init.ly" +up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } +down = \notes { bassdrum4 snare8 bd r bd sn4 } +\score { + \apply #(drums->paper 'drums) \context Staff < + \clef percussion + \context Voice = up { \voiceOne \up } + \context Voice = down { \voiceTwo \down } + > +} + +@end lilypond +In the above example the music was transformed using the list @code{'drums}. +Currently the following lists are defined in @file{scm/drums.scm}: +@table @code +@item 'drums +To typeset a typical drum kit on a five line staff. +@lilypond[] +\include "drumpitch-init.ly" +nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc + bd sn ss tomh tommh tomml toml tomfh tomfl } +mus = \notes { cymc cyms cymr hh hhc hho hhho hhp cb hc + bd sn ss tomh tommh tomml toml tomfh tomfl s16 } +\score { + < + \apply #(drums->paper 'drums) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + minimumVerticalExtent = #'(-4.0 . 5.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +Notice that the scheme supports six different toms. +If you are using fewer toms then you simply select the toms that produce +the desired result - i.e. to get toms on the three middle lines you +use @code{tommh}, @code{tomml} and @code{tomfh}. + +Because the general midi contain no rimshots we use the sidestick for +this purpose instead. +@item 'timbales +To typeset timbales on a two line staff. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { timh ssh timl ssl cb } +mus = \notes { timh ssh timl ssl cb s16 } +\score { + < + \apply #(drums->paper 'timbales) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #2 + StaffSymbol \override #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + + } +} +@end lilypond +@item 'congas +To typeset congas on a two line staff. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { cgh cgho cghm ssh cgl cglo cglm ssl } +mus = \notes { cgh cgho cghm ssh cgl cglo cglm ssl s16 } +\score { + < + \apply #(drums->paper 'congas) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #2 + StaffSymbol \override #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +@item 'bongos +To typeset bongos on a two line staff. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { boh boho bohm ssh bol bolo bolm ssl } +mus = \notes { boh boho bohm ssh bol bolo bolm ssl s16 } +\score { + < + \apply #(drums->paper 'bongos) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #2 + StaffSymbol \override #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +@item 'percussion +To typeset all kinds of simple percussion on one line staves. +@lilypond[singleline] +\include "drumpitch-init.ly" +nam = \lyrics { tri trio trim gui guis guil cb cl tamb cab mar hc } +mus = \notes { tri trio trim gui guis guil cb cl tamb cab mar hc s16 } +\score { + < + \apply #(drums->paper 'percussion) \context Staff < + \clef percussion + \mus + > + \context Lyrics \nam + > + \paper { + \translator { + \StaffContext + \remove Bar_engraver + \remove Time_signature_engraver + StaffSymbol \override #'line-count = #1 + minimumVerticalExtent = #'(-2.0 . 3.0) + } + \translator { + \VoiceContext + \remove Stem_engraver + } + } +} +@end lilypond +@end table + +If you don't like any of the predefined lists you can define your own +list at the top of your file: + +@lilypond[singleline, verbatim] +#(define mydrums `( + (bassdrum default #f ,(make-pitch -1 2 0)) + (snare default #f ,(make-pitch 0 1 0)) + (hihat cross #f ,(make-pitch 0 5 0)) + (pedalhihat xcircle "stopped" ,(make-pitch 0 5 0)) + (lowtom diamond #f ,(make-pitch -1 6 0)) +)) +\include "drumpitch-init.ly" +up = \notes { hh8 hh hh hh hhp4 hhp } +down = \notes { bd4 sn bd toml8 toml } +\score { + \apply #(drums->paper 'mydrums) \context Staff < + \clef percussion + \context Voice = up { \voiceOne \up } + \context Voice = down { \voiceTwo \down } + > +} +@end lilypond + +To use a modified existing list instead of building your own from +scratch you can append your modifications to the start of the existing +list: + +@example +#(define mydrums (append `( + (bassdrum default #f ,(make-pitch -1 2 0)) + (lowtom diamond #f ,(make-pitch -1 6 0)) +) drums )) +@end example + +@c FIXME: Too many levels of headers when using subsubsections. +@c Perhaps junk subsection ``Percussion staves'' +@subsubsection Percussion staves with normal staves +When you include @file{drumpitch-init.ly} then the default pitches +are overridden so that you after the inclusion cannot use the common +dutch pitch names anymore. Hence you might wan't to reinclude +@file{nederlands.ly} after the drum-pattern-definitions: +@lilypond[singleline,verbatim] +\include "drumpitch-init.ly" +up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } +down = \notes { bassdrum4 snare8 bd r bd sn4 } +\include "nederlands.ly" +bass = \notes \transpose c, { a4. e8 r e g e } +\score { + < + \apply #(drums->paper 'drums) \context Staff = drums < + \clef percussion + \context Voice = up { \voiceOne \up } + \context Voice = down { \voiceTwo \down } + > + \context Staff = bass { \clef "F_8" \bass } + > +} +@end lilypond + +@subsubsection Percussion midi output +In order to produce correct midi output you need to produce two score +blocks - one for the paper and one for the midi. +To use the percussion channel you set the property @code{instrument} +to @code{'drums}. Because the drum-pitches themself are similar to the +general midi pitches all you have to do is to insert the voices with +none of the scheme functions to get the correct midi output: + +@example +\score @{ + \apply #(drums->paper 'mydrums) \context Staff < + \clef percussion + \context Voice = up @{ \voiceOne \up @} + \context Voice = down @{ \voiceTwo \down @} + > + \paper@{@} +@} +\score @{ + \context Staff < + \property Staff.instrument = #'drums + \up \down + > + \midi@{@} +@} +@end example + +@refbugs + +This scheme is to be considered a temporary implementation. Even +though the scheme will probably keep on working then the future might +bring some other way of typesetting drums, and probably +there will be made no great efforts in keeping things downwards +compatible. + +@c . {Piano music} +@node Piano music +@section Piano music -@c . {Piano music} -@node Piano music -@section Piano music - Piano music is an odd type of notation. Piano staves are two normal staves coupled with a brace. The staves are largely independent, but sometimes voices can cross between the two staves. The @@ -1884,13 +2661,11 @@ other pianistic peculiarities. Voices can switch automatically between the top and the bottom staff. The syntax for this is @example - \autochange @var{contexttype} @var{musicexp} -@end example -This will switch the interpretation context of @var{musicexp} between a -@var{contexttype} named @code{up} and @code{down}. Typically, you use -@internalsref{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. + \autochange Staff \context Voice @{ @dots{}@var{music}@dots{} @} +@end example +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. Here is a practical example: @lilypond[verbatim,singleline] \score { \notes \context PianoStaff < @@ -1902,8 +2677,7 @@ over rests to switch rests in advance. s1*2 } > } @end lilypond - -Note how spacer rests are used to prevent the bottom staff from +Spacer rests are used to prevent the bottom staff from terminating too soon. @@ -1922,18 +2696,6 @@ current voice from its current staff to the Staff called @var{staffname}. Typically @var{staffname} is @code{"up"} or @code{"down"}. -The formal definition of this construct is obtuse, but for the sake of -completeness we give it here. -@cindex @code{\translator} -@example - \translator @var{contexttype} = @var{name} -@end example -Formally, this construct is a music expression indicating -that the context which is a direct child of the context of type -@var{contexttype} should be shifted to a context of type -@var{contexttype} and the specified name. - - @c . {Pedals} @node Pedals @subsection Pedals @@ -1961,7 +2723,9 @@ Pedals can also be indicated by a sequence of brackets, by setting the @lilypond[fragment,verbatim] \property Staff.SustainPedal \override #'pedal-type = #'bracket -c''4 \sustainDown d''4 e''4 a'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp +c''4 \sustainDown d''4 e''4 a'4 +\sustainUp \sustainDown + f'4 g'4 a'4 \sustainUp @end lilypond A third style of pedal notation is a mixture of text and brackets, @@ -1969,7 +2733,9 @@ obtained by setting @code{pedal-type} to @code{mixed}: @lilypond[fragment,verbatim] \property Staff.SustainPedal \override #'pedal-type = #'mixed -c''4 \sustainDown d''4 e''4 c'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp +c''4 \sustainDown d''4 e''4 c'4 +\sustainUp \sustainDown + f'4 g'4 a'4 \sustainUp @end lilypond The default '*Ped' style for sustain and damper pedals corresponds to @@ -1987,8 +2753,10 @@ For fine-tuning of the appearance of a pedal bracket, the properties may be extended to the end of the note head. @lilypond[fragment,verbatim] -\property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0) -c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp +\property Staff.PianoPedalBracket \override + #'shorten-pair = #'(0 . -1.0) +c''4 \sostenutoDown d''4 e''4 c'4 +f'4 g'4 a'4 \sostenutoUp @end lilypond @@ -2026,13 +2794,13 @@ are @code{PianoStaff.Arpeggio}. To add an arrow head to explicitly specify the direction of the arpeggio, you should set the arpeggio grob property -@code{arpeggio-type}. +@code{arpeggio-direction}. @lilypond[fragment,relative,verbatim] \context Voice { - \property Voice.Arpeggio \override #'arpeggio-direction = #1 + \property Voice.Arpeggio \set #'arpeggio-direction = #1 - \property Voice.Arpeggio \override #'arpeggio-direction = #-1 + \property Voice.Arpeggio \set #'arpeggio-direction = #-1 } @end lilypond @@ -2046,7 +2814,8 @@ arpeggiate the chord. To draw these brackets, set the @lilypond[fragment,relative,verbatim] \context PianoStaff < \property PianoStaff.connectArpeggios = ##t - \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket + \property PianoStaff.Arpeggio \override + #'molecule-callback = \arpeggioBracket \context Voice = one { } \context Voice = other { \clef bass } > @@ -2055,8 +2824,8 @@ arpeggiate the chord. To draw these brackets, set the @refbugs -It is not possible to mix connected arpeggios and unconnected arpeggios -at the same time. +It is not possible to mix connected arpeggios and unconnected +arpeggios in one PianoStaff at the same time. @@ -2088,219 +2857,105 @@ can be printed automatically. This is enabled if the property The associated grob is @internalsref{VoiceFollower}. -@node Lyrics -@section Lyrics +@node Tablatures +@section Tablatures +Tablature notation is used music for plucked string instruments. It +notates pitches not by using note heads, but by indicating on which +string and fret a note must be played. LilyPond offers limited +support for tablature, by abusing the fingering system. @menu -* Lyrics mode:: -* Printing lyrics:: -* Automatic syllable durations:: -* More stanzas:: +* Tablatures basic:: +* Non-guitar tablatures:: +* Tablature in addition to normal staff:: @end menu -@c . {Lyrics mode} -@node Lyrics mode -@subsection Lyrics mode -@cindex Lyrics mode - -To print lyrics, you must first make a music expression from the lyric -text. That music expression can be printed by selecting an appropriate -context. - -@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. - -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{"He could"4 not4} or by using an underscore without quotes: -@code{He_could4 not4}. All unquoted underscores are converted to -spaces. - -The precise definition of this mode can be found in @ref{Lyrics mode -definition}. - -@c . {Printing lyrics} -@node Printing lyrics -@subsection Printing lyrics -@cindex lyrics - -Lyrics are printed by interpreting them in the @internalsref{Lyrics} context. - -@c Maybe more pedagogical to avoid \addlyrics in this first example? /MB -@c Add tied and beamed melismata too. -@lilypond[verbatim,singleline] -\addlyrics - \notes \relative c' { - \time 7/4 - \property Staff.automaticMelismata = ##t - d'2 c4 b16 ( a g a b a b ) c a2 - b2 c4 b8 ( a16 g ) a4 g2 } - \context Lyrics \lyrics { - Join us now __ and - share the soft -- ware; } -@end lilypond - - -Notes and syllable durations are 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 tied, slurred or beamed notes to be -interpreted as melismata. - -The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs. - -@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{_}). -The grob for this symbol is @code{LyricsVoice.LyricExtender}. - - -@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 whose length varies depending on the space -between syllables. It will be centered between the syllables. The grob -for this symbol is @code{LyricsVoice.LyricHyphen}. +@node Tablatures basic +@subsection Tablatures basic +@cindex Tablatures basic -@cindex Lyric hyphen +Tablature can be typeset with Lilypond by using the +@internalsref{TabStaff} and @internalsref{TabVoice} contexts. As +tablature is a recent feature in Lilypond, most of the guitar special +effects such as hammer, pull, bend are not yet supported. -@node Automatic syllable durations -@subsection Automatic syllable durations -@cindex Automatic syllable durations +With the @internalsref{TabStaff}, the string number associated to a note +is given though the fingering mechanism, e.g. @code{c4-3} for a C +quarter on the third string. The string 1 is the lowest one, and the +tuning defaults to the standard guitar tuning (with 6 strings). -@cindex automatic lyric durations -@cindex @code{\addlyrics} - -If you have lyrics that are set to a melody, you can copy the rhythm -of that melody into the lyrics using @code{\addlyrics}. The syntax for -this is -@example - \addlyrics @var{musicexpr1 musicexpr2} -@end example - -Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every -music event (``every syllable'') in @var{musicexpr2} is interpreted only -when there are events in @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 } +@lilypond[fragment,verbatim] + \context TabStaff < + \notes { + \property Staff.Stem \override #'direction = #1 + + a,4-2 c'-5 a-4 e'-6 + e-3 c'-5 a-4 e'-6 + } + > @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: +@node Non-guitar tablatures +@subsection Non-guitar tablatures +@cindex Non-guitar tablatures -@lilypond[verbatim,fragment] -\addlyrics -\transpose c'' { - c8 () cis d8. e16 f2 -} -\context Lyrics \lyrics -< { do4 re fa sol } - { do8 re fa sol } > -@end lilypond +There are many ways to customize Lilypond tablatures. -It is valid (but probably not very useful) to use notes instead of -lyrics for @var{musicexpr2}. +First you can change the number of strings, by setting the number of +lines in the @internalsref{TabStaff}. You can change the strings +tuning. A string tuning is given as a Scheme list with one integer +number for each string, the number being the pitch of an open string. -@node More stanzas -@subsection More stanzas +Finally, it is possible to change the Scheme function to format the +tablature note text. The default is @var{fret-number-tablature-format}, +which uses the fret number, but for some instruments that may not use +this notation, just create your own tablature-format function. This +function takes three argument: the string number, the string tuning and +the note pitch. -@cindex phrasing -If you have multiple stanzas printed underneath each other, the vertical -groups of syllables should be aligned around punctuation. LilyPond can -do this if you tell it which lyric lines belong to which melody. +@node Tablature in addition to normal staff +@subsection Tablature in addition to normal staff +@cindex Tablature in addition to normal staff -To this end, give the Voice context an identity, and set the LyricsVoice -to a name starting with that identity followed by a dash. -In the following example, the Voice -identity is @code{duet}, and the identities of the LyricsVoices are -@code{duet-1} and @code{duet-2}. +It is possible to typeset both tablature and a "normal" staff, as +commonly done in many parts. +A common trick for that is to put the notes in a variables, and to hide +the fingering information (which correspond to the string number) for +the standard staff. -@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. } - > -} +@lilypond[verbatim] + part = \notes { + a,4-2 c'-5 a-4 e'-6 + e-3 c'-5 a-4 e'-6 + } + \score{ + \context StaffGroup < + \context Staff < + % Hide fingering number + \property Staff.Fingering \override #'transparent = ##t + + \part + > + \context TabStaff < + \property Staff.Stem \override #'direction = #1 + + \part + > + > + } @end lilypond -You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the -first system) and @code{LyricsVoice.stz} for the following -systems. Notice how you must surround dots with spaces in @code{\lyrics} -mode. - - - - -@cindex stanza numbering - @c . {Chords} @node Chords @section Chords @cindex Chords -LilyPond has support for both entering and printing chords. Chords are -characterized by a set of pitches. They are -internally stored as simultaneous music expressions. This means you can -enter chords by name and print them as note head, enter them as notes -and print them as chord names, or (the most common case) enter them by -name, and print them as name. - - +LilyPond has support for both entering and printing chords. @lilypond[verbatim,singleline] twoWays = \notes \transpose c'' { \chords { @@ -2316,9 +2971,15 @@ twoWays = \notes \transpose c'' { \context Voice \twoWays > } @end lilypond -Note that this example also shows that the chord printing routines do -not attempt to be intelligent. If you enter @code{f bes d}, it does not -interpret this as an inversion. +This example also shows that the chord printing routines do not try to +be intelligent. If you enter @code{f bes d}, it does not interpret +this as an inversion. + +As you can see chords really are a set of pitches. They are internally +stored as simultaneous music expressions. This means you can enter +chords by name and print them as notes, enter them as notes and print +them as chord names, or (the most common case) enter them by name, and +print them as name. @menu * Chords mode:: @@ -2333,24 +2994,9 @@ interpret this as an inversion. 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 formed by @emph{chord additions}. Additions 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 have two effects: they adds -the specified interval and all lower odd numbered intervals to the -chord, and they may lower or raise the specified interval. +(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. Throughout these examples, chords have been shifted around the staff using @code{\transpose}. @@ -2428,10 +3074,25 @@ so it becomes the lowest note in the chord. @end lilypond +The formal 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 formed by @emph{chord additions}. Additions 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 have two effects: they adds +the specified interval and all lower odd numbered intervals to the +chord, and they may lower or raise the specified interval. + + @refbugs -Implementation details are quite gory. For example @code{c:4} not only -adds a fourth, but also removes the third. +Implementation details are gory. For example @code{c:4} not only adds +a fourth, but also removes the third. @c . {Printing named chords} @@ -2473,7 +3134,9 @@ scheme = \chords { \property ChordNames.chordChanges = ##t \scheme } \context Staff \transpose c'' \scheme - > } + > +\paper{linewidth= 9.\cm} +} @end lilypond LilyPond examines chords specified as lists of notes to determine a name @@ -2547,10 +3210,10 @@ problems in orchestral music. * Bar numbers:: * Instrument names:: * Transpose:: -* Sound output for transposing instruments:: * Multi measure rests:: * Automatic part combining:: * Hara kiri staves:: +* Sound output for transposing instruments:: @end menu @c . {Rehearsal marks} @@ -2560,31 +3223,46 @@ problems in orchestral music. @cindex mark @cindex @code{\mark} - -@example - \mark @var{unsigned} - \mark @var{string} - \mark \default -@end example - -This command prints a rehearsal mark above the system. You can provide -a number, a string or a markup text as argument. If you use -@code{\default}, the value of property @code{rehearsalMark} is used and -automatically incremented. - +To print a rehearsal mark, use the @code{\mark} command. @lilypond[fragment,verbatim] \relative c'' { - c1 \mark "A2" + c1 \mark "A" c1 \mark \default c1 \mark \default c1 \mark "12" - c1 \mark #'(music "scripts-segno") + c1 \mark \default c1 } @end lilypond -The grob is @internalsref{RehearsalMark} in @internalsref{Score} context. See -@code{input/test/boxed-molecule.ly} if you need boxes around the marks. +As you can see, the mark is incremented automatically if you use +@code{\mark \default}. The value to use is stored in the property +@code{rehearsalMark} is used and automatically incremented. The grob +is @internalsref{RehearsalMark} in @internalsref{Score} context. See +@code{input/test/boxed-molecule.ly} if you need boxes around the +marks. + +The @code{\mark} command can also be used to put signs like coda, +segno and fermatas on a barline. The trick is to use the text markup +mechanism to access the fermata symbol. +@lilypond[fragment,verbatim,relative=1] + c1 \mark #'(music "scripts-ufermata") + c1 +@end lilypond + +The problem is that marks that occur at a line break are typeset only +at the beginning of the next line, opposite to what you want for the +fermata. This can be corrected by the following property setting +@example +\property Score.RehearsalMark \override + #'visibility-lambda = #begin-of-line-invisible +@end example + +@cindex fermatas +@cindex coda +@cindex segno +@cindex barlines, putting symbols on + @node Bar numbers @subsection Bar numbers @@ -2594,9 +3272,9 @@ The grob is @internalsref{RehearsalMark} in @internalsref{Score} context. See @cindex measure numbers @cindex currentBarNumber -Bar numbers are @internalsref{BarNumber} grobs. They are printed at the -start of the line. The number itself is a property that can be set by -modifying the @code{currentBarNumber} property, i.e. +Bar numbers are printed by default at the start of the line. The +number itself is a property that can be set by modifying the +@code{currentBarNumber} property, i.e. @example \property Score.currentBarNumber = #217 @end example @@ -2604,18 +3282,24 @@ modifying the @code{currentBarNumber} property, i.e. If you want boxed bar numbers, see the example file @code{input/test/boxed-molecule.ly}. +See also @seeinternals{BarNumber}. + @refbugs -It is not possible to have bar numbers printed at regular intervals -only. +Printing bar numbers at regular intervals is not implemented. +Barnumbers can collide with the StaffGroup, if there is one at the +top. To solve this, You have to twiddle with the +@internalsref{padding} property of @internalsref{BarNumber} if your +score starts with a @internalsref{StaffGroup}. @node Instrument names @subsection Instrument names -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. +In scores, the instrument name is printed before the staff. This can +be done 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] \property Staff.instrument = "ploink " { c''4 } @@ -2663,36 +3347,20 @@ This means that middle C in @var{musicexpr} is transposed to a tone. The first version will print sharps and the second version will print flats. -@lilypond[fragment,verbatim] -\context Staff { - \clef "F" - { \key e \major c d e f } +@lilypond[singleline, verbatim] +mus =\notes { \key d \major cis d fis g } +\score { \notes \context Staff { + \clef "F" \mus \clef "G" - \transpose des'' { \key e \major c d e f } - \transpose cis'' { \key e \major c d e f } -} + \transpose g'' \mus + \transpose f'' \mus +}} @end lilypond 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}. -@node Sound output for transposing instruments -@subsection Sound output transposing instruments - -When you want to make a MIDI file from 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. - -@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 @@ -2709,7 +3377,8 @@ Lily will not expand empty measures, and the appropriate number is added automatically. @lilypond[fragment,verbatim] - \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 + \time 3/4 r2. | R2. | R2.*2 + \property Score.skipBars = ##t R2.*17 R2.*4 @end lilypond Notice that the @code{R2.} is printed as a whole rest, centered in the @@ -2721,8 +3390,9 @@ The grob for this object is @internalsref{MultiMeasureRest}. @refbugs -Currently, there is no way to automatically condense multiple rests into -a single multimeasure rest. +Currently, there is no way to automatically condense multiple rests +into a single multimeasure rest. Multi measure rests do not take part +in rest collisions. @cindex condensing rests @@ -2735,9 +3405,10 @@ a single multimeasure rest. Automatic part combining is used to merge two parts of music onto a staff in an intelligent way. It is aimed primarily at typesetting orchestral scores. When the two parts are identical for a period of -time, only one is shown. In places where the two parts differ, they are -typeset as separate voices, and stem directions are set automatically. -Also, solo and @emph{a due} parts can be identified and marked. +time, only one is shown. In places where the two parts differ, they +are typeset as separate voices, and stem directions are set +automatically. Also, solo and @emph{a due} parts can be identified +and marked. The syntax for part combining is @@ -2846,10 +3517,54 @@ example disappears in the second line. @end lilypond +@node Sound output for transposing instruments +@subsection Sound output for transposing instruments + +When you want to make a MIDI file from 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. + +@cindex @code{transposing} + +@example + \property Staff.instrument = #"Cl. in B-flat" + \property Staff.transposing = #-2 +@end example + + @c . {Custodes} +@node Ancient notation +@section Ancient notation + +@menu +* Ancient note heads:: +* Custodes:: +* Ancient clefs :: +* Figured bass:: +@end menu + + +@node Ancient note heads +@subsection Ancient note heads + + To get a longa note head, you have to use mensural note heads. This +is accomplished by setting the @code{style} property of the +NoteHead grob to @code{mensural}. There is also a note head style +@code{baroque} which gives mensural note heads for @code{\longa} and +@code{\breve} but standard note heads for shorter notes. + +@lilypond[fragment,singleline,verbatim] + \property Voice.NoteHead \set #'style = #'mensural + \property Voice.NoteHead \set #'font-family = #'ancient + a'\longa +@end lilypond + @node Custodes -@section Custodes +@subsection Custodes + @cindex Custos @cindex Custodes @@ -2906,43 +3621,147 @@ block: @} @end example +@node Ancient clefs +@subsection Ancient clefs -@c . {Figured bass} -@node Figured bass -@section Figured bass - -@cindex Basso continuo - -TODO. see figured-bass.ly - -@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. - -Formatting is internally done by manipulating 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. - -The most direct way of tuning the output is by altering 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 in that object. +LilyPond supports a variety of clefs, many of them ancient. These can +be selected from the @code{ancient} font family, by setting +@code{Staff.clefGlyph}) to one of the following values + +@table @code +@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 table + +@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 + + +@node Figured bass +@subsection Figured bass + +@cindex Basso continuo + +LilyPond has limited support for figured bass: + +@lilypond[verbatim,fragment] +< + \context FiguredBass + \figures { + <_! 3+ 5- >4 + < [4 6] 8 > + } + \context Voice { c4 g8 } +> +@end lilypond + +The support for figured bass consists of two parts: there is an input +mode, introduced by @code{\figures}, where you can enter bass figures +as numbers, and there is a context called @internalsref{FiguredBass} +that takes care of making @internalsref{BassFigure} grobs. + +In figures input mode, a group of bass figures is delimited by +@code{<} and @code{>}. The duration is entered after the @code{>}. +@example + <4 6> +@end example +@lilypond[fragment] +\context FiguredBass +\figures { <4 6> } +@end lilypond + +Accidentals are added to the numbers if you alterate them by +appending @code{-}, @code{!} and @code{+}. + +@example + <4- 6+ 7!> +@end example +@lilypond[fragment] + \context FiguredBass +\figures { <4- 6+ 7!> } +@end lilypond + +Spaces or dashes may be inserted by using @code{_}. Brackets are +introduced with @code{[} and @code{]}. + +@example + < [4 6] 8 [_ 12]> +@end example +@lilypond[fragment] + \context FiguredBass +\figures { < [4 6] 8 [_ 12]> } +@end lilypond + +Although the support for figured bass may superficially resemble chord +support, it works much simpler: in figured bass simply stores the +numbers, and then prints the numbers you entered. There is no +conversion to pitches, and no realizations of the bass are played in +the MIDI file. + + +@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. + +Formatting is internally done by manipulating 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. + +The most direct way of tuning the output is by altering 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 in that object. @menu * Tuning groups of grobs :: * Tuning per grob :: -* What to tune?:: * Font selection:: * Text markup:: -* Invisible grobs:: -* Dirty tricks:: @end menu @node Tuning groups of grobs @@ -2957,7 +3776,7 @@ context property. By assigning to that property (using plain @code{\property}), you can change the resulting grobs. @lilypond[verbatim, fragment] -c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4 +c'4 \property Voice.Stem = #'() @end lilypond The @code{\property} assignment effectively empties the definition of @@ -3063,15 +3882,6 @@ 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. -Some grobs are created at the moment that their context is created. An -example of such a grob is the staff itself (i.e. the horizontal lines). -You can not change the appearance of the staff symbol by manipulating -@code{\property Staff.StaffSymbol}. At the moment that @code{\property -Staff} is interpreted, a Staff context is made, and the StaffSymbol is -created before any @code{\override} is effective. You can deal with this -either overriding properties in a @code{\translator} definition, or by -using @code{\outputproperty}. - @@ -3135,59 +3945,48 @@ the syntax and semantics are up for rewrite. -@node What to tune? -@subsection What to tune? - -This all tells you how to tune grobs, but you don't know what variables -to set? The question is not answered in this part of the manual -(although you may encounter some examples.). - -Grob properties are tied directly to the implementation of LilyPond, and -they are thus a moving target. Documentation of such variables is in the -automatically generated documentation. Description of properties are -generated from the source code for each version. This documentation is -therefore more up to date. It should be available from the same place -where you got this manual. - -To decide how to tune a grob, you need to find the following information -@itemize @bullet -@item -which grob to modify -@item -which property to modify -@item -which context the grob comes from. -@end itemize - -Included with the automatically generated documentation is a master list -of grobs. Selecting a grob will take you to an overview of the -properties available for that grob. - -There is also a master list of contexts. Selecting one takes you to an -overview of that context which lists which grob types are created there. - - @node Font selection @subsection Font selection -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 La@TeX{}'s New -Font Selection Scheme. Within this scheme, a font is entirely -characterized by its font name. +The most common thing to change about the appearance of fonts is +their size. The font size of a @internalsref{Voice}, +@internalsref{Staff} or @internalsref{Thread} context, can be easily +changed by setting the @code{fontSize} property for that context: +@lilypond[fragment,relative=1] + c4 c4 \property Voice.fontSize = #-1 + f4 g4 +@end lilypond + This command will not change the size of variable symbols, such as +beams or slurs. You can use this command to get smaller symbol for +cue notes, but that involves some more subtleties. An elaborate +example of those is in @file{input/test/cue-notes.ly}. + +@cindex cue notes +@cindex font size +@cindex size -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: +The font used for printing a grob can be selected by setting +@code{font-name}, e.g. +@example + \property Staff.TimeSignature + \set #'font-name = #"cmr17" +@end example +You may use any font which is available to @TeX{}, such as foreign +fonts or fonts that do not belong to the Computer Modern font family. +Font selection for the standard fonts, @TeX{}'s Computer Modern fonts, +can also be adjusted with a more fine-grained mechanism. By setting +the grob properties described below, you can select a different font. +All three mechanisms work for every grob that supports +@code{font-interface}. @table @code @item font-family A symbol indicating the general class of the typeface. Supported are -@code{roman} (Computer Modern), @code{braces} (for piano staff braces), -@code{music} (the standard music font), @code{dynamic} (font for dynamic -signs) and @code{typewriter} - +@code{roman} (Computer Modern), @code{braces} (for piano staff +braces), @code{music} (the standard music font), @code{ancient} (the +ancient notation font) @code{dynamic} (font for dynamic signs) and +@code{typewriter}. + @item font-shape A symbol indicating the shape of the font, there are typically several font shapes available for each font family. Choices are @code{italic}, @@ -3208,56 +4007,41 @@ 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, e.g. @code{cmr}, -@code{cmti}, etc. Setting this overrides font-family, font-shape and -font-series. - - +which enhances readability. @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. - +For any of these properties, the value @code{*} (i.e. the @emph{symbol}, +@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used +to override default setting, which are always present. For example: @example - \property Lyrics.LyricText \override #'font-series = #'bold - \property Lyrics.LyricText \override #'font-shape = #'* + \property Lyrics . LyricText \override #'font-series = #'bold + \property Lyrics . LyricText \override #'font-family = #'typewriter + \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 @code{volta}, @code{finger}, @code{tuplet}, -@code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large} -and @code{dynamic}. - -The style sheets and tables for selecting fonts are located in -@file{scm/font.scm}. Refer to this file for more information. - +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 @code{volta}, @code{finger}, +@code{tuplet}, @code{timesig}, @code{mmrest}, @code{script}, +@code{large}, @code{Large} and @code{dynamic}. The style sheets and +tables for selecting fonts are located in @file{scm/font.scm}. Refer +to this file for more information. -Setting @code{font-name} overrides all other qualifiers. The value for -this property should be a string, the file name of the font. You may use -this to use special fonts, which are not a part of the style sheet, or -which have special encodings. +@cindex magnification -The size of the font may be set with the grob property -@code{font-magnification}. It is the size of font, relative to its -standard size. For example, @code{1.0} is normal size. +The size of the font may be scaled with the grob property +@code{font-magnification}. For example, @code{2.0} blows up all +letters by a factor 2 in both directions. @refbugs Relative size is not linked to any real size. There is no style sheet provided for other fonts besides the @TeX{} -family. +family, and the style sheet can not be modified easiyl. @cindex font selection @cindex font magnification @@ -3304,7 +4088,7 @@ which are prepended to the property list. The @var{key}-@var{value} pair is a grob property. A list of properties available is included in the generated documentation for @rint{Text_interface}. -The following abbreviations are currently defined: +The following abbreviations are defined: @table @code @item columns horizontal mode: set all text on one line (default) @@ -3378,220 +4162,194 @@ marking: } @end lilypond -@node Invisible grobs -@subsection Invisible grobs -@cindex invisible grobs - -@ignore - -ben nog steeds niet kapot van de informatiedichtheid hier. - ---hwn - -@end ignore - -You can imagine a number of situations where you would want to make -certain grobs not show up in the output. There may be aesthetic -reasons, to make the output resemble an (old) manuscript as close as -possible, or to make lessons or exercises for students. - -Grobs can be made invisible in a number of ways: - -Here's an example with blanked-out notes and stems: -@lilypond[singleline,verbatim] -blanknotes = { - \property Voice.NoteHead \override - #'transparent = ##t - \property Voice.Stem \override - #'transparent = ##t } - -unblanknotes = { - \property Voice.NoteHead \revert #'transparent - \property Voice.Stem \revert #'transparent } - -\score { - \notes\relative c'' { - \time 6/4 - a b c b \blanknotes c \unblanknotes d - } -} -@end lilypond -This method makes the grobs invisible but they still take the normal space. -To remove all traces of the grob, you can redefine the function -typesetting them: -@lilypond[verbatim] -\score { - \notes\relative c'' { - \key c \minor - \time 6/4 - as bes c bes c d \break - \property Staff.KeySignature \override #'molecule-callback = #'() - as bes c bes c d - } - \paper{linewidth=5.0\cm indent=0} -} -@end lilypond - -A very rigorous way of removing grobs from the whole score is to remove -the engraver that creates them. For example, - -@lilypond[singleline,verbatim] -\score {\notes { c'4 d'8 e'8 g2 } - \paper { \translator { - \VoiceContext - \remove Stem_engraver - } } -} -@end lilypond - -@node Dirty tricks -@subsection Dirty tricks -@cindex embedded tex +@refbugs -It is possible to use @TeX{} commands in the strings, but this should be -avoided because it 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 (see @ref{PostScript -output}). +The syntax and semantics of markup texts are not clean, and both +syntax and semantics are slated for a rewrite. -@lilypond[fragment,relative,verbatim] - a'^"3 $\\times$ \\`a deux" -@end lilypond +LilyPond does not do kerning, and there generally spaces texts +slightly too wide. -You can also use raw PostScript commands embedded in text scripts. This -offers ultimate flexibility, but requires you to learn PostScript. -Currently, embedded PostScript will @strong{not} work with direct -PostScript output. Note that all dimensions that you use are in staff -space. -@lilypond[verbatim] -\score { - \notes \relative c'' { - a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}" - -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}" - b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}" - s2 - a'1 - } - \paper { linewidth = 70*\staffspace } -} -@end lilypond +@node Global layout +@section Global layout -@c . {Page layout} -@node Page layout -@section Page layout -@cindex Page layout +The global layout determined by three factors: the page layout, the +iline breaks and the spacing. These all influence each other: The +choice of spacing determines how densely each system of music is set, +whree line breaks breaks are chosen, and thus ultimately how many +pages a piece of music takes. In this section we will explain how the +lilypond spacing engine works, and how you can tune its results. -The page layout is the combined product of LilyPond formatting notation, -and (La)@TeX{} putting the notation on a page, including page breaks. -The part of LilyPond is documented here. +Globally spoken, this procedure happens in three steps: first, +flexible distances (``springs'') are chosen, based on durations. All +possible line breaking combination are tried, and the one with the +best results---a layout that has uniform density and requires as +little stretching or cramping as possible---is chosen. When the score +is processed by @TeX{}, page are filled with systems, and page breaks +are chosen whenever the page gets full. @menu -* Paper block:: -* Paper variables:: +* Vertical spacing:: +* Horizontal spacing:: * Font Size:: -* Paper size:: -* Line break:: -* Page break:: -* Output scaling:: +* Line breaking:: +* Page layout:: @end menu -@c . {Paper block} -@node Paper block -@subsection Paper block -@cindex Paper block - -The most important output definition is the @code{\paper} block, for -music notation. The syntax is - -@example - @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} -@end example - -where each of the items is one of -@itemize @bullet - @item An assignment. - - @item A context definition. See @ref{Interpretation context} for - more information on context definitions. - - @item \stylesheet declaration. Its syntax is - @example - \stylesheet @var{alist} - @end example - - See @file{scm/font.scm} for details of @var{alist}. - @item an @code{\elementdescriptions} declaration. - @example - \elementdescriptions @var{alist} - @end example - See @file{scm/grob-description.scm} for details of -@var{alist}. This command is not user-serviceable. +@node Vertical spacing +@subsection Vertical spacing -@end itemize - -@c . {Paper variables} -@node Paper variables -@subsection Paper variables -@cindex Paper variables +@cindex vertical spacing +@cindex distance between staffs +@cindex staff distance +@cindex between staves, distance -The paper block has some variables you may want to use or change: +The height of each system is determined automatically by lilypond, to +keep systems from bumping into each other, some minimum distances are +set. By changing these, you can put staffs closer together, and thus +put more systems onto one page. -@table @code -@cindex @code{indent} - @item @code{indent} - The indentation of the first line of music. -@cindex @code{staffspace} +Normally staves are stacked vertically. To make +staves maintain a distance, their vertical size is padded. This is +done with the property @code{minimumVerticalExtent}. It takes a pair +of numbers, so if you want to make it smaller from its, then you could +set +@example + \property Staff.minimumVerticalExtent = #'(-4 . 4) +@end example +This sets the vertical size of the current staff to 4 staff-space on +either side of the center staff line. The argument of +@code{minimumVerticalExtent} is interpreted as an interval, where the +center line is the 0, so the first number is generally negative. you +could also make the staff larger at the bottom by setting it to +@code{(-6 . 4)}. The default value is @code{(-6 . 6)}. + +Vertical aligment of staves is handled by the +@internalsref{VerticalAlignment} grob, which lives at +@internalsref{Score} level. + +The piano staffs are handled a little differently: to make cross-staff +beaming work correctly, it necessary that the distance between staves +is fixed. This is also done with a @internalsref{VerticalAlignment} +grob, created in @internalsref{PianoStaff}, but a forced distance is +set. This is done with the grob property #'forced-distance. If you +want to override this, use a @code{\translator} block as follows: +@example + \translator @{ + \PianoStaffContext + VerticalAlignment \override #'forced-distance = #9 + @} +@end example +This would bring the staffs together at a distance of 9 staff spaces, +and again this is measured from the center line of each staff. - @item @code{staffspace} - The distance between two staff lines, calculated from the center - of the lines. -@cindex @code{linewidth} - @item @code{linewidth} - Sets the width of the lines. -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. +@node Horizontal spacing +@subsection Horizontal Spacing -@cindex @code{textheight} +The spacing engine translates differences in durations into +stretchable distances (``springs'') of differing lengths. Longer +durations get more space, shorter durations get less. The basis for +assigning spaces to durations, is that the shortest durations get a +fixed amount of space, and the longer durations get more: doubling a +duration adds a fixed amount of space to the note. - @item @code{textheight} - Sets the total height of the music on each page. Only used by -@code{ly2dvi}. +For example, the following piece contains lots of half, quarter and +8th notes, the eighth note is followed by 1 note head width. The The +quarter note is followed by 2 NHW, the half by 3 NHW, etc. +@lilypond[fragment, verbatim, relative=1] + c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4 +@end lilypond -@cindex @code{interscoreline} +These two amounts of space are @code{shortest-duration-space} +@code{spacing-increment}, grob properties of +@internalsref{SpacingSpanner}. Normally @code{spacing-increment} is +set to 1.2, which is the width of a note head, and +@code{shortest-duration-space} is set to 2.0, meaning that the +shortest note gets 2 noteheads of space. For normal notes, this space +is always counted from the left edge of the symbol, so the short notes +in a score is generally followed by one note head width of space. + +If one would follow the above procedure exactly, then adding a single +32th note to a score that uses 8th and 16th notes, would widen up the +entire score a lot. The shortest note is no longer a 16th, but a 64th, +thus adding 2 noteheads of space to every note. To prevent this, the +shortest duration for spacing is not the shortest note in the score, +but the most commonly found shortest note. Notes that are even +shorter this are followed by a space that is proportonial to their +duration relative to the common shortest note. So if we were to add +only a few 16th notes to the example above, they would be followed by +half a NHW: + +@lilypond[fragment, verbatim, relative=1] + c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4 +@end lilypond - @item @code{interscoreline} - Sets the spacing between systems. The default is 16pt. - -@cindex @code{interscorelinefill} +The most common shortest duration is determined as follows: in every +measure, the shortest duration is determined. The most common short +duration, is taken as the basis for the spacing, with the stipulation +that this shortest duration should always be equal to or shorter than +1/8th note. The shortest duration is printed when you run lilypond +with @code{--verbose}. These durations may also be customized. If you +set the @code{common-shortest-duration} in +@internalsref{SpacingSpanner}, then this sets the base duration for +spacing. The maximum duration for this base (normally 1/8th), is set +through @code{base-shortest-duration}. + +@cindex @code{common-shortest-duration} +@cindex @code{base-shortest-duration} +@cindex @code{stem-spacing-correction} +@cindex @code{spacing} + +In the introduction it was explained that stem directions influence +spacing. This is controlled with @code{stem-spacing-correction} in +@internalsref{NoteSpacing}. The @code{StaffSpacing} grob contains the +same property for controlling the stem/barline spacing. In the +following example shows these corrections, once with default settings, +and once with exaggerated corrections. + +@lilypond + \score { \notes { + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + \property Staff.NoteSpacing \override #'stem-spacing-correction + = #1.5 + \property Staff.StaffSpacing \override #'stem-spacing-correction + = #1.5 + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + } + \paper { linewidth = -1. } } +@end lilypond - @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. - Not set by default. +@refbugs -@cindex @code{stafflinethickness} +Spacing is determined on a score wide basis. If you have a score that +changes its character (measured in durations) half way during the +score, the part containing the longer durations will be spaced too +widely. - @item @code{stafflinethickness} - Determines the thickness of staff lines, and also acts as a scaling - parameter for other line thicknesses. -@end table +Generating optically pleasing spacing is black magic. LilyPond tries +to deal with a number of frequent cases. Here is an example that is +not handled correctly, due to the combination of chord collisions and +kneed stems. -You may enter these dimension using units (@code{cm}, @code{in}, -@code{mm}, @code{pt}), or relative to another dimension -@example - linewidth = 20.0 * \staffspace - indent = 0.5 \cm -@end example +@lilypond +\score { + \context PianoStaff \notes \transpose c''' < + \context Staff = up { s1 } + \context Staff = down { [c8 c \translator Staff=up c +\translator Staff=down c c c] } + > + \paper { linewidth = -1 } +} +@end lilypond @c . {Font size} @@ -3601,17 +4359,18 @@ You may enter these dimension using units (@code{cm}, @code{in}, @cindex staff size, setting @cindex @code{paper} file -The Feta font provides musical symbols at six different sizes. These -fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26 -point. The point size of a font is the height of the five lines in a -staff when displayed in the font. +The Feta font provides musical symbols at seven different sizes. +These fonts are 11 point, 13 point, 16 point, 19 pt, 20 point, 23 +point, and 26 point. The point size of a font is the height of the +five lines in a staff when displayed in the font. Definitions for these sizes are the files @file{paperSZ.ly}, where -@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of -these files, the identifiers @code{paperEleven}, @code{paperThirteen}, -@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and -@code{paperTwentysix} are defined respectively. The default -@code{\paper} block is also set. These files should be imported at toplevel, i.e. +@code{SZ} is one of 11, 13, 16, 19, 20, 23 and 26. If you include any +of these files, the identifiers @code{paperEleven}, +@code{paperThirteen}, @code{paperSixteen}, @code{paperNineteen}, +@code{paperTwenty}, @code{paperTwentythree}, and @code{paperTwentysix} +are defined respectively. The default @code{\paper} block is also +set. These files should be imported at toplevel, i.e. @example \include "paper26.ly" \score @{ ... @} @@ -3621,34 +4380,9 @@ The font definitions are generated using a Scheme function. For more details, see the file @file{scm/font.scm}. - -@c . {Paper size} -@node Paper size -@subsection Paper size -@cindex Paper size - -@cindex paper size -@cindex page size -@cindex @code{papersize} - -To change the paper size, you must first set the -@code{papersize} paper variable variable. Set it to -the strings @code{a4}, @code{letter}, or @code{legal}. After this -specification, you must set the font as described above. If you want -the default font, then use the 20 point font. - -@example - \paper@{ papersize = "a4" @} - \include "paper16.ly" -@end example - -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 -Lilypond and @code{ly2dvi}) - @c . {Line break} -@node Line break -@subsection Line break +@node Line breaking +@subsection Line breaking @cindex line breaks @cindex breaking lines @@ -3657,16 +4391,20 @@ Line breaks are normally computed automatically. They are chosen such that it looks neither cramped nor loose, and that consecutive lines have similar density. -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 bar lines. If you want to have a line break where there is no -bar line, you can force an invisible bar line by entering @code{\bar -""}. Similarly, @code{\noBreak} forbids a line break at a certain point. +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. Line breaks can only occur at places where there are bar +lines. If you want to have a line break where there is no bar line, +you can force an invisible bar line by entering @code{\bar +""}. Similarly, @code{\noBreak} forbids a line break at a certain +point. + + +@cindex regular line breaks +@cindex four bar music. If you want linebreaks at regular intervals, you can use the following: @example - < \repeat 7 unfold @{ s1 * 4 \break @} @emph{real music} > @@ -3674,230 +4412,76 @@ If you want linebreaks at regular intervals, you can use the following: This makes the following 28 measures (assuming 4/4 time) be broken every 4 measures. +@node Page layout +@subsection Page layout -@cindex @code{\penalty} - -The @code{\break} and @code{\noBreak} commands are defined in terms of -the penalty command: -@example - \penalty @var{int} -@end example +@cindex page breaks +@cindex breaking pages -This encourages or discourages LilyPond to make a line break at this -point. +@cindex @code{indent} +@cindex @code{linewidth} -@refbugs +The most basic settings influencing the spacing are @code{linewidth} +and @code{indent}, both set in the @code{\paper} block. They control +the indentation of the first line of music, and the lengths of the +lines. If @code{linewidth} set to a negative value, a single +unjustified line is produced. A similar effect for scores that are +longer than one line, can be produced by setting @code{raggedright} to +true in the @code{\paper} block. + +@cindex page layout + +The page layout process happens outside lilypond. Ly2dvi sets page +layout instructions. Ly2dvi responds to the following variables in the +@code{\paper} block. The variable @code{textheight} sets the total +height of the music on each page. The spacing between systems is +controlled with @code{interscoreline}, its default is 16pt. +The distance between the score lines will stretch in order to fill the +full page @code{interscorelinefill} is set to a positive number. In +that case @code{interscoreline} specifies the minimum spacing. -The scaling of the @code{\penalty} argument is not well-defined. The -command is rather kludgey, and slated for rewriting. +@cindex @code{textheight} +@cindex @code{interscoreline} +@cindex @code{interscorelinefill} -@c . {Page break} -@node Page break -@subsection Page break +If the variable @code{lastpagefill} is defined (that is, it gets any +value assigned in the @code{\paper} block), systems are evenly +distributed vertically on the last page. This might produce ugly +results in case there are not enough systems on the last page. Note +that @command{lilypond-book} ignores @code{lastpagefill}. See +@ref{Insert music snippets into your texts using lilypond-book} for +more information. -@cindex page breaks -@cindex breaking pages +@cindex @code{lastpagefill} 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, by inserting -the command @code{\newpage} -@cindex @code{\newpage} +direct control of LilyPond. However, you can insert a commands into +the @file{.tex} output to instruct @TeX{} where to break pages. You +can insert a @code{\newpage} from within lilypond. This is done by +setting the @code{between-systems-strings} on the +@internalsref{NonMusicalPaperColumn} where the system is broken. + +@cindex paper size +@cindex page size +@cindex @code{papersize} + +To change the paper size, you must first set the +@code{papersize} paper variable variable. Set it to +the strings @code{a4}, @code{letter}, or @code{legal}. After this +specification, you must set the font as described above. If you want +the default font, then use the 20 point font. @example - \newpage + \paper@{ papersize = "a4" @} + \include "paper16.ly" @end example -@c why do so difficult? -@c maybe should explain contents of between-system.ly, -@c but not now, we're talking about page breaks here. -@c For more -@c details, see the example file @file{input/test/between-systems.ly} - +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 +Lilypond and @code{ly2dvi}) -@c . {Output scaling} -@node Output scaling -@subsection Output scaling -[TODO] -@example -dvips ... -@end example - -@example -pstops ... -@end example - - -@refbugs - -There is no mechanism to select magnification of particular fonts, -meaning that you don't have access to continuously scaled fonts. - - - -@c . {Output formats} -@node Output formats -@section Output formats - -LilyPond can output processed music in different output formats. - -@menu -* TeX output:: -* PostScript output:: -* Scheme output:: -* ASCIIScript output:: -@end menu - -@node TeX output -@subsection TeX output -@cindex TeX output - -LilyPond will use @TeX{} by default. Even if you want to produce -PostScript output for viewing or printing, you should normally have -LilyPond produce @TeX{} first. The .tex output must be processed by -@TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips} -is used to generate PostScript. Alternatively, @file{ly2dvi} can be -used to generate the .dvi for you. - -@refbugs - -Titling is not generated unless you use @file{ly2dvi}. - - -@node PostScript output -@subsection PostScript output -@cindex PostScript output -@cindex direct PostScript output - -LilyPond can produce PostScript directly, without going through @TeX{}. -Currently, this is mainly useful if you cannot use TeX, because direct -PostScript output has some problems; see Bugs below. - -@example -$ lilypond -fps foo.ly -GNU LilyPond 1.3.144 -Now processing: `foo.ly' -Parsing... -Interpreting music...[3] -Preprocessing elements... -Calculating column positions... -paper output to foo.ps... - -$ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr -@end example - - -@refbugs - -Text font selection is broken. - -The .ps file does not contain the .pfa font files. To print a .ps -created through direct postscript output, you should prepend the -necessary .pfa files to LilyPond's .ps output, or upload them to the -printer before printing. - -The line height calculation is broken, you must set @var{lineheight} in -the paperblock if you have more than one staff in your score, e.g. - -@example - ... - \paper @{ - % Set line height to 40 staff spaces - lineheight = 40 - @} -@end example - -@node Scheme output -@subsection Scheme output -@cindex Scheme output - -In the typesetting stage, LilyPond builds a page description, which is -then written to disk in postscript, @TeX{} or ASCII art. Before it is -written, the page description is represented as Scheme expressions. You -can also dump these Scheme expressions to a file, which may be -convenient for debugging output routines. This is done with the Scheme -output format - -@example -$ lilypond -fscm foo.ly -GNU LilyPond 1.3.144 -Now processing: `foo.ly' -Parsing... -Interpreting music...[3] -Preprocessing elements... -Calculating column positions... -paper output to foo.scm... - -$ head -4 foo.scm -;;; Usage: guile -s x.scm > x.tex - (primitive-load-path 'standalone.scm) -; (scm-tex-output) - (scm-ps-output) - -$ guile -s foo.scm > foo.tex -@end example - - -@node ASCIIScript output -@subsection ASCIIScript output -@cindex ASCIIScript output -@cindex ascii script -@cindex ascii art - -LilyPond can output ASCII Art. This is a two step process, LilyPond -produces an ASCII description file, dubbed ASCIIScript (extension -@file{.as}). ASCIIScript has a small and simple command set that -includes font selection, character and string printing and line drawing -commands. The program @file{as2text} is used to translate an .as file -to text. - -To produce ASCII Art, you must include an ASCII Art paper definition -file in your .ly, one of: -@example -\include "paper-as5.ly" -\include "paper-as9.ly" -@end example - -Here's an example use for ASCII Art output (the example file -@file{as-email.ly} is included in the LilyPond distribution), the staff -symbol has been made invisible: - -@example -$ lilypond -fas as-email.ly -GNU LilyPond 1.3.144 -Now processing: `as-email.ly' -Parsing... -Interpreting music...[3] -Preprocessing elements... -Calculating column positions... [2] -paper output to as-email.as... - -$ as2text as-email.as 2>/dev/null - |\ - |/ |##|##| | | | | | - /| | | | | |\ |\ |\ |\ |\ | - / |_ 3 | | | | 5 | )| )| )| )| )| - | /| \ 8 * * * | 8 * * * * * | - \_|_/ | | - *_| - - lily -@end example - - -@refbugs - -The ASCII Art fonts are far from complete and not very well designed. -It's easy to change the glyphs, though; if you think you can do better, -have a look at @file{mf/*.af}. - -Lots of resizable symbols such as slurs, ties and tuplets are missing. - -The poor looks of most ASCII Art output and its limited general -usefulness gives ASCII Art output a low priority; it may be -dropped in future versions. @c . {Sound} @node Sound @@ -3925,10 +4509,6 @@ instruments and ranges or change the default settings by overriding the Both loudness controls are combined to produce the final MIDI volume. -@refbugs - -It is currently not possible to use the percussion channel (generally -channel 10 of a MIDI file). @menu * MIDI block:: @@ -3958,7 +4538,7 @@ Assignments in the @code{\midi} block are not allowed. Context definitions follow precisely the same syntax as within the \paper block. Translation modules for sound are called performers. -The contexts for MIDI output are defined in @file{ly/performer.ly}. +The contexts for MIDI output are defined in @file{ly/performer-init.ly}. @node MIDI instrument names @@ -3980,1173 +4560,3 @@ default (Grand Piano). It is not possible to select an instrument by number. - - - - - - -@c FIXME: Note entry vs Music entry at top level menu is confusing. -@c . {Music entry} -@node Music entry -@section Music entry -@cindex Music entry -@menu -* Relative:: -* Bar check:: -* Point and click:: -@end menu - -When entering music with LilyPond, it is easy to introduce errors. This -section deals with tricks and features that help you enter music, and -find and correct mistakes. - -@c . {Relative} -@node Relative -@subsection Relative -@cindex Relative -@cindex relative octave specification - -Octaves are specified by adding @code{'} and @code{,} to pitch names. -When you copy existing music, it is easy to accidentally put a pitch in -the wrong octave and hard to find such an error. To prevent these -errors, LilyPond features octave entry. - -@cindex @code{\relative} -@example - \relative @var{startpitch} @var{musicexpr} -@end example - -The octave of notes that appear in @var{musicexpr} are calculated as -follows: If no octave changing marks are used, the basic interval -between this and the last note is always taken to be a fourth or less -(This distance is determined without regarding alterations; a -@code{fisis} following a @code{ceses} will be put above the -@code{ceses}) - -The octave changing marks @code{'} and @code{,} can be added to raise or -lower the pitch by an extra octave. Upon entering relative mode, an -absolute starting pitch must be specified that will act as the -predecessor of the first note of @var{musicexpr}. - -Entering music that changes octave frequently is easy in relative mode. -@lilypond[fragment,singleline,verbatim,center] - \relative c'' { - 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'' } -@end lilypond - -If the preceding item is a chord, the first note of the chord is used -to determine the first note of the next chord. However, other notes -within the second chord are determined by looking at the immediately -preceding note. - -@lilypond[fragment,verbatim,center] - \relative c' { - c - - - } -@end lilypond -@cindex @code{\notes} - -The pitch after the @code{\relative} contains a note name. To parse -the pitch as a note name, 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}, -@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{|}: -@example - \time 3/4 c2 e4 | g2. -@end example - - - -@cindex skipTypesetting - -Failed bar checks are most often caused by entering incorrect -durations. Incorrect durations often completely garble up the score, -especially if it is polyphonic, so you should start correcting the score -by scanning for failed bar checks and incorrect durations. To speed up -this process, you can use @code{skipTypesetting} (See @ref{Skipping -corrected music})). Bar - - -@c . {Point and click} -@node Point and click -@subsection Point and click - -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 - -@unnumberedsubsec Installation - -@itemize @bullet -@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 - -Xdvi must be configured to find the TeX fonts and music -fonts. Refer to the Xdvi documentation for more information. - - -@unnumberedsubsec Using it - -Add one of 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} and @code{server.el}. - -@example -#(set! point-and-click line-location) -@end example - -In the emacs startup file (usually @file{~/.emacs}), add the following -@example -(server-start) -@end example - -Make sure that the environment variable @code{XEDITOR} is set -to -@example -emacsclient --no-wait +%l %f -@end example -The second one, that also specifies the column, only works if you have -patched your emacsclient and server, and have compiled your @code{.ly} -file using the @code{line-column-location} setting. - -When viewing, control-mousebutton 1 will take you to the originating -spot in the @file{.ly} file. Control-mousebutton 2 will show all -clickable boxes. - - -@unnumberedsubsec Column location - -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 -(e.g. @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 - -Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f} - -At the top of the @code{ly} file, replace the @code{set!} line with the -following line -@example -#(set! point-and-click line-column-location) -@end example - -One final hint: if you correct large files with point-and-click, then -start correcting at the end of the file. When you start at the top, and -insert one line, all subsequent locations will be off by a line. - - -@refbugs - -When you convert the @TeX{} file to PostScript using @code{dvips}, it -will complain about not finding @code{src:X:Y} files. Those complaints -are harmless, and can be ignored. - -@node Skipping corrected music -@section Skipping corrected music - -The property @code{Score.skipTypesetting} can be used to switch on and -off typesetting completely during the interpretation phase. When -typesetting is switched off, the music is processed much more quickly. -You can use this to skip over the parts of a score that you have already -checked for errors. - -@lilypond[fragment,singleline,verbatim] -\relative c'' { c8 d -\property Score.skipTypesetting = ##t - e f g a g c, f e d -\property Score.skipTypesetting = ##f -c d b bes a g c2 } -@end lilypond - - -@node Interpretation context -@section Interpretation context - -@menu -* Creating contexts:: -* Default contexts:: -* Context properties:: -* Engravers and performers:: -* Changing context definitions:: -* Defining new contexts:: -@end menu - - -Interpretation contexts are objects that only exist during a run of -LilyPond. During the interpretation phase of LilyPond (when it prints -"interpreting music"), the music expression in a @code{\score} block is -interpreted in time order. This is the same order that humans hear and -play the music. - -During this interpretation, the interpretation context holds the -state for the current point within the music. It contains information -like - -@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 - -Contexts are grouped hierarchically: A @internalsref{Voice} context is -contained in a @internalsref{Staff} context (because a staff can contain -multiple voices at any point), a @internalsref{Staff} context is contained in -@internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context. - -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called @emph{performance -contexts}. The default definitions of the standard notation and -performance contexts can be found in @file{ly/engraver.ly} and -@file{ly/performer.ly}, respectively. - - -@node Creating contexts -@subsection Creating contexts - -@cindex @code{\context} -@cindex context selection - -Contexts for a music expression can be selected manually, using the -following music expression. - -@example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example - -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. - -@lilypond[verbatim,singleline] -\score { - \notes \relative c'' { - c4 f - } -} - -@end lilypond - -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. - - - -@node Default contexts -@subsection Default contexts - -Most music expressions don't need an explicit @code{\context} -declaration: 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. - -@lilypond[verbatim,singleline] -\score { \notes \context Voice = goUp { c'4 d' e' } } -@end lilypond - -There are some quirks that you must keep in mind when dealing with -defaults: - -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 - -Second, contexts are created automatically to be able to interpret the -music expressions. Consider the following example. - -@lilypond[verbatim, singleline] -\score { \context Score \notes { c'4 ( d' )e' } } -@end lilypond - -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. - -This is a convenient mechanism, but do not expect opening chords to work -without @code{\context}. For every note, a separate staff is -instantiated. - -@cindex explicit context -@cindex starting with chords -@cindex chords, starting with - -@lilypond[verbatim, singleline] -\score { \notes } -@end lilypond - -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 - - - -@node Context properties -@subsection Context properties - -Notation contexts have properties. These properties are from -the @file{.ly} file using the following expression: -@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 Scheme expression @var{value}. All @var{propname} and -@var{contextname} are strings, which are typically unquoted. - -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@internalsref{Voice} context can be set in the @internalsref{Score} context (for -example) and thus take effect in all @internalsref{Voice} contexts. - -Properties can be unset using the following expression: -@example - \property @var{contextname}.@var{propname} \unset -@end example - -@cindex properties, unsetting -@cindex @code{\unset} - -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 - -The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not -the inverse of @code{\property \set}. - -@node Engravers and performers -@subsection Engravers and performers - -[TODO] - -Basic building blocks of translation are called engravers; they are -special C++ classes. - - - -@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 @{ - @var{context-identifier} - @} @} -@end example -Then you can add and remove engravers using the following syntax: -@example - \remove @var{engravername} - \consists @var{engravername} -@end example - - -Here @var{engravername} is a string, the name of an engraver in the -system. - - -@lilypond[verbatim,singleline] -\score { \notes { - c'4 c'4 } - \paper { - \translator { \StaffContext - \remove Clef_engraver - } } } -@end lilypond - -@cindex engraver - -You can also set properties in a translator definition. The syntax is as -follows: -@example - @var{propname} = @var{value} - @var{propname} \set @var{grob-propname} = @var{pvalue} - @var{propname} \override @var{grob-propname} = @var{pvalue} - @var{propname} \revert @var{grob-propname} -@end example -@var{propname} is a string, @var{grob-propname} a symbol, @var{value} -and @code{pvalue} are Scheme expressions. These type of property -assignments happen before interpretation starts, so a @code{\property} -command will override any predefined settings. - - - To simplify editing translators, all standard contexts have standard -identifiers called @var{name}@code{Context}, e.g. @code{StaffContext}, -@code{VoiceContext}, see @file{ly/engraver.ly}. - -@node Defining new contexts -@subsection Defining new contexts - -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}}. - - @item A cooperation module. This is specified by @code{\type -@var{typename}}. -@end itemize - -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 - -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. - -@cindex @code{Score_engraver} - - @item @code{Score_engraver} - This is cooperation module that should be in the top level context, -and only the top level context. - -@cindex @code{Grace_engraver_group} - - @item @code{Grace_engraver_group} - This is a special cooperation module (resembling - @code{Score_engraver}) that is used to create an embedded - `miniscore'. -@end table - -Other modifiers are - -@itemize @bullet - @item @code{\alias} @var{alternate-name} - This specifies a different name. In the above example, -@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s - - @item @code{\consistsend} @var{engravername} - 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 stay there even if a user adds or removes engravers. -End-users generally don't need this command. - - @item @code{\accepts} @var{contextname} - Add @var{contextname} to the list of contexts this context can - contain in the context hierarchy. 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{\name} @var{contextname} - This sets the type name of the context, e.g. @internalsref{Staff}, - @internalsref{Voice}. If the name is not specified, the translator won't do - anything. -@end itemize - -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 @{ - @dots{} - @} - \paper @{ - \translator @{ \foo @dots{} @} - @} -@} -@end example - -@end quotation - - -@cindex paper types, engravers, and pre-defined translators - - - - - - -@c . {Syntactic details} -@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 modes:: -* Ambiguities:: -@end menu - -@c . {Top level} -@node Top level -@subsection Top level -@cindex Top level - -This section describes what you may enter at top level. - - -@c . {Score} -@subsubsection Score -@cindex Score - -@cindex score definition - -The output is generated combining a music expression with an output -definition. A score block has the following syntax: - -@example - \score @{ @var{musicexpr} @var{outputdefs} @} -@end example - -@var{outputdefs} are zero or more output definitions. If none is -supplied, the default @code{\paper} block will be added. - - - -@c . {Default output} -@subsubsection Default output - -Default values for the @code{\paper} and @code{\midi} block are set by -entering such a block at the top level. - -@c . {Header} -@subsubsection Header -@cindex Header -@cindex @code{\header} - - -A header describes bibliographic 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, -meter, arranger, piece and tagline. - -@cindex @code{ly2dvi} - -The syntax is -@example - \header @{ @var{key1} = @var{val1} - @var{key2} = @var{val2} @dots{} @} -@end example - -It is customary to put the @code{\header} at the top of the file. - -@subsubsection Default output - -A @code{\midi} or @code{\paper} block at top level sets the default -paper block for all scores that lack an explicit paper block. - -@c . {Identifiers} -@node Identifiers -@subsection Identifiers -@cindex Identifiers - -@ignore - What has this section got to do with identifiers? - It seems more appropriate in the introduction to Chapter 4, - "Internals". - - /MB -@end ignore - -All of the information in a LilyPond input file, is internally -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 - -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,singleline] -#(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 { c'4_"foo" } -} -@end lilypond - -For more information on what is possible, see the automatically -generated documentation. - - -Directly accessing internal representations is dangerous: the -implementation is subject to changes, so you should avoid this feature -if possible. - -A final example is a function that reverses a piece of music in time: - -@lilypond[verbatim,singleline] -#(define (reverse-music music) - (let* ((elements (ly-get-mus-property music 'elements)) - (reversed (reverse elements)) - (span-dir (ly-get-mus-property music 'span-direction))) - (ly-set-mus-property music 'elements reversed) - (if (dir? span-dir) - (ly-set-mus-property music 'span-direction (- span-dir))) - (map reverse-music reversed) - music)) - -music = \notes { c'4 d'4( e'4 f'4 } - -\score { \context Voice { - \music - \apply #reverse-music \music - } -} -@end lilypond - -More examples are given in the distributed example files in -@code{input/test/}. - -@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} - -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, - -@lilypond[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" -@end lilypond - -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} -@node Assignments -@subsection Assignments -@cindex Assignments - -Identifiers allow objects to be assigned to names during the parse -stage. To assign an identifier, you use @var{name}@code{=}@var{value} -and to refer to an identifier, you precede its name with a backslash: -`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of -the input-types listed above. Identifier assignments can appear at top -level in the LilyPond file, but also in @code{\paper} blocks. - -An identifier can be created with any string for its name, but you will -only be able to refer to identifiers whose names begin with a letter, -being entirely alphabetical. It is impossible to refer to an identifier -whose name is the same as the name of a keyword. - -The right hand side of an identifier assignment is parsed completely -before the assignment is done, so it is allowed to redefine an -identifier in terms of its old value, e.g. - -@example -foo = \foo * 2.0 -@end example - -When an identifier is referenced, the information it points to is -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 -@} - -\paper @{ - \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 in addition to 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 expression -@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 just instruct the parser in what mode -to parse their arguments. The modes are treated in more detail in -@ref{Lyrics} and @ref{Chords}. - -Different input modes may be nested. - -@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 - is interpreted as the string identifier assignment. However, -it can also be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. - - @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 The parser is not sophisticated enough to distinguish at the -right time between - @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode). - -[checkme] - -@end itemize - - -@c . {Lexical details} -@node 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 - - -@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. - -@node Direct Scheme -@subsection Direct Scheme - -@cindex Scheme -@cindex GUILE -@cindex Scheme, in-line code - - -LilyPond contains a Scheme interpreter (the GUILE library) for -internal use. In some places, Scheme expressions also form valid syntax: -wherever it is allowed, -@example - #@var{scheme} -@end example -evaluates the specified Scheme code. Example: -@example - \property Staff.TestObject \override #'foobar = #(+ 1 2) -@end example -@code{\override} expects two Scheme expressions, so there are two Scheme -expressions. The first one is a symbol (@code{foobar}), the second one -an integer (namely, 3). - -In-line scheme may be used at the top level. In this case the result is -discarded. - -Scheme is a full-blown programming language, and a full discussion is -outside the scope of this document. Interested readers are referred to -the website @uref{http://www.schemers.org/} for more information on -Scheme. - - -@node Keywords -@subsection Keywords -@cindex Keywords - - -Keywords start with a backslash, followed by a number of lower case -alphabetic characters. These are all the keywords. - -@example -apply arpeggio autochange spanrequest commandspanrequest -simultaneous sequential accepts alternative bar breathe -char chordmodifiers chords clef cm consists consistsend -context denies duration dynamicscript elementdescriptions -font grace header in lyrics key mark pitch -time times midi mm name pitchnames notes outputproperty -override set revert partial paper penalty property pt -relative remove repeat addlyrics partcombine score -script stylesheet skip textscript tempo translator -transpose type -@end example - -@node Integers -@subsection Integers - -@cindex integers -@cindex @code{+} -@cindex @code{-} -@cindex @code{*} -@cindex @code{/} - -Formed from an optional minus sign followed by digits. Arithmetic -operations cannot be done with integers, and integers cannot be mixed -with reals. - -@node Reals -@subsection Reals -@cindex real numbers - - - - - -Formed from an optional minus sign and a sequence of digits followed -by a @emph{required} decimal point and an optional exponent such as -@code{-1.2e3}. Reals can be built up using the usual operations: -`@code{+}', `@code{-}', `@code{*}', and -`@code{/}', with parentheses for grouping. - -@cindex @code{\mm}, -@cindex @code{\in} -@cindex @code{\cm} -@cindex @code{\pt} -@cindex dimensions - -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 -a number that is the internal representation of that dimension. - - -@node Strings -@subsection Strings -@cindex string -@cindex concatenate - -Begins and ends with the @code{"} character. To include a @code{"} -character in a string write @code{\"}. Various other backslash -sequences have special interpretations as in the C language. A string -that contains no spaces can be written without the quotes. Strings can -be concatenated with the @code{+} operator. - - -@node Main input -@subsection Main input -@cindex Main input - -@cindex @code{\maininput} - -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. - -@node File inclusion -@subsection File inclusion -@cindex @code{\include} -@example - \include @var{filename} -@end example - -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, - - -@node Version information -@subsection Version information -@cindex @code{\version} -@example - \version @var{string} -@end example - -Specify the version of LilyPond that a file was written for. The -argument is a version string in quotes, for example @code{"1.2.0"}. -This is used to detect invalid input, and to aid -@code{convert-ly} a tool that automatically upgrades input files. See -See @ref{convert-ly} for more information on @code{convert-ly}. - -@cindex convert-ly - - - - - -@c broken with emacs-21 -@c {Local emac s vars} -@c Local varia bles: -@c mode: texi nfo -@c minor-mod e: font-lock -@c minor-mo de: outline -@c outline -layout: (-1 : 0) -@c outlin e-use-mode-specific-leader: "@c \." -@c outli ne-primary-bullet: "{" -@c outli ne-stylish-prefixes: nil -@c outli ne-override-protect: t -@c End: -