-
-@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
@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}
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::
+* 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
@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
\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
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{'}
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
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
+@code{\rest} appended, e.g. Rest collisions will leave these rests alone.
+
+@lilypond[singleline,verbatim]
+a'4\rest d'4\rest
+@end lilypond
@c . {Skips}
@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 _
}
@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}
@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
}
@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
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 { <f,4. c'' d e f> }
+@end lilypond
@node Ties
@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' <c' e' g'> ~ <c' e' g'>
@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
<c' e' g'> ~ <c' e' g'>
@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.
+
+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.
-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.
+@refbugs
+Not all durations (especially those containing tuplets) can be
+represented exactly; the engraver will not insert tuplets.
@node Tuplets
@subsection Tuplets
@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.
+See also @seeinternals{TupletBracket}.
-@cindex @code{\pitchnames}
-@cindex @code{\chordmodifiers}
-@example
- \pitchnames @var{scheme-alist}
- \chordmodifiers @var{scheme-alist}
-@end example
-
-See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
-specific examples 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
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
-@node Staff notation
-@section Staff notation
+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.
-@cindex Staff notation
+@node Graphical interfaces
+@subsection Graphical interfaces
-@menu
-* Key signature::
-* Clef::
-* Time signature::
-* Unmetered music::
-* Bar lines::
-@end menu
+@cindex GUI
+@cindex graphical interface
+@cindex sequencer
+@cindex RoseGarden
+@cindex Denemo
+@cindex NoteEdit
+@cindex MIDI
-@c . {Key}
-@node Key signature
-@subsection Key signature
-@cindex Key
+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:
-@cindex @code{\key}
+@itemize @bullet
+@item
+Denemo was once intended as
+a LilyPond graphical user interface. It run on Gnome/GTK.
-Setting or changing the key signature is done with the @code{\key}
-command.
-@example
- @code{\key} @var{pitch} @var{type}
-@end example
+@quotation
+@uref{http://denemo.sourceforge.net/}
+@end quotation
-@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}
+@item
+ Noteedit, a graphical score editor that runs under KDE/Qt.
+@quotation
+@uref{http://rnvs.informatik.tu-chemnitz.de/~jan/noteedit/noteedit.html,}
+@end quotation
-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.
+@item
+RoseGarden was once the inspiration for naming LilyPond. Nowadays it
+has been rewritten from scratch and supports LilyPond export as of
+version 0.1.6.
-This command sets the context property @code{Staff.keySignature}.
-Non-standard key signatures can be specified by setting this property
-directly.
+@quotation
+@uref{http://rosegarden.sf.net/}
+@end quotation
+@end itemize
-The printed signature is a @internalsref{KeySignature} grob, typically
-created in @internalsref{Staff} context.
+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{keySignature}
-@c . {Clef}
-@node Clef
-@subsection Clef
-@cindex @code{\clef}
+@c . {Relative}
+@node Relative octaves
+@subsection Relative octaves
+@cindex Relative
+@cindex relative octave specification
-The clef can be set or changed with the @code{\clef} 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
- \clef @var{clefname}
+ \relative @var{startpitch} @var{musicexpr}
@end example
-Shortcut for
+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})
-@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
+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
-Any change in these properties creates a clef (A @internalsref{Clef} grob).
+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
-Supported clef-names include
+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 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
+@lilypond[fragment,verbatim,center]
+ \relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+ }
+@end lilypond
+@cindex @code{\notes}
-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
+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).
-Supported associated glyphs (for @code{Staff.clefGlyph}) are:
+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}.
-@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.''
+@c . {Bar check}
+@node Bar check
+@subsection Bar check
+@cindex Bar check
-@cindex Vaticana, Editio
-@cindex Medicaea, Editio
-@cindex hufnagel clefs
+@cindex bar check
+@cindex @code{barCheckSynchronize}
+@cindex @code{|}
-@c . {Time signature}
-@node Time signature
-@subsection Time signature
-@cindex Time signature
-@cindex meter
-@cindex @code{\time}
+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.
-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
+A bar check is entered using the bar symbol, @code{|}:
@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})
+ \time 3/4 c2 e4 | g2.
@end example
-These properties @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
-fraction to be printed. This grob is @internalsref{TimeSignature}.
-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
+@cindex skipTypesetting
-There are many more options for the layout of this grob. They are
-selected through the @code{style} grob property.
+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 FIXME: this isn't documented except in example?
-See
-@file{input/test/time.ly} for examples.
+@c . {Point and click}
+@node Point and click
+@subsection Point and click
+@cindex poind and click
-@c . {Partial}
-@subsection Partial
-@cindex Partial
-@cindex anacrusis
-@cindex upbeat
-@cindex partial measure
-@cindex measure, partial
-@cindex shorten measures
-@cindex @code{\partial}
+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.
-Partial measures, for example in upbeats, are entered using the
-@code{\partial} command:
-@example
- \partial @var{duration}
-@end example
+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}.
-Internally, this is a shortcut for
+ 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. Enable option @emph{Inverse search} in the menu @emph{Settings}.
-@example
- \property Score.measurePosition = -@var{length of duration}
-@end example
-@cindex @code{|}
+@cindex Xdvi
+@cindex KDVI
+@cindex KDE
-The property @code{measurePosition} contains a rational number
-indicating how much of the measure has passed at this point.
-@node Unmetered music
-@subsection Unmetered music
+@end itemize
+@item An editor with a client/server interface (or a lightweight GUI
+editor).
-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
+@cindex editor
-@lilypond[fragment,relative,singleline,verbatim]
-c'2.
-\property Score.timing = ##f
-c2
-\property Score.timing = ##t
-c4 c4 c4
-@end lilypond
+@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.
-The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
-shortcuts.
+@c move this elsewhere?
+LilyPond also comes with support files for emacs: lilypond-mode for
+emacs provides indentation, syntax coloring and handy compile
+short-cuts. If lilypond-mode is not installed on your platform, then
+refer to the installation instructions for more information
+@cindex emacs
+@cindex emacs mode
+@cindex lilypond-mode for emacs
+@cindex syntax coloring
-@c . {Bar lines}
-@node Bar lines
-@subsection Bar lines
-@cindex Bar lines
+@item XEmacs. Xemacs is very similar to emacs.
-@cindex @code{\bar}
-@cindex measure lines
-@cindex repeat bars
+@cindex XEmacs
-@example
- \bar @var{bartype}
-@end example
+@item NEdit. NEdit runs under Windows, and Unix.
+ It is available from @uref{http://www.nedit.org}.
-This is a shortcut for doing
-@example
- \property Score.whichBar = @var{bartype}
-@end example
-The following bar types are available
+@cindex NEdit
-@lilypond[fragment, relative, singleline, verbatim]
-c4
-\bar "|" c
-\bar "" c
-\bar "|:" c
-\bar "||" c
-\bar ":|" c
-\bar ".|" c
-\bar ".|." c
-\bar "|."
-@end lilypond
+@item GVim. GVim is a GUI variant of VIM, the popular VI
+clone. It is available from @uref{http://www.vim.org}.
+@cindex GVim
+@cindex Vim
-You are encouraged to use @code{\repeat} for repetitions. See
-@ref{Repeats}.
+@end itemize
+@end itemize
-@cindex Bar_line_engraver
-@cindex whichBar
-@cindex repeatCommands
-@cindex defaultBarType
+Xdvi must be configured to find the @TeX{} fonts and music
+fonts. Refer to the Xdvi documentation for more information.
-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
-@code{repeatCommands} is used to override default measure bars.
+To use point-and-click, add one of these lines to the top of your .ly
+file.
+@example
+#(set-point-and-click! 'line)
+@end example
+@cindex line-location
-@code{whichBar} can also be set directly, using @code{\property} or
-@code{\bar }. These settings take precedence over the automatic
-@code{whichBar} settings.
+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.
-@internalsref{BarLine} grobs are created by the @code{Bar_engraver}.
+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.
-@c . {Polyphony}
-@node Polyphony
-@section Polyphony
-@cindex polyphony
+@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
-Polyphonic parts, i.e. parts with more than one voice on a staff can be
-typeset with LilyPond. To use this, instantiate a separate Voice
-context for each part, and assign a stem direction to each part.
-@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' } >
-@end lilypond
+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)
+@end example
+@cindex line-colomn-location
+and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}.
-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}).
+@refbugs
-@lilypond[fragment, verbatim]
- \context Staff \notes\relative c''<
- \context Voice=one {
- \shiftOff \stemUp e4
- }
- \context Voice=two {
- \shiftOn \stemUp cis
- }
- \context Voice=three {
- \shiftOnn \stemUp ais
- }
- \context Voice=four {
- \shiftOnnn \stemUp fis
- }
- >
-@end lilypond
+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.
-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.
+@node Skipping corrected music
+@subsection Skipping corrected music
-@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 } >
+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
-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
- g'8 g'8
- \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
- g'8 g'8
- }
- \context Voice = VB { \voiceTwo [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 }
->
-@end lilypond
+@node Staff notation
+@section Staff notation
-Note head collisions (horizontal shifting of note heads) are handled by
-the @internalsref{NoteCollision} grob. @internalsref{RestCollision} handles vertical
-shifting of rests.
+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
-@refbugs
+@node Staff symbol
+@subsection Staff symbol
-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.
-@node Beaming
-@section Beaming
+@cindex adjusting staff symbol
+@cindex StaffSymbol, using \property
+@cindex staff lines, setting number of
-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 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}.
-@c . {Automatic beams}
-@subsection Automatic beams
-@cindex @code{Voice.autoBeamSettings}
-@cindex @code{(end * * * *)}
-@cindex @code{(begin * * * *)}
+@refbugs
+If you end a staff half way a piece, the staff symbol may not end
+exactly on the barline.
-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,
-or at durations specified by the properties in
-@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
-are defined in @file{scm/auto-beam.scm}.
-The value of @code{autoBeamSettings} is changed using
-@code{\override} and unset using @code{\revert}:
-@example
-\property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
-\property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
-@end example
-Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
-whether the rule applies to begin or end-points. The quantity
-@var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
-*}' designates notes of any length), @var{N}/@var{M} refers to a time
-signature (wildcards, `@code{* *}' may be entered to designate all time
-signatures).
+@c . {Key}
+@node Key signature
+@subsection Key signature
+@cindex Key
-For example, if you want automatic beams to end on every quarter note,
-you can use the following:
-@example
-\property Voice.autoBeamSettings \override
- #'(end * * * *) = #(make-moment 1 4)
-@end example
-Since the duration of a quarter note is 1/4 of a whole note, it is
-entered as @code{(make-moment 1 4)}.
+@cindex @code{\key}
-The same syntax can be used to specify beam starting points. In this
-example, automatic beams can only end on a dotted quarter note.
+Setting or changing the key signature is done with the @code{\key}
+command.
@example
-\property Voice.autoBeamSettings \override
- #'(end * * * *) = #(make-moment 3 8)
+ @code{\key} @var{pitch} @var{type}
@end example
-In 4/4 time signature, this means that automatic beams could end only on
-3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
-3/8 has passed within the measure).
-You can also restrict rules to specific time signatures. A rule that
-should only be applied in @var{N}/@var{M} time signature is formed by
-replacing the second asterisks by @var{N} and @var{M}. For example, a
-rule for 6/8 time exclusively looks like
-@example
-\property Voice.autoBeamSettings \override
- #'(begin * * 6 8) = ...
-@end example
-
-If you want a rule to apply to certain types of beams, you can use the
-first pair of asterisks. Beams are classified according to the shortest
-note they contain. For a beam ending rule that only applies to beams
-with 32nd notes (and no shorter notes), you would use @code{(end 1
-32 * *)}.
+@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}
-@c not true
-@c Automatic beams can not be put on the last note in a score.
+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.
-If a score ends while an automatic beam has not been ended and is still
-accepting notes, this last beam will not be typeset at all.
+This command sets the context property @code{Staff.keySignature}.
+Non-standard key signatures can be specified by setting this property
+directly.
-@cindex automatic beam generation
-@cindex autobeam
-@cindex @code{Voice.noAutoBeaming}
+The printed signature is a @internalsref{KeySignature} grob, typically
+created in @internalsref{Staff} context.
-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.
+@cindex @code{keySignature}
-@refbugs
+@c . {Clef}
+@node Clef
+@subsection Clef
+@cindex @code{\clef}
-It is not possible to specify beaming parameters for beams with mixed
-durations, that differ from the beaming parameters of all separate
-durations, i.e., you'll have to specify manual beams to get:
-@lilypond[fragment,singleline,relative]
- \property Voice.autoBeamSettings
- \override #'(end * * * *) = #(make-moment 3 8)
- \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
+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
-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}.
+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
-@c . {Manual beams}
-@cindex Automatic beams
-@subsection Manual beams
-@cindex beams, manual
-@cindex @code{]}
-@cindex @code{[}
+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
-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:
+The grob for this symbol is @internalsref{Clef}.
-@lilypond[fragment,relative,verbatim]
- \context Staff {
- r4 [r8 g' a r8] r8 [g | a] r8
- }
-@end lilypond
-Whenever an manual beam is busy, the automatic beamer will not produce
-anything.
-@cindex @code{stemLeftBeamCount}
+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.
-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]
- }
+@c . {Time signature}
+@node Time signature
+@subsection Time signature
+@cindex Time signature
+@cindex meter
+@cindex @code{\time}
+
+The time signature is set or changed by the @code{\time}
+command.
+@lilypond[fragment,verbatim]
+ \time 2/4 c'2 \time 3/4 c'2.
@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.
+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.
-Set @code{height} to zero, to get horizontal beams:
-@lilypond[fragment,relative,verbatim]
- \property Voice.Beam \set #'direction = #1
- \property Voice.Beam \set #'height = #0
- [a'8 e' d c]
-@end lilypond
+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.
-Here's how you'd specify a weird looking beam that instead of being
-horizontal, falls two staff spaces:
+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.
-@lilypond[fragment,relative,verbatim]
- \property Voice.Beam \set #'staff-position = #4
- \property Voice.Beam \set #'height = #-4
- [c8 c]
-@end lilypond
+@c . {Partial}
+@subsection Partial
+@cindex Partial
+@cindex anacrusis
+@cindex upbeat
+@cindex partial measure
+@cindex measure, partial
+@cindex shorten measures
+@cindex @code{\partial}
-@c TODO -> why this ref? Document?
-@cindex @code{neutral-direction}
+Partial measures, for example in upbeats, are entered using the
+@code{\partial} command:
+@lilypond[fragment,verbatim]
+\partial 4* 5/16 c'16 c4 f16 a'2. ~ a'8. a'16 | g'1
+@end lilypond
-@node Expressive marks
-@section Expressive marks
+The syntax for this command is
+@example
+ \partial @var{duration}
+@end example
+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.
-@c . {Slurs}
-@menu
-* Slurs ::
-* Phrasing slurs::
-* Breath marks::
-* Tempo::
-* Text spanners::
-@end menu
-@node Slurs
-@subsection Slurs
-@cindex slurs
+@node Unmetered music
+@subsection Unmetered music
-A slur indicates that notes are to be played bound or @emph{legato}.
-They are entered using parentheses:
+Bar lines and bar numbers are calculated automatically. For unmetered
+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,verbatim,center]
- f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
+@lilypond[fragment,relative,singleline,verbatim]
+c'2.
+\cadenzaOn
+c2
+\cadenzaOff
+c4 c4 c4
@end lilypond
+The property @code{Score.timing} can be used to switch off this
+automatic timing
-Slurs avoid crossing stems, and are generally attached to note heads.
-However, in some situations with beams, slurs may be attached to stem
-ends. If you want to override this layout you can do this through the
-grob-property @code{attachment} of @internalsref{Slur} in
-@internalsref{Voice} context It's value is a pair of symbols, specifying
-the attachment type of the left and right end points.
+@c . {Bar lines}
+@node Bar lines
+@subsection Bar lines
+@cindex Bar lines
-@lilypond[fragment,relative,verbatim]
- \property Voice.Slur \set #'direction = #1
- \property Voice.Stem \set #'length = #5.5
- g'8(g)g4
- \property Voice.Slur \set #'attachment = #'(stem . stem)
- g8(g)g4
-@end lilypond
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
-If a slur would strike through a stem or beam, the slur will be moved
-away upward or downward. If this happens, attaching the slur to the
-stems might look better:
+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
-@lilypond[fragment,relative,verbatim]
- \property Voice.Stem \set #'direction = #1
- \property Voice.Slur \set #'direction = #1
- d32( d'4 )d8..
- \property Voice.Slur \set #'attachment = #'(stem . stem)
- d,32( d'4 )d8..
+The following bar types are available
+@lilypond[fragment, relative, singleline, verbatim]
+c4
+\bar "|" c
+\bar "" c
+\bar "|:" c
+\bar "||" c
+\bar ":|" c
+\bar ".|" c
+\bar ".|." c
+\bar "|."
@end lilypond
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeats}.
-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
- 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
+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
-@refbugs
-
-@code{beautiful} is an arbitrary parameter in the slur formatter.
-Useful values can only be determined by trial and error.
+The grobs that are created at @internalsref{Staff} level. The name is
+@internalsref{BarLine}.
-@cindex Adjusting slurs
+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
+@code{repeatCommands} is used to override default measure bars.
-@node Phrasing slurs
-@subsection Phrasing slurs
+@code{whichBar} can also be set directly, using @code{\property} or
+@code{\bar }. These settings take precedence over the automatic
+@code{whichBar} settings.
-@cindex phrasing slurs
-@cindex phrasing marks
-A phrasing slur (or phrasing mark) connects chords and is used to
-indicate a musical sentence. It is started using @code{\(} and @code{\)}
-respectively.
+@cindex Bar_line_engraver
+@cindex whichBar
+@cindex repeatCommands
+@cindex defaultBarType
-@lilypond[fragment,verbatim,center,relative]
- \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.
-@node Breath marks
-@subsection Breath marks
+@c . {Polyphony}
+@node Polyphony
+@section Polyphony
+@cindex polyphony
-Breath marks are entered using @code{\breathe}. The result is a
-@internalsref{BreathingSign} grob in @internalsref{Voice} context.
+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[fragment,relative]
-c'4 \breathe d4
+@lilypond[verbatim,fragment]
+\context Voice = VA \relative c'' {
+ c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
+}
@end lilypond
+The separator causes @internalsref{Voice} contexts to be instantiated,
+bearing the names @code{"1"}, @code{"2"}, etc.
+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[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
-@refbugs
+The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
+ties, slurs and stems, and set shift directions.
- Currently, only tick marks are supported, not comma style breath marks.
+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 {
+ \shiftOff \stemUp e4
+ }
+ \context Voice=two {
+ \shiftOn \stemUp cis
+ }
+ \context Voice=three {
+ \shiftOnn \stemUp ais
+ }
+ \context Voice=four {
+ \shiftOnnn \stemUp fis
+ }
+ >
+@end lilypond
-@c . {Tempo}
-@node Tempo
-@subsection Tempo
-@cindex Tempo
-@cindex beats per minute
-@cindex metronome marking
+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 Voice < {
+ g'8 g'8
+ \property Staff.NoteCollision \override
+ #'merge-differently-dotted = ##t
+ g'8 g'8
+ } \\ { [g'8. f16] [g'8. f'16] }
+ >
+@end lilypond
-Metronome settings can be entered as follows:
+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
-@cindex @code{\tempo}
-@example
- \tempo @var{duration} = @var{perminute}
-@end example
+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}
-For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
-per minute.
-
@refbugs
-
-The tempo setting is not printed, but is only used in the MIDI
-output. You can trick lily into producing a metronome mark,
-though. Details are in @ref{Text markup}.
-
+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 @internalsref{NoteColumn} grob and pitched
+rests to override typesetting decisions.
-@node Text spanners
-@subsection Text spanners
-@cindex Text spanners
+@node Beaming
+@section Beaming
-Some textual indications, e.g. rallentando or accelerando, often extend
-over many measures. This is indicated by following the text with a
-dotted line. You can create such texts using text spanners. The syntax
-is as follows:
-@example
-\spanrequest \start "text"
-\spanrequest \stop "text"
-@end example
-LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
-in @internalsref{Voice} context). The string to be printed, as well as the
-style is set through grob properties.
+Beams are used to group short notes into chunks that are aligned with
+the metrum. They are inserted automatically in most cases.
-An application---or rather, a hack---is to fake octavation indications.
-@lilypond[fragment,relative,verbatim]
- \relative c' { a''' b c a
- \property Voice.TextSpanner \set #'type = #'dotted-line
- \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
- \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
- \property Staff.centralCPosition = #-13
- a\spanrequest \start "text" b c a \spanrequest \stop "text" }
+@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.
-@c . {Ornaments}
-@node Ornaments
-@section Ornaments
-@cindex Ornaments
-@menu
-* Articulations::
-* Text scripts::
-* Grace notes::
-* Glissando ::
-* Dynamics::
-@end menu
-
-@c . {Articulation}
-@node Articulations
-@subsection Articulations
-@cindex Articulations
+See also @internalsref{Beam}.
-@cindex articulations
-@cindex scripts
-@cindex ornaments
+@c . {Manual beams}
+@cindex Automatic beams
+@subsection Manual beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
-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.
+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[]
- \score {
- <
- \property Score.LyricSyllable \override #'font-family =#'typewriter
- \property Score.LyricSyllable \override #'font-shape = #'upright
- \context Staff \notes {
- c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
- c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
- c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
- c''-\rtoe c''-\turn c''-\open c''-\flageolet
- c''-\reverseturn c''-\trill c''-\prall c''-\mordent
- c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
- c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
- c''-\lineprall c''-\thumb c''-\segno c''-\coda
- }
- \context Lyrics \lyrics {
- accent__ marcato__ staccatissimo__ fermata
- stopped__ staccato__ tenuto__ upbow
- downbow__ lheel__ rheel__ ltoe
- rtoe__ turn__ open__ flageolet
- reverseturn__ trill__ prall__ mordent
- prallprall__ prallmordent__ uprall__ downprall
- upmordent__ downmordent__ pralldown__ prallup__
- lineprall__ thumb__ segno__ coda
- }
- >
- \paper {
- linewidth = 5.875\in
- indent = 0.0
- }
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ r4 [r8 g' a r8] r8 [g | a] r8
}
@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 @code{stemLeftBeamCount}
-@cindex fingering
+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.
-Fingering instructions can also be entered in this shorthand.
-@lilypond[verbatim, singleline, fragment]
- c'4-1 c'4-2 c'4-3 c'4-4
+@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}
-@cindex @code{\script}
-@cindex scripts
-@cindex superscript
-@cindex subscript
+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.
-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}
+[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
-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}.
+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}.
-@refbugs
+@cindex beams, kneed
+@cindex kneed beams
+@cindex auto-knee-gap
+@cindex hara kiri
-All of these note ornaments appear in the printed output but have no
-effect on the MIDI rendering of the music.
-Unfortunately, there is no support for adding fingering instructions or
-ornaments to individual note heads. Some hacks exist, though. See
-@file{input/test/script-horizontal.ly}.
+@c TODO -> why this ref? Document?
+@cindex @code{neutral-direction}
+@refbugs
-@c . {Text scripts}
-@node Text scripts
-@subsection Text scripts
-@cindex Text scripts
+Auto knee beams can not be used together with hara kiri staffs.
-In addition, it is possible to place arbitrary strings of text or markup
-text (see @ref{Text markup}) above or below notes by using a string:
-@code{c^"text"}.
+[TODO from bugs]
-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 }
-@end lilypond
+The Automatic beamer does not put @strong{unfinished} beams on the
+last notes of a score.
-Text scripts are created in form of @internalsref{TextScript} grobs, in
-@internalsref{Voice} context.
+Formatting of ties is a difficult subject. LilyPond often does not
+give optimal results.
-@ref{Text markup} describes how to change the font or access
-special symbols in text scripts.
+@menu
+* Setting automatic beam behavior ::
+@end menu
-@c . {Grace notes}
-@node Grace notes
-@subsection Grace notes
+@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}
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+@cindex @code{autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
-@cindex Grace music
-@cindex @code{\grace}
-@cindex ornaments
-@cindex grace notes
-@cindex @code{graceAlignPosition}
+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,
+or at durations specified by the properties in
+@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
+are defined in @file{scm/auto-beam.scm}.
-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.
+The value of @code{autoBeamSettings} is changed using
+@code{\override} and unset using @code{\revert}:
@example
- \grace @var{musicexpr}
+\property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
+\property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
@end example
+Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
+whether the rule applies to begin or end-points. The quantity
+@var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
+*}' designates notes of any length), @var{N}/@var{M} refers to a time
+signature (wildcards, `@code{* *}' may be entered to designate all time
+signatures).
-Unbeamed eighth notes and shorter by default have a slash through the
-stem.
-
-@lilypond[fragment,verbatim]
-\relative c'' {
- \grace c8 c4 \grace { [c16 c16] } c4
- \grace {
- \property Voice.Stem \override #'flag-style = #'()
- c16
- \property Voice.Stem \revert #'flag-style
- } c4
-}
-@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}.
-
-@refbugs
-
-Nesting @code{\grace} notes is not supported. The following may cause
-run-time errors: @example
- @code{\grace @{ \grace c32 c16 @} c4}
+For example, if you want automatic beams to end on every quarter note,
+you can use the following:
+@example
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 1 4)
@end example
-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.
-
-@menu
-* Glissando ::
-* Dynamics::
-@end menu
+Since the duration of a quarter note is 1/4 of a whole note, it is
+entered as @code{(make-moment 1 4)}.
+The same syntax can be used to specify beam starting points. In this
+example, automatic beams can only end on a dotted quarter note.
+@example
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 3 8)
+@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8 has passed within the measure).
+You can also restrict rules to specific time signatures. A rule that
+should only be applied in @var{N}/@var{M} time signature is formed by
+replacing the second asterisks by @var{N} and @var{M}. For example, a
+rule for 6/8 time exclusively looks like
+@example
+\property Voice.autoBeamSettings \override
+ #'(begin * * 6 8) = ...
+@end example
-@c . {Glissando}
-@node Glissando
-@subsection Glissando
-@cindex Glissando
+If you want a rule to apply to certain types of beams, you can use the
+first pair of asterisks. Beams are classified according to the shortest
+note they contain. For a beam ending rule that only applies to beams
+with 32nd notes (and no shorter notes), you would use @code{(end 1
+32 * *)}.
-@cindex @code{\glissando}
+@c not true
+@c Automatic beams can not be put on the last note in a score.
-A glissando line (grob @internalsref{Glissando}) can be requested by
-attaching a @code{\glissando} to a notte:
+If a score ends while an automatic beam has not been ended and is still
+accepting notes, this last beam will not be typeset at all.
+
+@cindex automatic beam generation
+@cindex autobeam
+@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}.
-@lilypond[fragment,relative,verbatim]
- c'-\glissando c'
-@end lilypond
@refbugs
-Printing of an additional text (such as @emph{gliss.}) must be done
-manually.
+It is not possible to specify beaming parameters for beams with mixed
+durations, that differ from the beaming parameters of all separate
+durations, i.e., you'll have to specify manual beams to get:
+
+@lilypond[singleline,fragment,relative,noverbatim]
+ \property Voice.autoBeamSettings
+ \override #'(end * * * *) = #(make-moment 3 8)
+ \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
+@end lilypond
+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}.
+@node Accidentals
+@section Accidentals
+@cindex Accidentals
+This section describes how to change the way that LilyPond automatically
+inserts accidentals before the running notes.
+@menu
+* Using the predefined accidental macros::
+* Defining your own accidental typesettings::
+@end menu
-@c . {Dynamics}
-@node Dynamics
-@subsection Dynamics
-@cindex Dynamics
+@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
+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
+@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
-@cindex @code{\ppp}
-@cindex @code{\pp}
-@cindex @code{\p}
-@cindex @code{\mp}
-@cindex @code{\mf}
-@cindex @code{\f}
-@cindex @code{\ff}
-@cindex @code{\fff}
-@cindex @code{\ffff}
-@cindex @code{\fp}
-@cindex @code{\sf}
-@cindex @code{\sff}
-@cindex @code{\sp}
-@cindex @code{\spp}
-@cindex @code{\sfz}
-@cindex @code{\rfz}
+@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
+@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
-Absolute dynamic marks are specified using an identifier after a
-note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
-@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
-@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
-@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
+@node Defining your own accidental typesettings
+@subsection Defining your own accidental typesettings
-@lilypond[verbatim,singleline,fragment,relative]
- c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
- c2\sf c\rfz
+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.
+
+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.
+
+@refbugs
+
+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 <c'' c'> r2 | cis'4 <c' c''> r2 | <cis' c''> r | <c'' cis'> r |
@end lilypond
-@cindex @code{\cr}
-@cindex @code{\rc}
-@cindex @code{\decr}
-@cindex @code{\rced}
-@cindex @code{\<}
-@cindex @code{\>}
-@cindex @code{\"!}
+The only solution is to manually insert the problematic
+accidentals using @code{!} and @code{?}.
+@node Expressive marks
+@section Expressive marks
-A crescendo mark is started with @code{\cr} and terminated with
-@code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
-started with @code{\decr} and terminated with @code{\rced}. There are
-also shorthands for these marks. A crescendo can be started with
-@code{\<} and a decrescendo can be started with @code{\>}. Either one
-can be terminated with @code{\!}. Note that @code{\!} must go before
-the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
-after the last note. Because these marks are bound to notes, if you
-want several marks during one note, you have to use spacer notes.
+@c . {Slurs}
+@menu
+* Slurs ::
+* Phrasing slurs::
+* Breath marks::
+* Tempo::
+* Text spanners::
+@end menu
+
+@node Slurs
+@subsection 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]
- c'' \< \! c'' d'' \decr e'' \rced
- < f''1 { s4 s4 \< \! s4 \> \! s4 } >
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
@end lilypond
-You can also use a text saying @emph{cresc.} instead of hairpins. Here
-is an example how to do it:
+See also @seeinternals{Slur}.
-@cindex crescendo
-@cindex decrescendo
+Slurs avoid crossing stems, and are generally attached to note heads.
+However, in some situations with beams, slurs may be attached to stem
+ends. If you want to override this layout you can do this through the
+grob-property @code{attachment} of @internalsref{Slur} in
+@internalsref{Voice} context It's value is a pair of symbols, specifying
+the attachment type of the left and right end points.
@lilypond[fragment,relative,verbatim]
- \context Voice {
- \property Voice.crescendoText = "cresc."
- \property Voice.crescendoSpanner = #'dashed-line
- a'2\mf\< a a \!a
- }
+ \slurUp
+ \property Voice.Stem \set #'length = #5.5
+ g'8(g)g4
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+ g8(g)g4
@end lilypond
-For everyday use, we recommend the identifiers @code{\cresc},
-@code{endcresc}, @code{\dim} and @code{\enddim}.
+If a slur would strike through a stem or beam, the slur will be moved
+away upward or downward. If this happens, attaching the slur to the
+stems might look better:
-@cindex diminuendo
+@lilypond[fragment,relative,verbatim]
+ \stemUp \slurUp
+ d32( d'4 )d8..
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+ d,32( d'4 )d8..
+@end lilypond
-Dynamics are grobs of @internalsref{DynamicText} and
-@internalsref{Hairpin}. They are put together on
-@internalsref{DynamicLineSpanner} to align them vertically.
+@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:
+
+@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
-@c . {Repeats}
-@node Repeats
-@section Repeats
+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 repeats
-@cindex @code{\repeat}
+@cindex Adjusting slurs
-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.
+@node Phrasing slurs
+@subsection Phrasing slurs
-@table @asis
-@item unfold
-Repeated music is fully written (played) out. Useful for MIDI
-output, and entering repetitive music.
+@cindex phrasing slurs
+@cindex phrasing marks
-@item volta
-This is the normal notation: Repeats are not written out, but
-alternative endings (voltas) are printed, left to right.
+A phrasing slur (or phrasing mark) connects chords and is used to
+indicate a musical sentence. It is started using @code{\(} and @code{\)}
+respectively.
-@item fold
-Alternative endings are written stacked. This has limited use but may be
-used to typeset two lines of lyrics in songs with repeats, see
-@file{input/star-spangled-banner.ly}.
+@lilypond[fragment,verbatim,center,relative]
+ \time 6/4 c' \( d () e f () e \) d
+@end lilypond
-@item tremolo
-Make tremolo beams.
+Typographically, the phrasing slur behaves almost exactly like a normal
+slur. See also @seeinternals{PhrasingSlur}.
-@item percent
-Make beat or measure repeats. These look like percent signs.
-@end table
+@node Breath marks
+@subsection Breath marks
-@menu
-* Repeat syntax::
-* Manual repeat commands::
-* Tremolo repeats::
-* Tremolo subdivisions::
-* Measure repeats::
-@end menu
+Breath marks are entered using @code{\breathe}. See also
+@seeinternals{BreathingSign}.
-@node Repeat syntax
-@subsection Repeat syntax
+@lilypond[fragment,relative]
+c'4 \breathe d4
+@end lilypond
-The syntax for repeats is
-@example
- \repeat @var{variant} @var{repeatcount} @var{repeatbody}
-@end example
+@c . {Tempo}
+@node Tempo
+@subsection Tempo
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
-If you have alternative endings, you may add
-@cindex @code{\alternative}
+Metronome settings can be entered as follows:
+
+@cindex @code{\tempo}
@example
- \alternative @code{@{} @var{alternative1}
- @var{alternative2}
- @var{alternative3} @dots{} @code{@}}
+ \tempo @var{duration} = @var{perminute}
@end example
-where each @var{alternative} is a music expression.
-Normal notation repeats are used like this:
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 { c'4 d' e' f' }
- \repeat volta 2 { f' e' d' c' }
-@end lilypond
+For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
+per minute.
+
+@refbugs
+
+The tempo setting is not printed, but is only used in the MIDI
+output. You can trick lily into producing a metronome mark,
+though. Details are in @ref{Text markup}.
+
-With alternative endings:
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
+
+@node Text spanners
+@subsection Text spanners
+@cindex Text spanners
+
+Some textual indications, e.g. rallentando or accelerando, often extend
+over many measures. This is indicated by following the text with a
+dotted line. You can create such texts using text spanners. The syntax
+is as follows:
+@example
+\spanrequest \start "text"
+\spanrequest \stop "text"
+@end example
+LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
+in @internalsref{Voice} context). The string to be printed, as well as the
+style is set through grob properties.
+
+An application---or rather, a hack---is to fake octavation indications.
+@lilypond[fragment,relative,verbatim]
+ \relative c' { a''' b c a
+ \property Voice.TextSpanner \set #'type = #'dotted-line
+ \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
+ \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
+ \property Staff.centralCPosition = #-13
+ a\spanrequest \start "text" b c a \spanrequest \stop "text" }
@end lilypond
-Folded repeats look like this:
+@c . {Ornaments}
+@node Ornaments
+@section Ornaments
+@cindex Ornaments
+@menu
+* Articulations::
+* Text scripts::
+* Grace notes::
+* Glissando ::
+* Dynamics::
+@end menu
+
+@c . {Articulation}
+@node Articulations
+@subsection Articulations
+@cindex Articulations
+
+@cindex articulations
+@cindex scripts
+@cindex ornaments
-@lilypond[fragment,verbatim]
- c'1
- \repeat fold 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
+A variety of symbols can appear above and below notes to indicate
+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
+ 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
-If you don't give enough alternatives for all of the repeats, then
-the first alternative is assumed to be repeated often enough to equal
-the specified number of repeats.
-@lilypond[fragment,verbatim]
-\context Staff {
- \relative c' {
- \partial 4
- \repeat volta 4 { e | c2 d2 | e2 f2 | }
- \alternative { { g4 g g } { a | a a a a | b2. } }
+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 portato
+@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.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''-\portato
+ c''-\upbow
+ c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
+ c''-\rtoe c''-\turn c''-\open c''-\flageolet
+ c''-\reverseturn c''-\trill c''-\prall c''-\mordent
+ c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
+ c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
+ c''-\lineprall c''-\thumb c''-\segno c''-\coda
+ }
+ \context Lyrics \lyrics {
+ accent__ marcato__ staccatissimo__ fermata
+ stopped__ staccato__ tenuto__ portato
+ upbow
+ downbow__ lheel__ rheel__ ltoe
+ rtoe__ turn__ open__ flageolet
+ reverseturn__ trill__ prall__ mordent
+ prallprall__ prallmordent__ uprall__ downprall
+ upmordent__ downmordent__ pralldown__ prallup__
+ lineprall__ thumb__ segno__ coda
+ }
+ >
+ \paper {
+ linewidth = 5.875\in
+ indent = 0.0
+ }
}
-}
@end lilypond
-@subsection Unfolding repeats for MIDI output.
-
-@cindex expanding repeats
-See @file{input/test/unfold-all-repeats.ly}.
+@cindex fingering
+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")
+@end lilypond
-@refbugs
-Notice that timing information is not remembered at the start of an
-alternative, so you have to reset timing information after a repeat,
-e.g. using a bar-check (See @ref{Bar check}), setting
-@code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
-are also not repeated.
+@cindex @code{\script}
+@cindex scripts
+@cindex superscript
+@cindex subscript
-It is possible to nest @code{\repeat}s, although this probably is only
-meaningful for unfolded repeats.
+See also @seeinternals{Script} and @seeinternals{Fingering}.
-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.
+@refbugs
-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.
+All of these note ornaments appear in the printed output but have no
+effect on the MIDI rendering of the music.
-@node Manual repeat commands
-@subsection Manual repeat commands
+Unfortunately, there is no support for adding fingering instructions or
+ornaments to individual note heads. Some hacks exist, though. See
+@file{input/test/script-horizontal.ly}.
-@cindex @code{repeatCommands}
-The property @code{repeatCommands} can be used to control the layout of
-repeats. Its value is a Scheme list of repeat commands, where each repeat
-command can be
+@c . {Text scripts}
+@node Text scripts
+@subsection Text scripts
+@cindex Text scripts
-@table @code
-@item 'start-repeat
- Print a |: bar line
-@item 'stop-repeat
- Print a :| bar line
-@item (volta . @var{text})
- Print a volta bracket saying @var{text}.
-@item (volta . #f)
- Stop a running volta bracket
-@end table
+In addition, it is possible to place arbitrary strings of text or markup
+text (see @ref{Text markup}) above or below notes by using a string:
+@code{c^"text"}.
-@lilypond[verbatim, fragment]
- c''4
- \property Score.repeatCommands = #'((volta "93") end-repeat)
- c''4 c''4
- \property Score.repeatCommands = #'((volta #f))
- c''4 c''4
+By default, these indications do not influence the note spacing, but
+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}).
-Repeats brackets are @internalsref{VoltaBracket} grobs.
+Text scripts are created in form of @internalsref{TextScript} grobs, in
+@internalsref{Voice} context.
-@node Tremolo repeats
-@subsection Tremolo repeats
-@cindex tremolo beams
+@ref{Text markup} describes how to change the font or access
+special symbols in text scripts.
-To place tremolo marks between notes, use @code{\repeat} with tremolo
-style.
-@lilypond[verbatim,center,singleline]
-\score {
- \context Voice \notes\relative c' {
- \repeat "tremolo" 8 { c16 d16 }
- \repeat "tremolo" 4 { c16 d16 }
- \repeat "tremolo" 2 { c16 d16 }
- \repeat "tremolo" 4 c16
- }
-}
-@end lilypond
-Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
-@internalsref{StemTremolo}.
+@c . {Grace notes}
+@node Grace notes
+@subsection Grace notes
-@refbugs
-At present, the spacing between tremolo beams is not regular, since the
-spacing engine does not notice that not all notes are printed.
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
-@node Tremolo subdivisions
-@subsection Tremolo subdivisions
-@cindex tremolo marks
-@cindex @code{tremoloFlags}
+Grace notes are ornaments are written out ornaments
+@lilypond[relative=2,verbatim,ifragment]
+ c4 \grace c16 c4 \grace { [c16 d16] } c4
+@end lilypond
-Tremolo marks can be printed on a single note by adding
-`@code{:}[@var{length}]' after the note. The length must be at least 8.
-A @var{length} value of 8 gives one line across the note stem. If the
-length is omitted, then then the last value (stored in
-@code{Voice.tremoloFlags}) is used.
+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:
-@lilypond[verbatim,fragment,center]
- c'2:8 c':32 | c': c': |
+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
-@refbugs
+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
+The placement of these grace notes is synchronized between different
+staffs, using this grace timing.
-Tremolos in this style do not carry over into the MIDI output.
+@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
-@node Measure repeats
-@subsection Measure repeats
+Unbeamed eighth notes and shorter by default have a slash through the
+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}.
-@cindex percent repeats
-@cindex measure repeats
-In the @code{percent} style, a note pattern can be repeated. It is
-printed once, and then the pattern is replaced with a special sign.
-Patterns of a one and two measures are replaced by percent-like signs,
-patterns that divide the measure length are replaced by slashes.
+@lilypond[fragment,verbatim]
+\relative c'' \context Voice {
+ \grace c8 c4 \grace { [c16 c16] } c4
+ \grace {
+ \property Voice.Stem \override #'flag-style = #'()
+ c16
+ \property Voice.Stem \revert #'flag-style
+ } c4
+}
+@end lilypond
-@lilypond[verbatim,singleline]
- \context Voice { \repeat "percent" 4 { c'4 }
- \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
+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
-The signs are represented by these grobs: @internalsref{RepeatSlash} and
-@internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
@refbugs
-You can not nest percent repeats, e.g. by filling in the first measure
-with slashes, and repeating that measure with percents.
+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.
-@node Rhythmic music
-@section Rhythmic music
+@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
-* Rhythmic staves::
+* Glissando ::
+* Dynamics::
@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:
-
-@lilypond[fragment,relative,verbatim]
- \context RhythmicStaff {
- \time 4/4
- c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
- }
-@end lilypond
-
-
-@c . {Piano music}
-@node Piano music
-@section Piano music
-
-Piano music is an odd type of notation. 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
-@internalsref{PianoStaff} is especially built to handle this cross-staffing
-behavior. In this section we discuss the @internalsref{PianoStaff} and some
-other pianistic peculiarities.
-
-@menu
-* Automatic staff changes::
-* Manual staff switches::
-* Pedals::
-* Arpeggio::
-* Voice follower lines::
-@end menu
-
-
-@c . {Automatic staff changes}
-@node Automatic staff changes
-@subsection Automatic staff changes
-@cindex Automatic staff changes
-
-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.
-
-@lilypond[verbatim,singleline]
-\score { \notes \context PianoStaff <
- \context Staff = "up" {
- \autochange Staff \context Voice = VA < \relative c' {
- g4 a b c d r4 a g } > }
- \context Staff = "down" {
- \clef bass
- s1*2
-} > }
-@end lilypond
-
-Note how spacer rests are used to prevent the bottom staff from
-terminating too soon.
-
-
-@node Manual staff switches
-@subsection Manual staff switches
-
-@cindex manual staff switches
-@cindex staff switch, manual
-
-Voices can be switched between staves manually, using the following command:
-@example
- \translator Staff = @var{staffname} @var{music}
-@end example
-The string @var{staffname} is the name of the staff. It switches the
-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
-@cindex Pedals
-
-Piano pedal instruction can be expressed using
-@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
-@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
-
-These identifiers are shorthands for spanner commands of the types
-@internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
-
-@lilypond[fragment,verbatim]
-c''4 \spanrequest \start "Sustain" c''4
-c''4 \spanrequest \stop "Sustain"
-@end lilypond
-
-The symbols that are printed can be modified by setting
-@code{pedal@var{X}Strings}, where @var{X} is one of the pedal
-types. Refer to the generated documentation of @rgrob{PianoPedal} for
-more information.
-
-@refbugs
-Currently, brackets are not supported, only text markings (i.e. `*Ped'
-style).
-
-
-@c . {Arpeggio}
-@node Arpeggio
-@subsection Arpeggio
-@cindex Arpeggio
-
-@cindex broken arpeggio
-@cindex @code{\arpeggio}
-
-You can specify an arpeggio sign on a chord by attaching an
-@code{\arpeggio} to a note of the chord.
-
-
-@lilypond[fragment,relative,verbatim]
- \context Voice <c\arpeggio e g c>
-@end lilypond
-
-When an arpeggio crosses staves in piano music, you attach an arpeggio
-to the chords in both staves, and set
-@code{PianoStaff.connectArpeggios}.
-
-@lilypond[fragment,relative,verbatim]
- \context PianoStaff <
- \property PianoStaff.connectArpeggios = ##t
- \context Voice = one { <c'\arpeggio e g c> }
- \context Voice = other { \clef bass <c,,\arpeggio e g>}
- >
-@end lilypond
+@c . {Glissando}
+@node Glissando
+@subsection Glissando
+@cindex Glissando
-This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
-are @code{PianoStaff.Arpeggio}. @internalsref{Arpeggio}
+@cindex @code{\glissando}
-To add an arrow head to explicitly specify the direction of the
-arpeggio, you should set the arpeggio grob property
-@code{arpeggio-type}.
+A glissando line can be requested by attaching a @code{\glissando} to
+a note:
@lilypond[fragment,relative,verbatim]
- \context Voice {
- \property Voice.Arpeggio \override #'arpeggio-direction = #1
- <c\arpeggio e g c>
- \property Voice.Arpeggio \override #'arpeggio-direction = #-1
- <c\arpeggio e g c>
- }
+ c'-\glissando c'
@end lilypond
-@ignore
-A square bracket on the left indicates that the player should not
-arpeggiate the chord.
-
-@lil ypond[fragment,relative,verbatim]
- \context PianoStaff <
- \property PianoStaff.connectArpeggios = ##t
- \property PianoStaff.Arpeggio \override #'arpeggio-direction = #'bracket
- \context Voice = one { <c'\arpeggio e g c> }
- \context Voice = other { \clef bass <c,,\arpeggio e g>}
- >
-@ e nd lilypond
-@end ignore
-
-
@refbugs
-It is not possible to mix connected arpeggios and unconnected arpeggios
-at the same time.
-
-
-
-@node Voice follower lines
-@subsection Voice follower lines
-
-@cindex follow voice
-@cindex staff switching
-@cindex cross staff
-
-@cindex @code{followVoice}
-
-Whenever a voice switches to another staff a line connecting the notes
-can be printed automatically. This is enabled if the property
-@code{PianoStaff.followVoice} is set to true:
-
-@lilypond[fragment,relative,verbatim]
- \context PianoStaff <
- \property PianoStaff.followVoice = ##t
- \context Staff \context Voice {
- c1
- \translator Staff=two
- b2 a
- }
- \context Staff=two {\clef bass \skip 1*2 }
- >
-@end lilypond
-
-The associated grob is @internalsref{VoiceFollower}.
-
-
-@node Lyrics
-@section Lyrics
-
-
-@menu
-* Lyrics mode::
-* Printing lyrics::
-* Automatic syllable durations::
-* More stanzas::
-@end menu
-
-@c . {Lyrics mode}
-@node Lyrics mode
-@subsection Lyrics mode
-@cindex Lyrics mode
-
-To print lyrics, 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}.
-
-@cindex Lyric hyphen
-
-@node Automatic syllable durations
-@subsection Automatic syllable durations
-@cindex Automatic syllable durations
-
-@cindex automatic lyric durations
-@cindex @code{\addlyrics}
+Printing of an additional text (such as @emph{gliss.}) must be done
+manually. See also @seeinternals{Glissando}.
-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}
+@c . {Dynamics}
+@node Dynamics
+@subsection Dynamics
+@cindex Dynamics
-If the property @code{automaticMelismata} is set in the
-context of @var{musicexpr1}, no lyrics will be put on slurred or tied
-notes.
-@lilypond[verbatim,fragment]
-\addlyrics
-\transpose c'' {
- \property Voice.automaticMelismata = ##t
- c8 () cis d8. e16 f2
-}
-\context Lyrics \lyrics {
- do4 re mi fa }
-@end lilypond
-If you want the lyric lines to be above the melody staff, or in some
-other, more complex configuration, then build that configuration first
-using simultaneous music, and use @code{\addlyrics} after that.
+@cindex @code{\ppp}
+@cindex @code{\pp}
+@cindex @code{\p}
+@cindex @code{\mp}
+@cindex @code{\mf}
+@cindex @code{\f}
+@cindex @code{\ff}
+@cindex @code{\fff}
+@cindex @code{\ffff}
+@cindex @code{\fp}
+@cindex @code{\sf}
+@cindex @code{\sff}
+@cindex @code{\sp}
+@cindex @code{\spp}
+@cindex @code{\sfz}
+@cindex @code{\rfz}
-@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:
+Absolute dynamic marks are specified using an identifier after a
+note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
+@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
+@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
+@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
-@lilypond[verbatim,fragment]
-\addlyrics
-\transpose c'' {
- c8 () cis d8. e16 f2
-}
-\context Lyrics \lyrics
-< { do4 re fa sol }
- { do8 re fa sol } >
+@lilypond[verbatim,singleline,fragment,relative]
+ c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
+ c2\sf c\rfz
@end lilypond
-It is valid (but probably not very useful) to use notes instead of
-lyrics for @var{musicexpr2}.
-
-@node More stanzas
-@subsection More stanzas
+@cindex @code{\cr}
+@cindex @code{\rc}
+@cindex @code{\decr}
+@cindex @code{\rced}
+@cindex @code{\<}
+@cindex @code{\>}
+@cindex @code{\"!}
-@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.
-
-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}.
-
-
-@lilypond[singleline,verbatim]
-\score {
-\addlyrics
- \notes \relative c'' \context Voice = duet { \time 3/4
- g2 e4 a2 f4 g2. }
- \lyrics \context Lyrics <
- \context LyricsVoice = "duet-1" {
- \property LyricsVoice . stanza = "Bert"
- Hi, my name is bert. }
- \context LyricsVoice = "duet-2" {
- \property LyricsVoice . stanza = "Ernie"
- Ooooo, ch\'e -- ri, je t'aime. }
- >
-}
-@end lilypond
-
-You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
-first system) and @code{LyricsVoice.stz} for the following
-systems. 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[verbatim,singleline]
-twoWays = \notes \transpose c'' {
- \chords {
- c1 f:sus4 bes/f
- }
- <c e g>
- <f bes c'>
- <f bes d'>
- }
-
-\score {
- < \context ChordNames \twoWays
- \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.
-
-@menu
-* Chords mode::
-* Printing named chords::
-@end menu
-
-@c . {Chords mode}
-@node Chords mode
-@subsection Chords mode
-@cindex Chords mode
-
-Chord mode is a mode where you can input sets of pitches using common
-names. It is introduced by the keyword @code{\chords}. It is similar
-to note mode, but words are also looked up in a chord modifier table
-(containing @code{maj}, @code{dim}, etc).
-
-Dashes and carets are used to indicate chord additions and subtractions,
-so articulation scripts can not be entered in Chord mode.
-
-The syntax for named chords is as follows:
-@example
- @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
-@end example
-
-@var{tonic} should be the tonic note of the chord, and @var{duration} is
-the chord duration in the usual notation. There are two kinds of
-modifiers. One type is 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.
-
-Throughout these examples, chords have been shifted around the staff
-using @code{\transpose}.
-
-@lilypond[fragment,verbatim]
-\transpose c'' {
- \chords {
- c1 c:3- c:7 c:8
- c:9 c:9-.5+.7+ c:3-.5-
- }
-}
-@end lilypond
-
-@cindex @code{aug}
-@cindex @code{dim}
-@cindex @code{maj}
-@cindex @code{sus}
-
-The second type of modifier that may appear after the @code{:} is a
-named modifier. Named modifiers are listed in the file
-@file{chord-modifiers.ly}. The available modifiers are @code{m} and
-@code{min} which lower the 3rd half a step, `@code{aug}' which
-raises the 5th, `@code{dim}' which lowers the 5th,
-`@code{maj}' which adds a raised 7th, and `@code{sus}'
-which replaces the 5th with a 4th.
-
-@lilypond[fragment,verbatim]
-\transpose c'' {
- \chords {
- c1:m c:min7 c:maj c:aug c:dim c:sus
- }
-}
-@end lilypond
-
-
-Chord subtractions are used to eliminate notes from a chord. The
-notes to be subtracted are listed after a @code{^} character,
-separated by dots.
-
-@lilypond[fragment,verbatim,center]
- \transpose c'' {
- \chords {
- c1^3 c:7^5.3 c:8^7
- }
- }
-@end lilypond
-@cindex @code{/}
-
-Chord inversions can be specified by appending `@code{/}' and the name
-of a single note to a chord. In a chord inversion, the inverted note is
-transposed down until it is the lowest note in the chord. If the note
-is not in the chord, a warning will be printed.
-
-@lilypond[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/e c/g c:7/e
- }
- }
-
-@end lilypond
-@cindex @code{/+}
-
-Bass notes can be added by `@code{/+}' and
-the name of a single note to a chord. This has the effect of
-adding the specified note to the chord, lowered by an octave,
-so it becomes the lowest note in the chord.
-
-@lilypond[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/+c c/+g c:7/+b
- }
- }
-
-@end lilypond
-
-@refbugs
-
-Implementation details are quite gory. For example @code{c:4} not only
-adds a fourth, but also removes the third.
-
-
-@c . {Printing named chords}
-@node Printing named chords
-@subsection Printing named chords
-
-@cindex printing chord names
-@cindex chord names
-@cindex chords
-
-For displaying printed chord names, use the @internalsref{ChordNames} context.
-The chords may be entered either using the notation described above, or
-directly using simultaneous music.
-
-@lilypond[verbatim,singleline]
-scheme = \notes {
- \chords {a1 b c} <d f g> <e g b>
-}
-\score {
- \notes<
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
-}
-@end lilypond
-
-You can make the chord changes stand out by setting
-@code{ChordNames.chordChanges} to true. This will only display chord
-names when there's a change in the chords scheme and at the start of a
-new line.
-
-@lilypond[verbatim]
-scheme = \chords {
- c1:m c:m \break c:m c:m d
-}
-\score {
- \notes <
- \context ChordNames {
- \property ChordNames.chordChanges = ##t
- \scheme }
- \context Staff \transpose c'' \scheme
- > }
-@end lilypond
-
-LilyPond examines chords specified as lists of notes to determine a name
-to give the chord. LilyPond will not try to identify chord inversions or
-an added bass note, which may result in strange chord names when chords
-are entered as a list of pitches:
-
-@lilypond[verbatim,center,singleline]
-scheme = \notes {
- <c'1 e' g'>
- <e' g' c''>
- <e e' g' c''>
-}
-
-\score {
- <
- \context ChordNames \scheme
- \context Staff \scheme
- >
-}
-@end lilypond
-
-
-By default, a chord name system proposed by Harald Banter (See
-@ref{Literature}) is used. The system is very regular and predictable.
-Typical American style chord names may be selected by setting the
-@code{style} property of the @code{ChordNames.ChordName} grob to
-@code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
-
-Routines that determine the names to be printed are written in Scheme,
-and may be customized by the user. The code can be found in
-@file{scm/chord-name.scm}. Here's an example showing the differences in
-chord name styles:
-
-@c too long?
-@c maybe just junk verbatim option?
-@lilypond[verbatim,singleline]
-scheme = \chords {
- c1 c:5^3 c:4^3 c:5+
- c:m7+ c:m5-.7
- c:5-.7 c:5+.7
- c:9^7
-}
-
-\score {
- \notes <
- \context ChordNames = banter \scheme
- \context ChordNames = american {
- \property ChordNames.ChordName \override
- #'style = #'american \scheme }
- \context ChordNames = jazz {
- \property ChordNames.ChordName \override
- #'style = #'jazz \scheme }
- \context Staff \transpose c'' \scheme
- >
-}
-@end lilypond
-
-
-@node Writing parts
-@section Writing parts
-
-Orchestral music involves some special notation, both in the full score,
-as in the individual parts. This section explains how to tackle common
-problems in orchestral music.
-
-
-@c . {Transpose}
-@menu
-* Rehearsal marks::
-* Bar numbers::
-* Instrument names::
-* Transpose::
-* Sound output for transposing instruments::
-* Multi measure rests::
-* Automatic part combining::
-* Hara kiri staves::
-@end menu
-
-@c . {Rehearsal marks}
-@node Rehearsal marks
-@subsection Rehearsal marks
-@cindex Rehearsal marks
-@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.
-
-@lilypond[fragment,verbatim]
-\relative c'' {
- c1 \mark "A2"
- c1 \mark \default
- c1 \mark \default
- c1 \mark "12"
- c1 \mark #'(music "scripts-segno")
- 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.
-
-@node Bar numbers
-@subsection Bar numbers
-
-
-@cindex bar numbers
-@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.
-@example
- \property Score.currentBarNumber = #217
-@end example
-
-If you want boxed bar numbers, see the example file
-@code{input/test/boxed-molecule.ly}.
-
-@refbugs
-
-It is not possible to have bar numbers printed at regular intervals
-only.
-
-@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.
-
-@lilypond[verbatim,singleline]
- \property Staff.instrument = "ploink " { c''4 }
-@end lilypond
-
-You can also use markup texts to construct more complicated instrument
-names:
-
-
-@lilypond[verbatim,singleline]
-#(define text-flat
- '((font-relative-size . -2 ) (music "accidentals--1")))
-
-\score { \notes {
- \property Staff.instrument = #`((kern . 0.5) (lines
- "2 Clarinetti" (columns " (B" ,text-flat ")")))
- c'' 4 }
-}
-@end lilypond
-
-
-@refbugs
-
-When you put a name on a grand staff or piano staff the width of the
-brace is not taken into account. You must add extra spaces to the end of
-the name to avoid a collision.
-
-@node Transpose
-@subsection Transpose
-@cindex Transpose
-@cindex transposition of pitches
-@cindex @code{\transpose}
-
-A music expression can be transposed with @code{\transpose}. The syntax
-is
-@example
- \transpose @var{pitch} @var{musicexpr}
-@end example
-
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
-
-@code{\transpose} distinguishes between enharmonic pitches: both
-@code{\transpose cis'} or @code{\transpose des'} will transpose up half
-a tone. The first version will print sharps and the second version
-will print flats.
-
-@lilypond[fragment,verbatim]
-\context Staff {
- \clef "F"
- { \key e \major c d e f }
- \clef "G"
- \transpose des'' { \key e \major c d e f }
- \transpose cis'' { \key e \major c d e f }
-}
-@end lilypond
-
-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
-@cindex Multi measure rests
-
-@cindex @code{R}
-
-Multi measure rests are entered using `@code{R}'. It is specifically
-meant for full bar rests and for entering parts: the rest can expand to
-fill a score with
-rests, or it can be printed as a single multimeasure rest This expansion
-is controlled by the property @code{Score.skipBars}. If this is set to true,
-Lily will not expand empty measures, and the appropriate number is added
-automatically.
-
-@lilypond[fragment,verbatim]
- \time 3/4 r2. | 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
-measure.
-
-@cindex whole rests for a full measure
-
-The grob for this object is @internalsref{MultiMeasureRest}.
-
-@refbugs
-
-Currently, there is no way to automatically condense multiple rests into
-a single multimeasure rest.
-
-@cindex condensing rests
-
-@node Automatic part combining
-@subsection Automatic part combining
-@cindex automatic part combining
-@cindex part combiner
-
-
-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.
-
-The syntax for part combining is
-
-@example
- \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
-@end example
-where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
-combined into one context of type @var{context}. The music expressions
-must be interpreted by contexts whose names should start with @code{one}
-and @code{two}.
-
-The most useful function of the part combiner is to combine parts into
-one voice, as common for wind parts in orchestral scores:
-
-@lilypond[verbatim,singleline,fragment]
- \context Staff <
- \context Voice=one \partcombine Voice
- \context Thread=one \relative c'' {
- g a () b r
- }
- \context Thread=two \relative c'' {
- g r4 r f
- }
- >
-@end lilypond
-
-Notice that the first @code{g} appears only once, although it was
-specified twice (once in each part). Stem, slur and tie directions are
-set automatically, depending whether there is a solo or unisono. The
-first part (with context called @code{one}) always gets up stems, and
-`solo', while the second (called @code{two}) always gets down stems and
-`Solo II'.
-
-If you just want the merging parts, and not the textual markings, you
-may set the property @var{soloADue} to false.
-
-@lilypond[verbatim,singleline,fragment]
- \context Staff <
- \property Staff.soloADue = ##f
- \context Voice=one \partcombine Voice
- \context Thread=one \relative c'' {
- b4 a c g
- }
- \context Thread=two \relative c'' {
- d,2 a4 g'
- }
- >
-@end lilypond
-
-There are a number of other properties that you can use to tweak the
-behavior of part combining, refer to the automatically generated
-documentation of @reng{Thread_devnull_engraver} and
-@reng{Voice_devnull_engraver}. Look at the documentation of the
-responsible engravers, @code{Thread_devnull_engraver},
-@code{Voice_devnull_engraver} and @code{A2_engraver}.
-
-@refbugs
-
-In @code{soloADue} mode, when the two voices play the same notes on and
-off, the part combiner may typeset @code{a2} more than once in a
-measure.
-
-@lilypond[fragment,singleline]
- \context Staff <
- \context Voice=one \partcombine Voice
- \context Thread=one \relative c'' {
- c b c b c a c a
- }
- \context Thread=two \relative c'' {
- b b b b f a f a
- }
- >
-@end lilypond
-
-@cindex @code{Thread_devnull_engraver}
-@cindex @code{Voice_engraver}
-@cindex @code{A2_engraver}
-
-@node Hara kiri staves
-@subsection Hara kiri staves
-
-In orchestral scores, staff lines that only have rests are usually removed.
-This saves some space. LilyPond also supports this through the hara
-kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
-the Japanese Samourai warriors.} staff. This staff commits suicide when
-it finds itself to be empty after the line-breaking process. It will
-not disappear when it contains normal rests, you must use multi measure
-rests.
-
-The hara kiri staff is specialized version of the @internalsref{Staff}
-context. It is available as the context identifier
-@code{\HaraKiriStaffContext}. Observe how the second staff in this
-example disappears in the second line.
-
-@lilypond[verbatim]
-\score {
- \notes \relative c' <
- \context Staff = SA { e4 f g a \break c1 }
- \context Staff = SB { c4 d e f \break R1 }
- >
- \paper {
- linewidth = 6.\cm
- \translator { \HaraKiriStaffContext }
- }
-}
-@end lilypond
-
-
-
-@c . {Custodes}
-@node Custodes
-@section Custodes
-@cindex Custos
-@cindex Custodes
-
-A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
-staff context symbol that appears at the end of a staff line. It
-anticipates the pitch of the first note(s) of the following line and
-thus helps the player or singer to manage line breaks during
-performance, thus enhancing readability of a score.
-
-@lilypond[verbatim]
-\score {
- \notes { c'1 \break
- \property Staff.Custos \set #'style = #'mensural
- d' }
- \paper {
- \translator {
- \StaffContext
- \consists Custos_engraver
- }
- }
-}
-@end lilypond
-
-Custodes were frequently used in music notation until the 17th century.
-There were different appearances for different notation styles.
-Nowadays, they have survived only in special forms of musical notation
-such as via the @emph{editio vaticana} dating back to the beginning of
-the 20th century.
-
-For typesetting custodes, just put a @code{Custos_engraver} into the
-@internalsref{Staff} context when declaring the @code{\paper} block. In this
-block, you can also globally control the appearance of the custos symbol
-by setting the custos @code{style} property. Currently supported styles
-are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
-@code{mensural}.
-
-@example
-\paper @{
- \translator @{
- \StaffContext
- \consists Custos_engraver
- Custos \override #'style = #'mensural
- @}
-@}
-@end example
-
-The property can also be set locally, for example in a @code{\notes}
-block:
-
-@example
-\notes @{
- \property Staff.Custos \override #'style = #'vaticana
- c'1 d' e' d' \break c' d' e' d'
-@}
-@end example
-
-@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
-@subsection Tuning groups of grobs
-
-@cindex grob description
-
-
-
-A grob definition is a Scheme association list, that is stored in a
-context property. By assigning to that property (using plain
-@code{\property}), you can change the resulting grobs.
-
-@lilypond[verbatim, fragment]
-c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
-@end lilypond
-
-The @code{\property} assignment effectively empties the definition of
-the Stem object. One of the effects is that the recipe of how it should be
-printed is erased, with the effect of rendering it invisible. The above
-assignment is available as a standard identifier, for the case that you
-find this useful:
-
-@example
- \property Voice.Stem = \turnOff
-@end example
-
-@cindex \override
-@cindex \revert
-@cindex \set
-
-This mechanism is fairly crude, since you can only set, but not modify,
-the definition of a grob. For this reason, there is a more advanced
-mechanism.
-
-The definition of a grob is actually a list of default grob
-properties. For example, the definition of the Stem grob (available in
-@file{scm/grob-description.scm}), defines the following values for
-@internalsref{Stem}
-
-@example
- (thickness . 0.8)
- (beamed-lengths . (0.0 2.5 2.0 1.5))
- (Y-extent-callback . ,Stem::height)
- @var{...}
-@end example
-
-You can add a property on top of the existing definition, or remove a
-property, thus overriding the system defaults:
-@lilypond[verbatim]
-c'4 \property Voice.Stem \override #'thickness = #4.0
-c'4 \property Voice.Stem \revert #'thickness
-c'4
-@end lilypond
-You should balance @code{\override} and @code{\revert}. If that's too
-much work, you can use the @code{\set} shorthand. It performs a revert
-followed by an override. The following example gives exactly the same
-result as the previous one.
-@lilypond[verbatim]
-c'4 \property Voice.Stem \set #'thickness = #4.0
-c'4 \property Voice.Stem \set #'thickness = #0.8
-c'4
-@end lilypond
-If you use @code{\set}, you must explicitly restore the default.
-
-
-Formally the syntax for these constructions is
-@example
-\property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
-\property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
-\property @var{context}.@var{grobname} \revert @var{symbol}
-@end example
-Here @var{symbol} is a Scheme expression of symbol type, @var{context}
-and @var{grobname} are strings and @var{value} is a Scheme expression.
-
-
-If you revert a setting which was not set in the first place, then it
-has no effect. However, if the setting was set as a system default, it
-may remove the default value, and this may give surprising results,
-including crashes. In other words, @code{\override} and @code{\revert},
-must be carefully balanced.
-
-These are examples of correct nesting of @code{\override}, @code{\set},
-@code{\revert}.
-
-A clumsy but correct form:
-@example
- \override \revert \override \revert \override \revert
-@end example
-
-Shorter version of the same:
-@example
- \override \set \set \revert
-@end example
-
-A short form, using only @code{\set}. This requires you to know the
-default value:
-@example
- \set \set \set \set @var{to default value}
-@end example
-
-If there is no default (i.e. by default, the grob property is unset),
-then you can use
-@example
- \set \set \set \revert
-@end example
-
-For the digirati, the grob description is an Scheme association
-list. Since a Scheme list is a singly linked list, we can treat it as a
-stack, and @code{\override} and @code{\revert} are just push and pop
-operations. This pushing and popping is also used for overriding
-automatic beaming settings.
-
-@refbugs
-
-LilyPond will hang or crash if @var{value} contains cyclic references.
-The backend is not very strict in type-checking grob properties. If you
-@code{\revert} properties that are expected to be set by default,
-LilyPond may crash.
-
-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}.
-
-
-
-
-@node Tuning per grob
-@subsection Tuning per grob
-
-@cindex \outputproperty
-
-A second way of tuning grobs is the more arcane @code{\outputproperty}
-feature. The syntax is as follows:
-@example
-\outputproperty @var{predicate} @var{symbol} = @var{value}
-@end example
-Here @code{predicate} is a Scheme function taking a grob argument, and
-returning a boolean. This statement is processed by the
-@code{Output_property_engraver}. It instructs the engraver to feed all
-grobs that it sees to @var{predicate}. Whenever the predicate returns
-true, the grob property @var{symbol} will be set to @var{value}.
-
-You will need to combine this statement with @code{\context} to select
-the appropriate context to apply this to.
-
-Here are some random examples.
+A crescendo mark is started with @code{\cr} and terminated with
+@code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
+started with @code{\decr} and terminated with @code{\rced}. There are
+also shorthands for these marks. A crescendo can be started with
+@code{\<} and a decrescendo can be started with @code{\>}. Either one
+can be terminated with @code{\!}. Note that @code{\!} must go before
+the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
+after the last note. Because these marks are bound to notes, if you
+want several marks during one note, you have to use spacer notes.
+@lilypond[fragment,verbatim,center]
+ c'' \< \! c'' d'' \decr e'' \rced
+ < f''1 { s4 s4 \< \! s4 \> \! s4 } >
+@end lilypond
-In the following example, all note heads occurring at current staff
-level, are shifted up and right by setting their @code{extra-offset}
-property.
+You can also use a text saying @emph{cresc.} instead of hairpins. Here
+is an example how to do it:
-@lilypond[fragment,verbatim,singleline]
-\relative c'' { c4
- \context Staff \outputproperty
- #(make-type-checker 'note-head-interface)
- #'extra-offset = #'(0.5 . 0.75)
- <c8 e g> }
+@lilypond[fragment,relative=2,verbatim]
+ c4 \cresc c4 \endcresc c4
@end lilypond
-@cindex @code{extra-offset}
-In this example, the predicate checks the @code{text} grob property, to
-shift only the `m.d.' text, but not the fingering instruction "2".
-@lilypond[verbatim,singleline]
-#(define (make-text-checker text)
- (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
+@cindex crescendo
+@cindex decrescendo
-\score {
- \notes\relative c''' {
- \property Voice.Stem \set #'direction = #1
- \outputproperty #(make-text-checker "m.d.")
- #'extra-offset = #'(-3.5 . -4.5)
- a^2^"m.d."
+You can also supply your own texts:
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.crescendoText = "cresc. poco"
+ \property Voice.crescendoSpanner = #'dashed-line
+ a'2\mf\< a a \!a
}
-}
@end lilypond
-@refbugs
+@cindex diminuendo
-If possible, avoid this feature: the semantics are not very clean, and
-the syntax and semantics are up for rewrite.
+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.
+@cindex direction, of dynamics
+@cindex @code{\dynamicDown}
+@cindex @code{\dynamicUp}
+@c . {Repeats}
+@node Repeats
+@section Repeats
-@node What to tune?
-@subsection What to tune?
+@cindex repeats
+@cindex @code{\repeat}
-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.).
+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.
-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.
+@table @code
+@item unfold
+Repeated music is fully written (played) out. Useful for MIDI
+output, and entering repetitive music.
-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
+@item volta
+This is the normal notation: Repeats are not written out, but
+alternative endings (voltas) are printed, left to right.
-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.
+@item fold
+Alternative endings are written stacked. This has limited use but may be
+used to typeset two lines of lyrics in songs with repeats, see
+@file{input/star-spangled-banner.ly}.
-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.
+@item tremolo
+Make tremolo beams.
+@item percent
+Make beat or measure repeats. These look like percent signs.
-@node Font selection
-@subsection Font selection
+@end table
-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.
+@menu
+* Repeat syntax::
+* Repeats and MIDI::
+* Manual repeat commands::
+* Tremolo repeats::
+* Tremolo subdivisions::
+* Measure repeats::
+@end menu
-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:
+@node Repeat syntax
+@subsection Repeat syntax
-@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}
+The syntax for repeats is
-@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},
- @code{caps} and @code{upright}
+@example
+ \repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
-@item font-series
-A symbol indicating the series of the font. There are typically several
-font series for each font family and shape. Choices are @code{medium}
-and @code{bold}.
+If you have alternative endings, you may add
+@cindex @code{\alternative}
+@example
+ \alternative @code{@{} @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @code{@}}
+@end example
+where each @var{alternative} is a music expression.
-@item font-relative-size
- A number indicating the size relative the standard size. For example,
- with 20pt staff height, relative size -1 corresponds to 16pt staff
- height, and relative size +1 corresponds to 23 pt staff height.
+Normal notation repeats are used like this:
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 { c'4 d' e' f' }
+ \repeat volta 2 { f' e' d' c' }
+@end lilypond
-@item font-design-size
-A number indicating the design size of the font.
+With alternative endings:
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
+@end lilypond
-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''.
+Folded repeats look like this:
-@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.
-@end table
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat fold 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
-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.
+@end lilypond
-@example
- \property Lyrics.LyricText \override #'font-series = #'bold
- \property Lyrics.LyricText \override #'font-shape = #'*
-@end example
+If you don't give enough alternatives for all of the repeats, then
+the first alternative is assumed to be repeated often enough to equal
+the specified number of repeats.
-@cindex @code{font-style}
+@lilypond[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \partial 4
+ \repeat volta 4 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b2. } }
+ }
+}
+@end lilypond
+
+@node Repeats and MIDI
+@subsection Repeats and MIDI
+
+@cindex expanding repeats
-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}.
+For instructions on how to unfoldi repeats for MIDI output, see
+the example file @file{input/test/unfold-all-repeats.ly}.
-The style sheets and tables for selecting fonts are located in
-@file{scm/font.scm}. Refer to this file for more information.
@refbugs
-Relative size is not linked to any real size.
+Notice that timing information is not remembered at the start of an
+alternative, so you have to reset timing information after a repeat,
+e.g. using a bar-check (See @ref{Bar check}), setting
+@code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
+are also not repeated.
-There is no mechanism to select magnification of particular fonts,
-meaning that you don't have access to continuously scaled fonts. You
-can scale the entire output, of course, see @ref{Output scaling}.
+It is possible to nest @code{\repeat}s, although this probably is only
+meaningful for unfolded repeats.
-There is no style sheet provided for other fonts besides the @TeX{}
-family.
+Folded repeats offer little more over simultaneous music.
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
+@node Manual repeat commands
+@subsection Manual repeat commands
+@cindex @code{repeatCommands}
-@node Text markup
-@subsection Text markup
-@cindex text markup
-@cindex markup text
+The property @code{repeatCommands} can be used to control the layout of
+repeats. Its value is a Scheme list of repeat commands, where each repeat
+command can be
-LilyPond has an internal mechanism to typeset texts. You can
-form text markup expressions by composing scheme expressions
-in the following way.
+@table @code
+@item 'start-repeat
+ Print a |: bar line
+@item 'end-repeat
+ Print a :| bar line
+@item (volta . @var{text})
+ Print a volta bracket saying @var{text}.
+@item (volta . #f)
+ Stop a running volta bracket
+@end table
-@lilypond[verbatim, singleline]
- \relative c' {
- \fatText
- a^#"upright"
- b_#'(bold "bold")
- c^#'(italic "italic")
- d_#'((bold italic) "ff")
- e^#'(dynamic "ff")
- f_#'(lines "one" (bold "two"))
- g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
+@lilypond[verbatim, fragment]
+ c''4
+ \property Score.repeatCommands = #'((volta "93") end-repeat)
+ c''4 c''4
+ \property Score.repeatCommands = #'((volta #f))
+ c''4 c''4
+@end lilypond
+
+
+Repeats brackets are @internalsref{VoltaBracket} grobs.
+
+@node Tremolo repeats
+@subsection Tremolo repeats
+@cindex tremolo beams
+
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
+@lilypond[verbatim,center,singleline]
+\score {
+ \context Voice \notes\relative c' {
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+ \repeat "tremolo" 2 { c16 d16 }
+ \repeat "tremolo" 4 c16
}
+}
@end lilypond
-Normally, the Scheme markup text is stored in the @code{text} property
-of a grob. Formally, it is defined as follows:
+Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
+@internalsref{StemTremolo}. The single stem tremolo @emph{must} be
+entered without @code{@{} and @code{@}}.
-@example
-text: string | (head? text+)
-head: markup | (markup+)
-markup-item: property | abbrev
-property: (@var{key} . @var{value})
-abbrev: @code{columns lines roman music bold italic named super sub}
- @code{overstrike text finger volta timesig mmrest mark script}
- @code{large Large dynamic}
-@end example
+@refbugs
-The markup is broken down and converted into a list of grob properties,
-which are prepended to the property list. The @var{key}-@var{value}
-pair is a grob property. A list of properties available is included in
-the generated documentation for @rint{Text_interface}.
+Only powers of two and undotted notes are supported repeat counts.
+
+@node Tremolo subdivisions
+@subsection Tremolo subdivisions
+@cindex tremolo marks
+@cindex @code{tremoloFlags}
+
+Tremolo marks can be printed on a single note by adding
+`@code{:}[@var{length}]' after the note. The length must be at least 8.
+A @var{length} value of 8 gives one line across the note stem. If the
+length is omitted, then then the last value (stored in
+@code{Voice.tremoloFlags}) is used.
+
+@lilypond[verbatim,fragment,center]
+ c'2:8 c':32 | c': c': |
+@end lilypond
-The following abbreviations are currently defined:
-@table @code
-@item columns
- horizontal mode: set all text on one line (default)
-@item lines
- vertical mode: set every text on a new line
-@item roman
- select roman font
-@item music
- selects the Feta font (the standard font for music notation glyphs),
-and uses named lookup
+@refbugs
-@item bold
- select bold series
-@item italic
- select italic shape
-@item named
- lookup by character name
-@item text
- plain text lookup (by character value)
-@item super
- superscript
-@item sub
- subscript
-@item overstrike
- the next text or character overstrikes this one
-@item finger
- select fingering number fontstyle
-@item volta
- select volta number fontstyle
-@item timesig
- select time signature number fontstyle
-@item mmrest
- select multi measure rest number fontstyle
-@item mark
- select mark number fontstyle
-@item script
- select scriptsize roman fontstyle
-@item large
- select large roman fontstyle
-@item Large
- select Large roman fontstyle
-@item dynamic
- select dynamics fontstyle
-@end table
+Tremolos in this style do not carry over into the MIDI output.
-@cindex metronome mark
-One practical application of complicated markup is to fake a metronome
-marking:
+@node Measure repeats
+@subsection Measure repeats
-@lilypond[verbatim]
-#(define note '(columns
- (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
-#(define eight-note `(columns ,note ((kern . -0.1)
- (music ((raise . 3.5) "flags-u3")))))
-#(define dotted-eight-note
- `(columns ,eight-note (music "dots-dot")))
+@cindex percent repeats
+@cindex measure repeats
-\score {
- \notes\relative c'' {
- a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
- }
- \paper {
- linewidth = -1.
- \translator{
- \ScoreContext
- TextScript \override #'font-shape = #'upright
- }
- }
+In the @code{percent} style, a note pattern can be repeated. It is
+printed once, and then the pattern is replaced with a special sign.
+Patterns of a one and two measures are replaced by percent-like signs,
+patterns that divide the measure length are replaced by slashes.
+
+@lilypond[verbatim,singleline]
+ \context Voice { \repeat "percent" 4 { c'4 }
+ \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
}
-@end lilypond
+@end lilypond
-@node Invisible grobs
-@subsection Invisible grobs
-@cindex invisible grobs
+The signs are represented by these grobs: @internalsref{RepeatSlash} and
+@internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
-@ignore
+@refbugs
-ben nog steeds niet kapot van de informatiedichtheid hier.
+You can not nest percent repeats, e.g. by filling in the first measure
+with slashes, and repeating that measure with percents.
---hwn
+@node Rhythmic music
+@section Rhythmic music
-@end ignore
+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:
-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.
+@lilypond[fragment,relative,verbatim]
+ \context RhythmicStaff {
+ \time 4/4
+ c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
+ }
+@end lilypond
-Grobs can be made invisible in a number of ways:
+@menu
+* Percussion staves::
+@end menu
-Here's an example with blanked-out notes and stems:
+@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]
-blanknotes = {
- \property Voice.NoteHead \override
- #'transparent = ##t
- \property Voice.Stem \override
- #'transparent = ##t }
-
-unblanknotes = {
- \property Voice.NoteHead \revert #'transparent
- \property Voice.Stem \revert #'transparent }
+\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 {
- \notes\relative c'' {
- \time 6/4
- a b c b \blanknotes c \unblanknotes d
- }
+ <
+ \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
-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]
+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 {
- \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}
+ <
+ \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
-
-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
- } }
+@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
-@node Dirty tricks
-@subsection Dirty tricks
-@cindex embedded tex
-
-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}).
+If you don't like any of the predefined lists you can define your own
+list at the top of your file:
-@lilypond[fragment,relative,verbatim]
- a'^"3 $\\times$ \\`a deux"
+@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
-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.
+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:
-@lilypond[verbatim]
+@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 {
- \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 }
+ <
+ \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:
-@c . {Page layout}
-@node Page layout
-@section Page layout
-@cindex Page layout
+@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.
-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.
+@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
+@internalsref{PianoStaff} is especially built to handle this cross-staffing
+behavior. In this section we discuss the @internalsref{PianoStaff} and some
+other pianistic peculiarities.
@menu
-* Paper block::
-* Paper variables::
-* Font Size::
-* Paper size::
-* Line break::
-* Page break::
-* Output scaling::
-@end menu
+* Automatic staff changes::
+* Manual staff switches::
+* Pedals::
+* Arpeggio::
+* Voice follower lines::
+@end menu
+
+
+@c . {Automatic staff changes}
+@node Automatic staff changes
+@subsection Automatic staff changes
+@cindex Automatic staff changes
+
+Voices can switch automatically between the top and the bottom
+staff. The syntax for this is
+@example
+ \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 <
+ \context Staff = "up" {
+ \autochange Staff \context Voice = VA < \relative c' {
+ g4 a b c d r4 a g } > }
+ \context Staff = "down" {
+ \clef bass
+ s1*2
+} > }
+@end lilypond
+Spacer rests are used to prevent the bottom staff from
+terminating too soon.
-@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
+@node Manual staff switches
+@subsection Manual staff switches
+
+@cindex manual staff switches
+@cindex staff switch, manual
+Voices can be switched between staves manually, using the following command:
@example
- @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
+ \translator Staff = @var{staffname} @var{music}
@end example
+The string @var{staffname} is the name of the staff. It switches the
+current voice from its current staff to the Staff called
+@var{staffname}. Typically @var{staffname} is @code{"up"} or
+@code{"down"}.
-where each of the items is one of
+@c . {Pedals}
+@node Pedals
+@subsection Pedals
+@cindex Pedals
-@itemize @bullet
- @item An assignment.
+Piano pedal instruction can be expressed using
+@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
+@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
- @item A context definition. See @ref{Interpretation context} for
- more information on context definitions.
+These identifiers are shorthands for spanner commands of the types
+@internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
- @item \stylesheet declaration. Its syntax is
- @example
- \stylesheet @var{alist}
- @end example
+@lilypond[fragment,verbatim]
+c''4 \spanrequest \start "Sustain" c''4
+c''4 \spanrequest \stop "Sustain"
+@end lilypond
- 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.
+The symbols that are printed can be modified by setting
+@code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
+Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
+@rgrob{SustainPedal}, for example, for more information.
-@end itemize
+Pedals can also be indicated by a sequence of brackets, by setting the
+@code{pedal-type} property of SustainPedal grobs:
-@c . {Paper variables}
-@node Paper variables
-@subsection Paper variables
-@cindex Paper variables
+@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
+@end lilypond
-The paper block has some variables you may want to use or change:
+A third style of pedal notation is a mixture of text and brackets,
+obtained by setting @code{pedal-type} to @code{mixed}:
-@table @code
-@cindex @code{indent}
- @item @code{indent}
- The indentation of the first line of music.
-@cindex @code{staffspace}
+@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
+@end lilypond
- @item @code{staffspace}
- The distance between two staff lines, calculated from the center
- of the lines.
+The default '*Ped' style for sustain and damper pedals corresponds to
+@code{\pedal-type = #'text}. However, @code{mixed} is the default style
+for a sostenuto pedal:
-@cindex @code{linewidth}
- @item @code{linewidth}
- Sets the width of the lines.
+@lilypond[fragment,verbatim]
+c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
+@end lilypond
-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.
+For fine-tuning of the appearance of a pedal bracket, the properties
+@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
+@code{PianoPedalBracket} grobs (see the detailed documentation of
+@rgrob{PianoPedalBracket}) can be modified. For example, the bracket
+may be extended to the end of the note head.
-@cindex @code{textheight}
+@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
+@end lilypond
- @item @code{textheight}
- Sets the total height of the music on each page. Only used by
-@code{ly2dvi}.
-@cindex @code{interscoreline}
- @item @code{interscoreline}
- Sets the spacing between systems. The default is 16pt.
-
-@cindex @code{interscorelinefill}
+@c . {Arpeggio}
+@node Arpeggio
+@subsection Arpeggio
+@cindex Arpeggio
+
+@cindex broken arpeggio
+@cindex @code{\arpeggio}
+
+You can specify an arpeggio sign on a chord by attaching an
+@code{\arpeggio} to a note of the chord.
- @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.
+@lilypond[fragment,relative,verbatim]
+ \context Voice <c\arpeggio e g c>
+@end lilypond
+When an arpeggio crosses staves in piano music, you attach an arpeggio
+to the chords in both staves, and set
+@code{PianoStaff.connectArpeggios}.
-@cindex @code{stafflinethickness}
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.connectArpeggios = ##t
+ \context Voice = one { <c'\arpeggio e g c> }
+ \context Voice = other { \clef bass <c,,\arpeggio e g>}
+ >
+@end lilypond
- @item @code{stafflinethickness}
- Determines the thickness of staff lines, and also acts as a scaling
- parameter for other line thicknesses.
-@end table
+This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
+are @code{PianoStaff.Arpeggio}.
-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
+To add an arrow head to explicitly specify the direction of the
+arpeggio, you should set the arpeggio grob property
+@code{arpeggio-direction}.
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.Arpeggio \set #'arpeggio-direction = #1
+ <c\arpeggio e g c>
+ \property Voice.Arpeggio \set #'arpeggio-direction = #-1
+ <c\arpeggio e g c>
+ }
+@end lilypond
-@c . {Font size}
-@node Font Size
-@subsection Font size
-@cindex font size
+A square bracket on the left indicates that the player should not
+arpeggiate the chord. To draw these brackets, set the
+@code{molecule-callback} property of @code{Arpeggio} or
+@code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
+@code{\arpeggio} statements within the chords as before.
-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.
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.connectArpeggios = ##t
+ \property PianoStaff.Arpeggio \override
+ #'molecule-callback = \arpeggioBracket
+ \context Voice = one { <c'\arpeggio e g c> }
+ \context Voice = other { \clef bass <c,,\arpeggio e g>}
+ >
+@end lilypond
-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.
-The font definitions are generated using a Scheme function. For more
-details, see the file @file{scm/font.scm}.
+@refbugs
+It is not possible to mix connected arpeggios and unconnected
+arpeggios in one PianoStaff at the same time.
-@c . {Paper size}
-@node Paper size
-@subsection Paper size
-@cindex Paper size
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+@node Voice follower lines
+@subsection Voice follower lines
-To change the paper size, you must first set the
-@code{papersize} variable at top level. 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.
+@cindex follow voice
+@cindex staff switching
+@cindex cross staff
-@example
- papersize = "a4"
- \include "paper16.ly"
-@end example
+@cindex @code{followVoice}
-The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
-will set the paper variables @code{hsize} and @code{vsize} (used by
-@code{ly2dvi})
+Whenever a voice switches to another staff a line connecting the notes
+can be printed automatically. This is enabled if the property
+@code{PianoStaff.followVoice} is set to true:
-@c . {Line break}
-@node Line break
-@subsection Line break
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.followVoice = ##t
+ \context Staff \context Voice {
+ c1
+ \translator Staff=two
+ b2 a
+ }
+ \context Staff=two {\clef bass \skip 1*2 }
+ >
+@end lilypond
-@cindex line breaks
-@cindex breaking lines
+The associated grob is @internalsref{VoiceFollower}.
-Line breaks are normally computed automatically. They are chosen such
-that the resulting spacing has low variation, and looks neither cramped
-nor loose.
-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.
+@node Tablatures
+@section Tablatures
-@cindex @code{\penalty}
+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.
-The @code{\break} and @code{\noBreak} commands are defined in terms of
-the penalty command:
-@example
- \penalty @var{int}
-@end example
+@menu
+* Tablatures basic::
+* Non-guitar tablatures::
+* Tablature in addition to normal staff::
+@end menu
-This encourages or discourages LilyPond to make a line break at this
-point.
+@node Tablatures basic
+@subsection Tablatures basic
+@cindex Tablatures basic
-@refbugs
+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.
-The scaling of the @code{\penalty} argument is not well-defined. The
-command is rather kludgey, and slated for rewriting.
+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).
-@c . {Page break}
-@node Page break
-@subsection Page break
+@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
-@cindex page breaks
-@cindex breaking pages
+@node Non-guitar tablatures
+@subsection Non-guitar tablatures
+@cindex Non-guitar tablatures
-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}
+There are many ways to customize Lilypond tablatures.
-@example
- \newpage
-@end example
+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.
-@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}
+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.
-@c . {Output scaling}
-@node Output scaling
-@subsection Output scaling
+@node Tablature in addition to normal staff
+@subsection Tablature in addition to normal staff
+@cindex Tablature in addition to normal staff
-[TODO]
+It is possible to typeset both tablature and a "normal" staff, as
+commonly done in many parts.
-@example
-dvips ...
-@end example
+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.
+@c FIXME
+@c @lily pond[verbatim]
@example
-pstops ...
+ 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 example
+@c @end lilypond
+@c . {Chords}
+@node Chords
+@section Chords
+@cindex Chords
-@refbugs
-
-There is no mechanism to select magnification of particular fonts,
-meaning that you don't have access to continuously scaled fonts.
-
+LilyPond has support for both entering and printing chords.
+@lilypond[verbatim,singleline]
+twoWays = \notes \transpose c'' {
+ \chords {
+ c1 f:sus4 bes/f
+ }
+ <c e g>
+ <f bes c'>
+ <f bes d'>
+ }
+\score {
+ < \context ChordNames \twoWays
+ \context Voice \twoWays > }
+@end lilypond
-@c . {Output formats}
-@node Output formats
-@section Output formats
+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.
-LilyPond can output processed music in different output formats.
+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
-* TeX output::
-* PostScript output::
-* Scheme output::
-* ASCIIScript output::
+* Chords mode::
+* Printing named chords::
@end menu
-@node TeX output
-@subsection TeX output
-@cindex TeX output
+@c . {Chords mode}
+@node Chords mode
+@subsection Chords mode
+@cindex Chords mode
+
+Chord mode is a mode where you can input sets of pitches using common
+names. It is introduced by the keyword @code{\chords}. It is similar
+to note mode, but words are also looked up in a chord modifier table
+(containing @code{maj}, @code{dim}, etc). Dashes and carets are used
+to indicate chord additions and subtractions, so articulation scripts
+can not be entered in Chord mode.
-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.
+Throughout these examples, chords have been shifted around the staff
+using @code{\transpose}.
-@refbugs
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1 c:3- c:7 c:8
+ c:9 c:9-.5+.7+ c:3-.5-
+ }
+}
+@end lilypond
+
+@cindex @code{aug}
+@cindex @code{dim}
+@cindex @code{maj}
+@cindex @code{sus}
-Titling is not generated unless you use @file{ly2dvi}.
+The second type of modifier that may appear after the @code{:} is a
+named modifier. Named modifiers are listed in the file
+@file{chord-modifiers.ly}. The available modifiers are @code{m} and
+@code{min} which lower the 3rd half a step, `@code{aug}' which
+raises the 5th, `@code{dim}' which lowers the 5th,
+`@code{maj}' which adds a raised 7th, and `@code{sus}'
+which replaces the 5th with a 4th.
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1:m c:min7 c:maj c:aug c:dim c:sus
+ }
+}
+@end lilypond
+
-@node PostScript output
-@subsection PostScript output
-@cindex PostScript output
-@cindex direct PostScript output
+Chord subtractions are used to eliminate notes from a chord. The
+notes to be subtracted are listed after a @code{^} character,
+separated by dots.
-LilyPond 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.
+@lilypond[fragment,verbatim,center]
+ \transpose c'' {
+ \chords {
+ c1^3 c:7^5.3 c:8^7
+ }
+ }
+@end lilypond
+@cindex @code{/}
-@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
+Chord inversions can be specified by appending `@code{/}' and the name
+of a single note to a chord. In a chord inversion, the inverted note is
+transposed down until it is the lowest note in the chord. If the note
+is not in the chord, a warning will be printed.
+@lilypond[fragment,verbatim,center]
+ \transpose c''' {
+ \chords {
+ c1 c/e c/g c:7/e
+ }
+ }
-@refbugs
+@end lilypond
+@cindex @code{/+}
-Text font selection is broken.
+Bass notes can be added by `@code{/+}' and
+the name of a single note to a chord. This has the effect of
+adding the specified note to the chord, lowered by an octave,
+so it becomes the lowest note in the chord.
-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.
+@lilypond[fragment,verbatim,center]
+ \transpose c''' {
+ \chords {
+ c1 c/+c c/+g c:7/+b
+ }
+ }
-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.
+@end lilypond
+The formal syntax for named chords is as follows:
@example
- ...
- \paper @{
- % Set line height to 40 staff spaces
- lineheight = 40
- @}
+ @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
@end example
-@node Scheme output
-@subsection Scheme output
-@cindex Scheme output
+@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.
+
-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
+@refbugs
-@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
+Implementation details are gory. For example @code{c:4} not only adds
+a fourth, but also removes the third.
-@node ASCIIScript output
-@subsection ASCIIScript output
-@cindex ASCIIScript output
-@cindex ascii script
-@cindex ascii art
+@c . {Printing named chords}
+@node Printing named chords
+@subsection Printing named chords
-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.
+@cindex printing chord names
+@cindex chord names
+@cindex chords
-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
+For displaying printed chord names, use the @internalsref{ChordNames} context.
+The chords may be entered either using the notation described above, or
+directly using simultaneous music.
-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:
+@lilypond[verbatim,singleline]
+scheme = \notes {
+ \chords {a1 b c} <d f g> <e g b>
+}
+\score {
+ \notes<
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+}
+@end lilypond
-@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
+You can make the chord changes stand out by setting
+@code{ChordNames.chordChanges} to true. This will only display chord
+names when there's a change in the chords scheme and at the start of a
+new line.
+@lilypond[verbatim]
+scheme = \chords {
+ c1:m c:m \break c:m c:m d
+}
+\score {
+ \notes <
+ \context ChordNames {
+ \property ChordNames.chordChanges = ##t
+ \scheme }
+ \context Staff \transpose c'' \scheme
+ >
+\paper{linewidth= 9.\cm}
+}
+@end lilypond
-@refbugs
+LilyPond examines chords specified as lists of notes to determine a name
+to give the chord. LilyPond will not try to identify chord inversions or
+an added bass note, which may result in strange chord names when chords
+are entered as a list of pitches:
-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}.
+@lilypond[verbatim,center,singleline]
+scheme = \notes {
+ <c'1 e' g'>
+ <e' g' c''>
+ <e e' g' c''>
+}
-Lots of resizable symbols such as slurs, ties and tuplets are missing.
+\score {
+ <
+ \context ChordNames \scheme
+ \context Staff \scheme
+ >
+}
+@end lilypond
-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
-@section Sound
-@cindex Sound
+By default, a chord name system proposed by Harald Banter (See
+@ref{Literature}) is used. The system is very regular and predictable.
+Typical American style chord names may be selected by setting the
+@code{style} property of the @code{ChordNames.ChordName} grob to
+@code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
-LilyPond can produce MIDI output. The performance lacks lots of
-interesting effects, such as swing, articulation, slurring, etc., but it
-is good enough for proof-hearing the music you have entered. Ties,
-dynamics and tempo changes are interpreted.
+Routines that determine the names to be printed are written in Scheme,
+and may be customized by the user. The code can be found in
+@file{scm/chord-name.scm}. Here's an example showing the differences in
+chord name styles:
-Dynamic marks, crescendi and decrescendi translate into MIDI volume
-levels. Dynamic marks translate to a fixed fraction of the available
-MIDI volume range, crescendi and decrescendi make the the volume vary
-linearly between their two extremities. The fractions be adjusted by
-overriding the @code{absolute-volume-alist} defined in
-@file{scm/midi.scm}.
+@c too long?
+@c maybe just junk verbatim option?
+@lilypond[verbatim,singleline]
+scheme = \chords {
+ c1 c:5^3 c:4^3 c:5+
+ c:m7+ c:m5-.7
+ c:5-.7 c:5+.7
+ c:9^7
+}
-For each type of musical instrument (that MIDI supports), a volume range
-can be defined. This gives you basic equalizer control, which can
-enhance the quality of the MIDI output remarkably. You can add
-instruments and ranges or change the default settings by overriding the
-@code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
+\score {
+ \notes <
+ \context ChordNames = banter \scheme
+ \context ChordNames = american {
+ \property ChordNames.ChordName \override
+ #'style = #'american \scheme }
+ \context ChordNames = jazz {
+ \property ChordNames.ChordName \override
+ #'style = #'jazz \scheme }
+ \context Staff \transpose c'' \scheme
+ >
+}
+@end lilypond
-Both loudness controls are combined to produce the final MIDI volume.
+@node Writing parts
+@section Writing parts
-@refbugs
+Orchestral music involves some special notation, both in the full score,
+as in the individual parts. This section explains how to tackle common
+problems in orchestral music.
-It is currently not possible to use the percussion channel (generally
-channel 10 of a MIDI file).
+@c . {Transpose}
@menu
-* MIDI block::
-* MIDI instrument names::
+* Rehearsal marks::
+* Bar numbers::
+* Instrument names::
+* Transpose::
+* Multi measure rests::
+* Automatic part combining::
+* Hara kiri staves::
+* Sound output for transposing instruments::
@end menu
-@c . {MIDI block}
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
-
+@c . {Rehearsal marks}
+@node Rehearsal marks
+@subsection Rehearsal marks
+@cindex Rehearsal marks
+@cindex mark
+@cindex @code{\mark}
-The MIDI block is analogous to the paper block, but it is somewhat
-simpler. The @code{\midi} block can contain:
-@cindex MIDI block
+To print a rehearsal mark, use the @code{\mark} command.
+@lilypond[fragment,verbatim]
+\relative c'' {
+ c1 \mark "A"
+ c1 \mark \default
+ c1 \mark \default
+ c1 \mark "12"
+ c1 \mark \default
+ c1
+}
+@end lilypond
-@itemize @bullet
- @item a @code{\tempo} definition
- @item context definitions
-@end itemize
+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
-Assignments in the @code{\midi} block are not allowed.
+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
-@cindex context definition
+@node Bar numbers
+@subsection Bar numbers
-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}.
+@cindex bar numbers
+@cindex measure numbers
+@cindex currentBarNumber
-@node MIDI instrument names
-@subsection MIDI instrument names
+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
-@cindex instrument names
-@cindex @code{Staff.midiInstrument}
-@cindex @code{Staff.instrument}
+If you want boxed bar numbers, see the example file
+@code{input/test/boxed-molecule.ly}.
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property or, if that property is not set, the @code{Staff.instrument}
-property. The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
+See also @seeinternals{BarNumber}.
@refbugs
-If the selected string does not exactly match, then LilyPond uses the
-default (Grand Piano). It is not possible to select an instrument by
-number.
+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
+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 }
+@end lilypond
+You can also use markup texts to construct more complicated instrument
+names:
+@lilypond[verbatim,singleline]
+#(define text-flat
+ '((font-relative-size . -2 ) (music "accidentals--1")))
+\score { \notes {
+ \property Staff.instrument = #`((kern . 0.5) (lines
+ "2 Clarinetti" (columns " (B" ,text-flat ")")))
+ c'' 4 }
+}
+@end lilypond
-@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.
+@refbugs
-@c . {Relative}
-@node Relative
-@subsection Relative
-@cindex Relative
-@cindex relative octave specification
+When you put a name on a grand staff or piano staff the width of the
+brace is not taken into account. You must add extra spaces to the end of
+the name to avoid a collision.
-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.
+@node Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
-@cindex @code{\relative}
+A music expression can be transposed with @code{\transpose}. The syntax
+is
@example
- \relative @var{startpitch} @var{musicexpr}
+ \transpose @var{pitch} @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})
+This means that middle C in @var{musicexpr} is transposed to
+@var{pitch}.
-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}.
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose cis'} or @code{\transpose des'} will transpose up half
+a tone. The first version will print sharps and the second version
+will print flats.
-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
- }
+@lilypond[singleline, verbatim]
+mus =\notes { \key d \major cis d fis g }
+\score { \notes \context Staff {
+ \clef "F" \mus
+ \clef "G"
+ \transpose g'' \mus
+ \transpose f'' \mus
+}}
@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'' }
+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}.
+
+@c . {Multi measure rests}
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex Multi measure rests
+
+@cindex @code{R}
+
+Multi measure rests are entered using `@code{R}'. It is specifically
+meant for full bar rests and for entering parts: the rest can expand to
+fill a score with
+rests, or it can be printed as a single multimeasure rest This expansion
+is controlled by the property @code{Score.skipBars}. If this is set to true,
+Lily will not expand empty measures, and the appropriate number is added
+automatically.
+
+@lilypond[fragment,verbatim]
+ \time 3/4 r2. | R2. | R2.*2
+ \property Score.skipBars = ##t R2.*17 R2.*4
@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.
+Notice that the @code{R2.} is printed as a whole rest, centered in the
+measure.
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
- }
-@end lilypond
-@cindex @code{\notes}
+@cindex whole rests for a full measure
-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 grob for this object is @internalsref{MultiMeasureRest}.
+
+@refbugs
-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}.
+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
-@c . {Bar check}
-@node Bar check
-@subsection Bar check
-@cindex Bar check
+@node Automatic part combining
+@subsection Automatic part combining
+@cindex automatic part combining
+@cindex part combiner
-@cindex bar check
-@cindex @code{barCheckNoSynchronize}
-@cindex @code{|}
+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.
-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.
+The syntax for part combining is
-A bar check is entered using the bar symbol, @code{|}:
@example
- \time 3/4 c2 e4 | g2.
+ \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
@end example
+where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
+combined into one context of type @var{context}. The music expressions
+must be interpreted by contexts whose names should start with @code{one}
+and @code{two}.
-@c . {Point and click}
-@node Point and click
-@subsection Point and click
+The most useful function of the part combiner is to combine parts into
+one voice, as common for wind parts in orchestral scores:
-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.
+@lilypond[verbatim,singleline,fragment]
+ \context Staff <
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ g a () b r
+ }
+ \context Thread=two \relative c'' {
+ g r4 r f
+ }
+ >
+@end lilypond
-To use it, you need the following software
+Notice that the first @code{g} appears only once, although it was
+specified twice (once in each part). Stem, slur and tie directions are
+set automatically, depending whether there is a solo or unisono. The
+first part (with context called @code{one}) always gets up stems, and
+`solo', while the second (called @code{two}) always gets down stems and
+`Solo II'.
-@unnumberedsubsec Installation
+If you just want the merging parts, and not the textual markings, you
+may set the property @var{soloADue} to false.
-@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
+@lilypond[verbatim,singleline,fragment]
+ \context Staff <
+ \property Staff.soloADue = ##f
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ b4 a c g
+ }
+ \context Thread=two \relative c'' {
+ d,2 a4 g'
+ }
+ >
+@end lilypond
-Xdvi must be configured to find the TeX fonts and music
-fonts. Refer to the Xdvi documentation for more information.
+There are a number of other properties that you can use to tweak the
+behavior of part combining, refer to the automatically generated
+documentation of @reng{Thread_devnull_engraver} and
+@reng{Voice_devnull_engraver}. Look at the documentation of the
+responsible engravers, @code{Thread_devnull_engraver},
+@code{Voice_devnull_engraver} and @code{A2_engraver}.
+@refbugs
-@unnumberedsubsec Using it
+In @code{soloADue} mode, when the two voices play the same notes on and
+off, the part combiner may typeset @code{a2} more than once in a
+measure.
-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}.
+@lilypond[fragment,singleline]
+ \context Staff <
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ c b c b c a c a
+ }
+ \context Thread=two \relative c'' {
+ b b b b f a f a
+ }
+ >
+@end lilypond
-@example
-#(set! point-and-click line-location)
-@end example
+@cindex @code{Thread_devnull_engraver}
+@cindex @code{Voice_engraver}
+@cindex @code{A2_engraver}
-In the emacs startup file (usually @file{~/.emacs}), add the following
-@example
-(server-start)
-@end example
+@node Hara kiri staves
+@subsection Hara kiri staves
-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.
+In orchestral scores, staff lines that only have rests are usually removed.
+This saves some space. LilyPond also supports this through the hara
+kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
+the Japanese Samourai warriors.} staff. This staff commits suicide when
+it finds itself to be empty after the line-breaking process. It will
+not disappear when it contains normal rests, you must use multi measure
+rests.
-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.
+The hara kiri staff is specialized version of the @internalsref{Staff}
+context. It is available as the context identifier
+@code{\HaraKiriStaffContext}. Observe how the second staff in this
+example disappears in the second line.
+@lilypond[verbatim]
+\score {
+ \notes \relative c' <
+ \context Staff = SA { e4 f g a \break c1 }
+ \context Staff = SB { c4 d e f \break R1 }
+ >
+ \paper {
+ linewidth = 6.\cm
+ \translator { \HaraKiriStaffContext }
+ }
+}
+@end lilypond
-@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.
+@node Sound output for transposing instruments
+@subsection Sound output for transposing instruments
-@example
- (setq load-path (cons "~/usr/share/emacs" load-path))
-@end example
+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.
-Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
+@cindex @code{transposing}
-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)
+ \property Staff.instrument = #"Cl. in B-flat"
+ \property Staff.transposing = #-2
@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
+@c . {Custodes}
+@node Ancient notation
+@section Ancient notation
-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.
+@menu
+* Ancient note heads::
+* Custodes::
+* Ancient clefs ::
+* Figured bass::
+@end menu
-@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.
+@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]
-\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 }
+ \property Voice.NoteHead \set #'style = #'mensural
+ \property Voice.NoteHead \set #'font-family = #'ancient
+ a'\longa
@end lilypond
+@node Custodes
+@subsection Custodes
-@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
+@cindex Custos
+@cindex Custodes
-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.
+A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
+staff context symbol that appears at the end of a staff line. It
+anticipates the pitch of the first note(s) of the following line and
+thus helps the player or singer to manage line breaks during
+performance, thus enhancing readability of a score.
-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.
+@lilypond[verbatim]
+\score {
+ \notes { c'1 \break
+ \property Staff.Custos \set #'style = #'mensural
+ d' }
+ \paper {
+ \translator {
+ \StaffContext
+ \consists Custos_engraver
+ }
+ }
+}
+@end lilypond
+Custodes were frequently used in music notation until the 17th century.
+There were different appearances for different notation styles.
+Nowadays, they have survived only in special forms of musical notation
+such as via the @emph{editio vaticana} dating back to the beginning of
+the 20th century.
-@node Creating contexts
-@subsection Creating contexts
+For typesetting custodes, just put a @code{Custos_engraver} into the
+@internalsref{Staff} context when declaring the @code{\paper} block. In this
+block, you can also globally control the appearance of the custos symbol
+by setting the custos @code{style} property. Currently supported styles
+are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
+@code{mensural}.
-@cindex @code{\context}
-@cindex context selection
+@example
+\paper @{
+ \translator @{
+ \StaffContext
+ \consists Custos_engraver
+ Custos \override #'style = #'mensural
+ @}
+@}
+@end example
-Contexts for a music expression can be selected manually, using the
-following music expression.
+The property can also be set locally, for example in a @code{\notes}
+block:
@example
- \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+\notes @{
+ \property Staff.Custos \override #'style = #'vaticana
+ c'1 d' e' d' \break c' d' e' d'
+@}
@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.
+@node Ancient clefs
+@subsection Ancient clefs
-@lilypond[verbatim,singleline]
-\score {
- \notes \relative c'' {
- c4 <d4 \context Staff = "another" e4> f
- }
-}
+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
-@end lilypond
+@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.''
-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.
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel clefs
+@node Figured bass
+@subsection Figured bass
-@node Default contexts
-@subsection Default contexts
+@cindex Basso continuo
-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 has limited support for figured bass:
-@lilypond[verbatim,singleline]
-\score { \notes \context Voice = goUp { c'4 d' e' } }
+@lilypond[verbatim,fragment]
+<
+ \context FiguredBass
+ \figures {
+ <_! 3+ 5- >4
+ < [4 6] 8 >
+ }
+ \context Voice { c4 g8 }
+>
@end lilypond
-There are some quirks that you must keep in mind when dealing with
-defaults:
+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.
-First, every top level music is interpreted by the Score context, in other
-words, you may think of @code{\score} working like
+In figures input mode, a group of bass figures is delimited by
+@code{<} and @code{>}. The duration is entered after the @code{>}.
@example
- \score @{
- \context Score @var{music}
- @}
+ <4 6>
@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 <c'4 es'> }
-@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 <c'4 es'> } }
+@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{+}.
-
-@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}
+ <4- 6+ 7!>
@end example
+@lilypond[fragment]
+ \context FiguredBass
+\figures { <4- 6+ 7!> }
+@end lilypond
-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.
+Spaces or dashes may be inserted by using @code{_}. Brackets are
+introduced with @code{[} and @code{]}.
-Properties can be unset using the following expression:
@example
- \property @var{contextname}.@var{propname} \unset
+ < [4 6] 8 [_ 12]>
@end example
+@lilypond[fragment]
+ \context FiguredBass
+\figures { < [4 6] 8 [_ 12]> }
+@end lilypond
-@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}.
+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.
-@node Engravers and performers
-@subsection Engravers and performers
-[TODO]
+@c . {Tuning output}
+@node Tuning output
+@section Tuning output
-Basic building blocks of translation are called engravers; they are
-special C++ classes.
+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.
-@c . {Context definitions}
-@node Changing context definitions
-@subsection Changing context definitions
+@menu
+* Tuning groups of grobs ::
+* Tuning per grob ::
+* Font selection::
+* Text markup::
+@end menu
-@cindex context definition
-@cindex translator definition
+@node Tuning groups of grobs
+@subsection Tuning groups of grobs
-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
+@cindex grob description
-Here @var{engravername} is a string, the name of an engraver in the
-system.
+A grob definition is a Scheme association list, that is stored in a
+context property. By assigning to that property (using plain
+@code{\property}), you can change the resulting grobs.
-@lilypond[verbatim,singleline]
-\score { \notes {
- c'4 c'4 }
- \paper {
- \translator { \StaffContext
- \remove Clef_engraver
- } } }
+@lilypond[verbatim, fragment]
+c'4 \property Voice.Stem = #'()
@end lilypond
-@cindex engraver
+The @code{\property} assignment effectively empties the definition of
+the Stem object. One of the effects is that the recipe of how it should be
+printed is erased, with the effect of rendering it invisible. The above
+assignment is available as a standard identifier, for the case that you
+find this useful:
-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}
+ \property Voice.Stem = \turnOff
@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
+@cindex \override
+@cindex \revert
+@cindex \set
-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}}.
+This mechanism is fairly crude, since you can only set, but not modify,
+the definition of a grob. For this reason, there is a more advanced
+mechanism.
- @item A cooperation module. This is specified by @code{\type
-@var{typename}}.
-@end itemize
+The definition of a grob is actually a list of default grob
+properties. For example, the definition of the Stem grob (available in
+@file{scm/grob-description.scm}), defines the following values for
+@internalsref{Stem}
-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"
-}@
+ (thickness . 0.8)
+ (beamed-lengths . (0.0 2.5 2.0 1.5))
+ (Y-extent-callback . ,Stem::height)
+ @var{...}
@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}
+You can add a property on top of the existing definition, or remove a
+property, thus overriding the system defaults:
+@lilypond[verbatim]
+c'4 \property Voice.Stem \override #'thickness = #4.0
+c'4 \property Voice.Stem \revert #'thickness
+c'4
+@end lilypond
+You should balance @code{\override} and @code{\revert}. If that's too
+much work, you can use the @code{\set} shorthand. It performs a revert
+followed by an override. The following example gives exactly the same
+result as the previous one.
+@lilypond[verbatim]
+c'4 \property Voice.Stem \set #'thickness = #4.0
+c'4 \property Voice.Stem \set #'thickness = #0.8
+c'4
+@end lilypond
+If you use @code{\set}, you must explicitly restore the default.
- @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}
+Formally the syntax for these constructions is
+@example
+\property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
+\property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
+\property @var{context}.@var{grobname} \revert @var{symbol}
+@end example
+Here @var{symbol} is a Scheme expression of symbol type, @var{context}
+and @var{grobname} are strings and @var{value} is a Scheme expression.
- @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
+If you revert a setting which was not set in the first place, then it
+has no effect. However, if the setting was set as a system default, it
+may remove the default value, and this may give surprising results,
+including crashes. In other words, @code{\override} and @code{\revert},
+must be carefully balanced.
-@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
+These are examples of correct nesting of @code{\override}, @code{\set},
+@code{\revert}.
-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
+A clumsy but correct form:
+@example
+ \override \revert \override \revert \override \revert
+@end example
-@quotation
+Shorter version of the same:
@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
+ \override \set \set \revert
+@end example
-@end quotation
+A short form, using only @code{\set}. This requires you to know the
+default value:
+@example
+ \set \set \set \set @var{to default value}
+@end example
+
+If there is no default (i.e. by default, the grob property is unset),
+then you can use
+@example
+ \set \set \set \revert
+@end example
+For the digirati, the grob description is an Scheme association
+list. Since a Scheme list is a singly linked list, we can treat it as a
+stack, and @code{\override} and @code{\revert} are just push and pop
+operations. This pushing and popping is also used for overriding
+automatic beaming settings.
-@cindex paper types, engravers, and pre-defined translators
+@refbugs
-
+LilyPond will hang or crash if @var{value} contains cyclic references.
+The backend is not very strict in type-checking grob properties. If you
+@code{\revert} properties that are expected to be set by default,
+LilyPond may crash.
-@c . {Syntactic details}
-@node Syntactic details
-@section Syntactic details
-@cindex Syntactic details
+@node Tuning per grob
+@subsection Tuning per grob
-This section describes details that were too boring to be put elsewhere.
+@cindex \outputproperty
-@menu
-* Top level::
-* Identifiers::
-* Music expressions::
-* Manipulating music expressions::
-* Assignments::
-* Lexical modes::
-* Ambiguities::
-@end menu
+A second way of tuning grobs is the more arcane @code{\outputproperty}
+feature. The syntax is as follows:
+@example
+\outputproperty @var{predicate} @var{symbol} = @var{value}
+@end example
+Here @code{predicate} is a Scheme function taking a grob argument, and
+returning a boolean. This statement is processed by the
+@code{Output_property_engraver}. It instructs the engraver to feed all
+grobs that it sees to @var{predicate}. Whenever the predicate returns
+true, the grob property @var{symbol} will be set to @var{value}.
-@c . {Top level}
-@node Top level
-@subsection Top level
-@cindex Top level
+You will need to combine this statement with @code{\context} to select
+the appropriate context to apply this to.
-This section describes what you may enter at top level.
+Here are some random examples.
-@c . {Score}
-@subsubsection Score
-@cindex Score
+In the following example, all note heads occurring at current staff
+level, are shifted up and right by setting their @code{extra-offset}
+property.
-@cindex score definition
+@lilypond[fragment,verbatim,singleline]
+\relative c'' { c4
+ \context Staff \outputproperty
+ #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(0.5 . 0.75)
+ <c8 e g> }
+@end lilypond
-The output is generated combining a music expression with an output
-definition. A score block has the following syntax:
+@cindex @code{extra-offset}
-@example
- \score @{ @var{musicexpr} @var{outputdefs} @}
-@end example
+In this example, the predicate checks the @code{text} grob property, to
+shift only the `m.d.' text, but not the fingering instruction "2".
+@lilypond[verbatim,singleline]
+#(define (make-text-checker text)
+ (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
-@var{outputdefs} are zero or more output definitions. If none is
-supplied, the default @code{\paper} block will be added.
+\score {
+ \notes\relative c''' {
+ \property Voice.Stem \set #'direction = #1
+ \outputproperty #(make-text-checker "m.d.")
+ #'extra-offset = #'(-3.5 . -4.5)
+ a^2^"m.d."
+ }
+}
+@end lilypond
+@refbugs
+If possible, avoid this feature: the semantics are not very clean, and
+the syntax and semantics are up for rewrite.
-@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}
+@node Font selection
+@subsection Font selection
-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.
+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 @code{ly2dvi}
+@cindex cue notes
+@cindex font size
+@cindex size
-The syntax is
+The font used for printing a grob can be selected by setting
+@code{font-name}, e.g.
@example
- \header @{ @var{key1} = @var{val1}
- @var{key2} = @var{val2} @dots{} @}
+ \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}.
-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.
+@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{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},
+ @code{caps} and @code{upright}
-@c . {Identifiers}
-@node Identifiers
-@subsection Identifiers
-@cindex Identifiers
+@item font-series
+A symbol indicating the series of the font. There are typically several
+font series for each font family and shape. Choices are @code{medium}
+and @code{bold}.
-@ignore
- What has this section got to do with identifiers?
- It seems more appropriate in the introduction to Chapter 4,
- "Internals".
+@item font-relative-size
+ A number indicating the size relative the standard size. For example,
+ with 20pt staff height, relative size -1 corresponds to 16pt staff
+ height, and relative size +1 corresponds to 23 pt staff height.
- /MB
-@end ignore
+@item font-design-size
+A number indicating the design size of the font.
-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,
+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.
+@end table
-@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
+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-family = #'typewriter
+ \property Lyrics . LyricText \override #'font-shape = #'*
+@end example
-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.
+@cindex @code{font-style}
-@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})
+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.
-@end itemize
+@cindex magnification
+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.
-@node Music expressions
-@subsection Music expressions
+@refbugs
-@cindex music expressions
+Relative size is not linked to any real size.
-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}:
+There is no style sheet provided for other fonts besides the @TeX{}
+family, and the style sheet can not be modified easiyl.
-@example
-\sequential @{ c4 d4 @}
-@end example
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
-@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.
+@node Text markup
+@subsection Text markup
+@cindex text markup
+@cindex markup text
-@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 has an internal mechanism to typeset texts. You can
+form text markup expressions by composing scheme expressions
+in the following way.
-@lilypond[fragment,verbatim,center]
- \notes \context Voice {
- <a c'> <b d' > <c' e'>
- < { a b c' } { c' d' e' } >
+@lilypond[verbatim, singleline]
+ \relative c' {
+ \fatText
+ a^#"upright"
+ b_#'(bold "bold")
+ c^#'(italic "italic")
+ d_#'((bold italic) "ff")
+ e^#'(dynamic "ff")
+ f_#'(lines "one" (bold "two"))
+ g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
}
@end lilypond
+Normally, the Scheme markup text is stored in the @code{text} property
+of a grob. Formally, it is defined as follows:
-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}
+text: string | (head? text+)
+head: markup | (markup+)
+markup-item: property | abbrev
+property: (@var{key} . @var{value})
+abbrev: @code{columns lines roman music bold italic named super sub}
+ @code{overstrike text finger volta timesig mmrest mark script}
+ @code{large Large dynamic}
@end example
+The markup is broken down and converted into a list of grob properties,
+which are prepended to the property list. The @var{key}-@var{value}
+pair is a grob property. A list of properties available is included in
+the generated documentation for @internalsref{text-interface}.
-@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.
+The following abbreviations are defined:
+@table @code
+@item columns
+ horizontal mode: set all text on one line (default)
+@item lines
+ vertical mode: set every text on a new line
+@item roman
+ select roman font
+@item music
+ selects the Feta font (the standard font for music notation glyphs),
+and uses named lookup
-@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
+@item bold
+ select bold series
+@item italic
+ select italic shape
+@item named
+ lookup by character name
+@item text
+ plain text lookup (by character value)
+@item super
+ superscript
+@item sub
+ subscript
+@item overstrike
+ the next text or character overstrikes this one
+@item finger
+ select fingering number fontstyle
+@item volta
+ select volta number fontstyle
+@item timesig
+ select time signature number fontstyle
+@item mmrest
+ select multi measure rest number fontstyle
+@item mark
+ select mark number fontstyle
+@item script
+ select scriptsize roman fontstyle
+@item large
+ select large roman fontstyle
+@item Large
+ select Large roman fontstyle
+@item dynamic
+ select dynamics fontstyle
+@end table
-For more information on what is possible, see the automatically
-generated documentation.
+@cindex metronome mark
-Directly accessing internal representations is dangerous: the
-implementation is subject to changes, so you should avoid this feature
-if possible.
+One practical application of complicated markup is to fake a metronome
+marking:
-A final example is a function that reverses a piece of music in time:
+@lilypond[verbatim]
+#(define note '(columns
+ (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
+#(define eight-note `(columns ,note ((kern . -0.1)
+ (music ((raise . 3.5) "flags-u3")))))
+#(define dotted-eight-note
+ `(columns ,eight-note (music "dots-dot")))
-@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
+\score {
+ \notes\relative c'' {
+ a1^#`((columns (font-relative-size . -1))
+ ,dotted-eight-note " = 64")
+ }
+ \paper {
+ linewidth = -1.
+ \translator{
+ \ScoreContext
+ TextScript \override #'font-shape = #'upright
+ }
}
}
@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:
+@refbugs
+The syntax and semantics of markup texts are not clean, and both
+syntax and semantics are slated for a rewrite.
-@example
- \spanrequest @var{startstop} @var{type}
-@end example
+LilyPond does not do kerning, and there generally spaces texts
+slightly too wide.
-@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,
+@node Global layout
+@section Global layout
-@lilypond[fragment,verbatim,center]
- c'4-\spanrequest \start "slur"
- c'4-\spanrequest \stop "slur"
-@end lilypond
+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.
-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}.
+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
+* Vertical spacing::
+* Horizontal spacing::
+* Font Size::
+* Line breaking::
+* Page layout::
+@end menu
-@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.
+@node Vertical spacing
+@subsection Vertical spacing
-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.
+@cindex vertical spacing
+@cindex distance between staffs
+@cindex staff distance
+@cindex between staves, distance
-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.
+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.
+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
-foo = \foo * 2.0
+ \property Staff.minimumVerticalExtent = #'(-4 . 4)
@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.
+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
-\paper @{
- foo = 1.0
- \paperIdent % wrong and invalid
-@}
-
-\paper @{
- \paperIdent % correct
- foo = 1.0 @}
+ \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.
-@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}.
+@node Horizontal spacing
+@subsection Horizontal Spacing
-Different input modes may be nested.
-
-@c . {Ambiguities}
-@node Ambiguities
-@subsection Ambiguities
-@cindex ambiguities
-@cindex grammar
+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.
+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
-The grammar contains a number of ambiguities. We hope to resolve them at
-some time.
+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
-@itemize @bullet
- @item The assignment
+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
-@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
+@refbugs
-@example
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end example
+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.
- @end quotation
+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.
- 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.
+@lilypond
+\score {
+ \context PianoStaff \notes \transpose c''' <
+ \context Staff = up { s1 }
+ \context Staff = down { [c8 c \translator Staff=up <c d> c
+\translator Staff=down c c c] }
+ >
+ \paper { linewidth = -1 }
+}
+@end lilypond
- @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]
+@c . {Font size}
+@node Font Size
+@subsection Font size
+@cindex font size, setting
+@cindex staff size, setting
+@cindex @code{paper} file
-@end itemize
+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, 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 @{ ... @}
+@end example
-@c . {Lexical details}
-@node Lexical details
-@section Lexical details
+The font definitions are generated using a Scheme function. For more
+details, see the file @file{scm/font.scm}.
-Even more boring details, now on lexical side of the input parser.
-@menu
-* Comments::
-* Direct Scheme::
-* Keywords::
-* Integers::
-* Reals::
-* Strings::
-* Main input::
-* File inclusion::
-* Version information::
-@end menu
+@c . {Line break}
+@node Line breaking
+@subsection Line breaking
+@cindex line breaks
+@cindex breaking lines
-@node Comments
-@subsection Comments
+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. 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 comments
-@cindex block comment
-@cindex line comment
-@cindex @code{%}
+@cindex regular line breaks
+@cindex four bar music.
-A one line comment is introduced by a @code{%} character.
-Block comments are started by @code{%@{} and ended by @code{%@}}.
-They cannot be nested.
+If you want linebreaks at regular intervals, you can use the following:
+@example
+< \repeat 7 unfold @{ s1 * 4 \break @}
+ @emph{real music}
+>
+@end example
+This makes the following 28 measures (assuming 4/4 time) be broken every
+4 measures.
-@node Direct Scheme
-@subsection Direct Scheme
+@node Page layout
+@subsection Page layout
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
+@cindex page breaks
+@cindex breaking pages
+@cindex @code{indent}
+@cindex @code{linewidth}
-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).
+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.
-In-line scheme may be used at the top level. In this case the result is
-discarded.
+@cindex @code{textheight}
+@cindex @code{interscoreline}
+@cindex @code{interscorelinefill}
-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.
+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{lilypond-book: integrating text and music} for
+more information.
+@cindex @code{lastpagefill}
-@node Keywords
-@subsection Keywords
-@cindex Keywords
+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. 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}
-Keywords start with a backslash, followed by a number of lower case
-alphabetic characters. These are all the keywords.
+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
-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
+ \paper@{ papersize = "a4" @}
+ \include "paper16.ly"
@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.
+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})
-@node Reals
-@subsection Reals
-@cindex real numbers
+@c . {Sound}
+@node Sound
+@section Sound
+@cindex Sound
+LilyPond can produce MIDI output. The performance lacks lots of
+interesting effects, such as swing, articulation, slurring, etc., but it
+is good enough for proof-hearing the music you have entered. Ties,
+dynamics and tempo changes are interpreted.
-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.
+Dynamic marks, crescendi and decrescendi translate into MIDI volume
+levels. Dynamic marks translate to a fixed fraction of the available
+MIDI volume range, crescendi and decrescendi make the the volume vary
+linearly between their two extremities. The fractions be adjusted by
+overriding the @code{absolute-volume-alist} defined in
+@file{scm/midi.scm}.
-@cindex @code{\mm},
-@cindex @code{\in}
-@cindex @code{\cm}
-@cindex @code{\pt}
-@cindex dimensions
+For each type of musical instrument (that MIDI supports), a volume range
+can be defined. This gives you basic equalizer control, which can
+enhance the quality of the MIDI output remarkably. You can add
+instruments and ranges or change the default settings by overriding the
+@code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
-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.
+Both loudness controls are combined to produce the final MIDI volume.
-@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.
+@menu
+* MIDI block::
+* MIDI instrument names::
+@end menu
+@c . {MIDI block}
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
-@node Main input
-@subsection Main input
-@cindex Main input
-@cindex @code{\maininput}
+The MIDI block is analogous to the paper block, but it is somewhat
+simpler. The @code{\midi} block can contain:
+@cindex MIDI block
-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.
+@itemize @bullet
+ @item a @code{\tempo} definition
+ @item context definitions
+@end itemize
-@node File inclusion
-@subsection File inclusion
-@cindex @code{\include}
-@example
- \include @var{filename}
-@end example
+Assignments in the @code{\midi} block are not allowed.
-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
+@cindex context definition
-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}.
+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-init.ly}.
-@cindex convert-ly
+@node MIDI instrument names
+@subsection MIDI instrument names
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+@cindex @code{Staff.instrument}
+The MIDI instrument name is set by the @code{Staff.midiInstrument}
+property or, if that property is not set, the @code{Staff.instrument}
+property. The instrument name should be chosen from the list in
+@ref{MIDI instruments}.
+@refbugs
+If the selected string does not exactly match, then LilyPond uses the
+default (Grand Piano). It is not possible to select an instrument by
+number.
-@c .{Local emacs vars}
-@c Local variables:
-@c mode: texinfo
-@c minor-mode: font-lock
-@c minor-mode: outline
-@c outline-layout: (-1 : 0)
-@c outline-use-mode-specific-leader: "@c \."
-@c outline-primary-bullet: "{"
-@c outline-stylish-prefixes: nil
-@c outline-override-protect: t
-@c End: