-
-
-@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
@macro seeinternals{NAME}
@end macro
@macro internalsref{NAME}
-\NAME\
@cindex \NAME\
-
+\NAME\
@end macro
@end ifnothtml
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::
* Staff notation::
* Polyphony::
* Repeats::
* Rhythmic music::
* Piano music::
+* Tablatures::
* Lyrics::
* Chords::
* Writing parts::
-* Custodes::
+* Ancient notation ::
+* Ancient clefs ::
* Figured bass::
* Tuning output::
* Page layout::
* 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 ::
@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
c' c'' es' g' as' gisis' ais'
@end lilypond
+@node Chromatic alterations
+@subsection Chromatic alterations
+
+Normally Accidentals signify that the pitch of a note differs from the
+key signature. Normally, they are printed automatically depending, 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.
+
+Each accidental symbol is an @internalsref{Accidental} grob. The
+placement of accidentals is handled by
+@internalsref{AccidentalPlacement}.
+
+
@c . {Rests}
@node Rests
@subsection Rests
@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}
}
@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
@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.
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.
-
+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.
+@node Automatic note splitting
+@subsection Automatic note splitting
+
+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 the uses of this is, is to debug complex scores: if the
+measures are not entirely filled, then the ties exactly show how much
+each measure is off.
+
+@refbugs
+
+Not all durations (especially those containing tuplets) can be
+represented exactly; the engraver will not insert tuplets.
@node Tuplets
@subsection Tuplets
@code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
instead.
+@c todo: junk this?
+
The typesetting of brackets and numbers is controlled by the properties
-@code{tuplet-bracket-visibility} and @code{tuplet-number-visibility}.
+@code{bracket-visibility} and @code{number-visibility}. These
+properties can either be @code{#f}, @code{#t} or @code{'if-no-beam},
+meaning respectively off, on, and on if there is no beam.
@lilypond[fragment, relative, singleline, verbatim]
-\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t
+\property Voice.TupletBracket \set #'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
+\property Voice.TupletBracket \set #'bracket-visibility = #'if-no-beam
\times 2/3{c d e} \times 2/3{d4 e8}
-\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f
+\property Voice.TupletBracket \set #'bracket-visibility = ##f
\times 2/3{c d e} \times 2/3{d4 e8}
-\property Voice.TupletBracket \set #'tuplet-number-visibility = ##f
+\property Voice.TupletBracket \set #'number-visibility = ##f
\times 2/3{c d e} \times 2/3{d4 e8}
-\property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam
+\property Voice.TupletBracket \set #'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.
+Tuplet brackets are printed as @internalsref{TupletBracket} grobs in
+the @internalsref{Voice} context.
@c . {Defining pitch names}
@node Defining pitch names
\chordmodifiers @var{scheme-alist}
@end example
-See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers-init.ly} for
specific examples on how to do this.
@subsection Clef
@cindex @code{\clef}
-The clef can be set or changed with the @code{\clef} command.
-@example
- \clef @var{clefname}
-@end example
-
-Shortcut for
-
-@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
-
-
-Any change in these properties creates a clef (A @internalsref{Clef} grob).
+The clef can be set or changed with the @code{\clef} command:
+@lilypond[fragment,verbatim]
+ \key f\major c''2 \clef alto g'2
+@end lilypond
Supported clef-names include
-
@c Moved standard clefs to the top /MB
@table @code
@item treble, violin, G, G2
name. For example,
@example
\clef "G_8"
-@end example
+@end example
-Supported associated glyphs (for @code{Staff.clefGlyph}) are:
+The grob for this symbol is @internalsref{Clef}.
+
+
+The full syntax for this command is
+@example
+ \clef @var{clefname}
+@end example
+where @var{clefname} is a string. This command is a shortcut for
+@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
+Upon any change in these properties lilypond creates a clef
+symbol. The mapping from @var{clefname} to the property values can be
+found in @file{scm/clef.scm}
-@table @code
-@item clefs-C
- modern style C clef
-@item clefs-F
- modern style F clef
-@item clefs-G
- modern style G clef
-@item clefs-vaticana_do
- Editio Vaticana style do clef
-@item clefs-vaticana_fa
- Editio Vaticana style fa clef
-@item clefs-medicaea_do
- Editio Medicaea style do clef
-@item clefs-medicaea_fa
- Editio Medicaea style fa clef
-@item clefs-mensural1_c
- modern style mensural C clef
-@item clefs-mensural2_c
- historic style small mensural C clef
-@item clefs-mensural3_c
- historic style big mensural C clef
-@item clefs-mensural1_f
- historic style traditional mensural F clef
-@item clefs-mensural2_f
- historic style new mensural F clef
-@item clefs-mensural_g
- historic style mensural G clef
-@item clefs-hufnagel_do
- historic style hufnagel do clef
-@item clefs-hufnagel_fa
- historic style hufnagel fa clef
-@item clefs-hufnagel_do_fa
- historic style hufnagel combined do/fa clef
-@item clefs-percussion
- modern style percussion clef
-@end table
-@emph{Modern style} means ``as is typeset in current editions.''
-@emph{Historic style} means ``as was typeset or written in contemporary
-historic editions''. @emph{Editio XXX style} means ``as is/was printed in
-Editio XXX.''
-@cindex Vaticana, Editio
-@cindex Medicaea, Editio
-@cindex hufnagel clefs
@c . {Time signature}
@cindex @code{\time}
The time signature is set or changed by the @code{\time}
-command. Syntax:
-@example
- \time @var{n}@code{/}@var{d}
-@end example
-Internally, this is a shortcut for doing
-@example
-\property Score.timeSignatureFraction = #'(@var{n} . @var{d})
-\property Score.beatLength = #(make-moment 1 @var{d})
-\property Score.measureLength = #(make-moment @var{n} @var{d})
-@end example
-
-These properties @code{timeSignatureFraction} determine where bar lines
-should be inserted, and how automatic beams should be
-generated.
-
-Changing the value of @code{timeSignatureFraction} also causes a
-fraction to be printed. This grob is @internalsref{TimeSignature}.
+command.
+@lilypond[fragment,verbatim]
+ \time 2/4 c'2 \time 3/4 c'2.
+@end lilypond
The actual symbol that's printed can be customized with the style
property.
\time 2/2 s2
@end lilypond
-There are many more options for the layout of this grob. They are
-selected through the @code{style} grob property.
+The grob for this symbol is @internalsref{TimeSignature}. There are
+many more options for its layout. They are selected through the
+@code{style} grob property. See @file{input/test/time.ly} for more
+examples.
-@c FIXME: this isn't documented except in example?
-See
-@file{input/test/time.ly} for examples.
+
+The full syntax for this command is
+@example
+ \time @var{n}@code{/}@var{d}
+@end example
+where @var{n} and @var{d} are integers. This command is internally
+translated, to the following:
+@example
+\property Score.timeSignatureFraction = #'(@var{n} . @var{d})
+\property Score.beatLength = #(make-moment 1 @var{d})
+\property Score.measureLength = #(make-moment @var{n} @var{d})
+@end example
+
+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
+fraction to be printed.
@c . {Partial}
@subsection Partial
@cindex @code{\partial}
Partial measures, for example in upbeats, are entered using the
-@code{\partial} command:
+@code{\partial} command:
+@lilypond[fragment,verbatim]
+\partial 4* 5/16 c'16 c8. f16 a'2. ~ a'8. a'16 | g'1
+@end lilypond
+
+The syntax for this command is
@example
\partial @var{duration}
@end example
-
-Internally, this is a shortcut for
-
+This is internally translated into
@example
\property Score.measurePosition = -@var{length of duration}
@end example
@cindex @code{|}
-
The property @code{measurePosition} contains a rational number
-indicating how much of the measure has passed at this point.
+indicating how much of the measure has passed at this point.
@node Unmetered music
@cindex measure lines
@cindex repeat bars
-@example
- \bar @var{bartype}
-@end example
+Bar lines are inserted automatically by, but if you need a special
+types of barline, you can force one using the @code{\bar} command:
+@lilypond[fragment,verbatim]
+ c4 \bar "|:" c4
+@end lilypond
-This is a shortcut for doing
-@example
- \property Score.whichBar = @var{bartype}
-@end example
The following bar types are available
-
@lilypond[fragment, relative, singleline, verbatim]
c4
\bar "|" c
\bar "|."
@end lilypond
-
You are encouraged to use @code{\repeat} for repetitions. See
@ref{Repeats}.
+In scores with many staffs, the barlines are automatically placed at
+top level, and they are connected between different staffs of a
+@internalsref{StaffGroup}:
+@lilypond[fragment, verbatim]
+< \context StaffGroup <
+ \context Staff = up { e'4 d'
+ \bar "||"
+ f' e' }
+ \context Staff = down { \clef bass c4 g e g } >
+\context Staff = pedal { \clef bass c2 c2 } >
+@end lilypond
+
+The grobs that are created at @internalsref{Staff} level. The name is
+@internalsref{BarLine}.
+
+The full syntax for this command is
+@example
+ \bar @var{bartype}
+@end example
+where @var{bartype} is a string. This is a shortcut for doing
+@example
+ \property Score.whichBar = @var{bartype}
+@end example
+
@cindex Bar_line_engraver
@cindex whichBar
@code{\bar }. These settings take precedence over the automatic
@code{whichBar} settings.
-@internalsref{BarLine} grobs are created by the @code{Bar_engraver}.
-
@c . {Polyphony}
@node Polyphony
@section Polyphony
@lilypond[verbatim,fragment]
\context Voice = VA \apply #voicify-music \relative c'' {
- c4 < { f d e } \\ { b c2 } > c4 < g' \\ c, \\ f \\ d >
+ c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
}
@end lilypond
contexts, bearing the names @code{"1"}, @code{"2"}, etc.
To explicity typeset polyphonic music, instantiate a separate Voice
-context for each part, and assign a stem direction to each part.
+context for each part, and use @code{\voiceOne}, up to
+@code{\voiceFour} to assign a stem directions and horizontal shift for
+each part.
@c
-@lilypond[fragment,verbatim]
-\context Staff
-< \context Voice = VA { \stemUp b'4 a' g' f' e' }
- \context Voice = VB { \stemDown g'4 g' g' g' g' } >
+
+@lilypond[singleline, verbatim]
+\relative c''
+\context Staff < \context Voice = VA { \voiceOne cis2 b }
+ \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
+ \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
@end lilypond
-When there are more than two voices on a staff, you must also indicate
-which voice should moved horizontally in case of a collision. This can
-be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
-@code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift}
-in @internalsref{NoteColumn}).
+The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
+ties, slurs and stems, and set shift directions.
+If you want more than four voices, you can also manually set
+horizontal shifts and stem directions, as is shown in the following example:
@lilypond[fragment, verbatim]
\context Staff \notes\relative c''<
\context Voice=one {
>
@end lilypond
-The most convenient way is to use the identifiers @code{\voiceOne}
-through @code{\voiceFour}, which also set slur and tie directions in the
-correct manner.
-
-@lilypond[singleline, verbatim]
-\relative c''
-\context Staff < \context Voice = VA { \voiceOne cis2 b }
- \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
- \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
-@end lilypond
Normally, note heads with a different number of dots are not merged, but
if you set the grob property @code{merge-differently-dotted}, they are:
-
@lilypond[verbatim,fragment,singleline]
- \context Staff <
- \context Voice = VA { \voiceOne
+\apply #voicify-music < {
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] }
+ } \\ { [g'8. f16] [g'8. f'16] }
>
@end lilypond
-LilyPond also vertically shifts rests that are opposite of a stem.
+Similarly, you can merge half note heads with eighth notes, by setting
+@code{merge-differently-headed}:
+@lilypond[fragment, relative=2,verbatim]
+\apply #voicify-music < {
+ c8 c4.
+ \property Staff.NoteCollision
+ \override #'merge-differently-headed = ##t
+ c8 c4. } \\ { c2 c2 } >
+@end lilypond
+
+LilyPond also vertically shifts rests that are opposite of a stem.
+
+@lilypond[singleline,fragment,verbatim]
+\apply #voicify-music <
+ { c''4 } \\ { r4 }
+>
+@end lilypond
+
+Note head collisions (horizontal shifting of note heads) are handled by
+the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
+handles vertical shifting of rests.
+
+
+
+@refbugs
+
+Resolving collisions is a very intricate subject, and LilyPond only
+handles a few situations. When it can not cope, you are advised to use
+@code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
+rests to override typesetting decisions.
+
+@node Beaming
+@section Beaming
+
+Beams are used to group short notes into chunks that are aligned with
+the metrum. They are inserted automatically in most cases.
+
+@lilypond[fragment,verbatim, relative=2]
+\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
+@end lilypond
+
+If you're not satisfied with the automatic beaming, you can enter the
+beams explicitly. If you have beaming patterns that differ from the
+defaults, you can also set the patterns for automatic beamer.
+
+The beam symbol is @internalsref{Beam} in @internalsref{Voice}
+context, both for automatically created and manual beams.
+
+@c . {Manual beams}
+@cindex Automatic beams
+@subsection Manual beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
+
+In some cases it may be necessary to override LilyPond's automatic
+beaming algorithm. For example, the auto beamer will not beam over
+rests or bar lines, If you want that, specify the begin and end point
+manually using a @code{[} before the first beamed note and a @code{]}
+after the last note:
+
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ r4 [r8 g' a r8] r8 [g | a] r8
+ }
+@end lilypond
+
+@cindex @code{stemLeftBeamCount}
+
+Normally, beaming patterns within a beam are determined automatically.
+When this mechanism fouls up, the properties
+@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
+be used to control the beam subdivision on a stem. If you set either
+property, 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]
+ }
+@end lilypond
+@cindex @code{stemRightBeamCount}
+
+@ignore
+TODO: FIXME, we don't want this doc here.
+
+ can be tweaked through
+grob-property @code{positions}. The value is a pair.
+specify vertical location of the left and right end point. Both are
+measured in half staff-spaces, and the middle staff line is the value
+of 0.
+
+@li lypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'position = #
+ \property Voice.Beam \set #'height = #0
+ [a'8 e' d c]
+@end lilyp ond
+
+Here's how you'd specify a weird looking beam that instead of being
+horizontal, falls two staff spaces:
+
+
+[FIXME]
+
-@lilypond[singleline,verbatim]
-\context Staff <
-\context Voice { \stemUp c''4 }
-\context Voice =VB { r4 }
->
+@li lypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'staff-position = #4
+ \property Voice.Beam \set #'height = #-4
+ [c8 c]
@end lilypond
-Note head collisions (horizontal shifting of note heads) are handled by
-the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
-handles vertical shifting of rests.
+@end ignore
+Kneed beams are inserted automatically, when a large gap between two
+adjacent beamed notes is detected. This behavior can be tuned through
+the grob property @code{auto-knee-gap}.
+@cindex beams, kneed
+@cindex kneed beams
+@cindex auto-knee-gap
+@cindex hara kiri
+@c TODO -> why this ref? Document?
+@cindex @code{neutral-direction}
+
@refbugs
-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.
+Auto knee beams can not be used together with hara kiri staffs.
-@node Beaming
-@section Beaming
+@menu
+* Beam typography::
+* Setting automatic beam behavior ::
+@end menu
-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.
+@node Beam typography
+@subsection 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.]
@c . {Automatic beams}
-@subsection Automatic beams
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
-@cindex @code{Voice.autoBeamSettings}
+@cindex @code{autoBeamSettings}
@cindex @code{(end * * * *)}
@cindex @code{(begin * * * *)}
-
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
In normal time signatures, automatic beams can start on any note but can
only end in a few positions within the measure: beams can end on a beat,
@cindex automatic beam generation
@cindex autobeam
-@cindex @code{Voice.noAutoBeaming}
+@cindex @code{Voice.autoBeaming}
+@cindex lyrics
+
+For melodies that have lyrics, you may want to switch off
+automatic beaming. This is done by setting @code{Voice.autoBeaming} to
+@code{#f}.
-Automatic beaming is on by default, but can be switched off by setting
-@code{Voice.noAutoBeaming} to true. You you may find this necessary for
-a melody that goes with lyrics.
@refbugs
different parts of a measure. This means that it is not possible to use
automatic beaming in irregular meters such as @code{5/8}.
-@c . {Manual beams}
-@cindex Automatic beams
-@subsection Manual beams
-@cindex beams, manual
-@cindex @code{]}
-@cindex @code{[}
-
-In some cases it may be necessary to override LilyPond's automatic
-beaming algorithm. For example, the auto beamer will not beam over
-rests or bar lines, If you want that, specify the begin and end point
-manually using a @code{[} before the first beamed note and a @code{]}
-after the last note:
-
-@lilypond[fragment,relative,verbatim]
- \context Staff {
- r4 [r8 g' a r8] r8 [g | a] r8
- }
-@end lilypond
-Whenever an manual beam is busy, the automatic beamer will not produce
-anything.
-
-@cindex @code{stemLeftBeamCount}
-
-Normally, beaming patterns within a beam are determined automatically.
-When this mechanism fouls up, the properties
-@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. can
-be used to control the beam subdivision on a stem. If you set either
-property, it's value will be used only once, and then it is erased.
-
-@lilypond[fragment,relative,verbatim]
- \context Staff {
- [f8 r16 f g a]
- [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
- }
-@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.
-
-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
-
-Here's how you'd specify a weird looking beam that instead of being
-horizontal, falls two staff spaces:
-
-
-[FIXME]
-
-
-@lilypond[fragment,relative,verbatim]
- \property Voice.Beam \set #'staff-position = #4
- \property Voice.Beam \set #'height = #-4
- [c8 c]
-@end lilypond
-
-[TODO: doc autokneeing ? ]
-
-@c TODO -> why this ref? Document?
-@cindex @code{neutral-direction}
@node Expressive marks
@section Expressive marks
the attachment type of the left and right end points.
@lilypond[fragment,relative,verbatim]
- \property Voice.Slur \set #'direction = #1
+ \slurUp
\property Voice.Stem \set #'length = #5.5
g'8(g)g4
\property Voice.Slur \set #'attachment = #'(stem . stem)
stems might look better:
@lilypond[fragment,relative,verbatim]
- \property Voice.Stem \set #'direction = #1
- \property Voice.Slur \set #'direction = #1
+ \stemUp \slurUp
d32( d'4 )d8..
\property Voice.Slur \set #'attachment = #'(stem . stem)
d,32( d'4 )d8..
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
+ \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
@refbugs
-@code{beautiful} is an arbitrary parameter in the slur formatter.
-Useful values can only be determined by trial and error.
+Producing nice slurs is a difficult problem, and LilyPond currently
+uses a simple, empiric method to produce slurs. In some cases, the
+results of this method don't look too good. This is reflected by the
+@code{beautiful} parameter. It is an arbitrary parameter in the slur
+formatter. Useful values can only be determined by trial and error.
@cindex Adjusting slurs
@end lilypond
-
-
-@refbugs
-
-The current layout of the default comma style breath marks
-could be improved and more optional symbols should be added to the
-font.
-
-
-
@c . {Tempo}
@node Tempo
@subsection Tempo
@menu
* Articulations::
* Text scripts::
+* Adding scripts::
* Grace notes::
* Glissando ::
* Dynamics::
@cindex ornaments
A variety of symbols can appear above and below notes to indicate
-different characteristics of the performance. These symbols can be
-added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
-are defined in @file{script.ly}. Symbols can be forced to appear above
-or below the note by writing `@var{note}@code{^\}@var{name}' and
-`@var{note}@code{_\}@var{name}' respectively. Here is a chart showing
-symbols on notes, with the name of the corresponding symbol appearing
-underneath.
+different characteristics of the performance. They are added to a note
+by adding @code{-}@var{script}
+@lilypond[singleline]
+ \score {
+ \notes \context Voice {
+ \property Voice.TextScript \set #'font-family = #'typewriter
+ \property Voice.TextScript \set #'font-shape = #'upright
+ c''4-._"c-." s4
+ c''4--_"c-{}-" s4
+ c''4-+_"c-+" s4
+ c''4-|_"c-|" s4
+ c''4->_"c->" s4
+ c''4-^_"c-\\^{ }" s4
+ }
+ }
+@end lilypond
+
+The script is automatically placed, but if you need to force
+directions, you can use @code{_} to force them down, or @code{^} to
+put them up:
+@lilypond[fragment, verbatim]
+ c''4^^ c''4_^
+@end lilypond
+
+Other symbols can be added using the syntax
+@var{note}@code{-\}@var{name}. Again, they can be forced up or down
+using @code{^} and @code{_}.
@lilypond[]
\score {
<
}
@end lilypond
-To save typing work, some shorthands are available:
-@lilypond[singleline]
- \score {
- \notes \context Voice {
- \property Voice.TextScript \set #'font-family = #'typewriter
- \property Voice.TextScript \set #'font-shape = #'upright
- c''4-._"c-." s4
- c''4--_"c-{}-" s4
- c''4-+_"c-+" s4
- c''4-|_"c-|" s4
- c''4->_"c->" s4
- c''4-^_"c-\\^{ }" s4
- }
- }
-@end lilypond
@cindex fingering
-Fingering instructions can also be entered in this shorthand. For
-changes, some markup texts would be needed:
+Fingering instructions can also be entered in this shorthand. For
+finger changes, use markup texts:
+@c
@lilypond[verbatim, singleline, fragment]
c'4-1 c'4-2 c'4-3 c'4-4
c^#'(finger "2-3")
@cindex superscript
@cindex subscript
-You can add scripts by editing @file{scm/script.scm}. This file contains
-a table, listing script definitions and aliases. The following syntax
-accesses a script definition from the table:
-
-@example
- \script @var{alias}
-@end example
-
-Usually the @code{\script} keyword is not used directly. Various
-helpful identifier definitions appear in @file{script.ly}.
-
Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
@refbugs
@code{c^"text"}.
By default, these indications do not influence the note spacing, but
-if @code{Voice.textNonEmpty} is set to true the widths will be taken
-into account. The identifier @code{\fatText} is defined in the standard
-includes.
-@lilypond[fragment,singleline,verbatim]
-\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
+by using the command @code{\fatText}, the widths will be taken into
+account.
+@c
+@lilypond[fragment,singleline,verbatim] \relative c' {
+c4^"longtext" \fatText c4_"longlongtext" c4 }
@end lilypond
Text scripts are created in form of @internalsref{TextScript} grobs, in
-@internalsref{Voice} context.
+@internalsref{Voice} context.
@ref{Text markup} describes how to change the font or access
special symbols in text scripts.
-@c . {Grace notes}
-@node Grace notes
-@subsection Grace notes
+@node Adding scripts
+@subsection Adding scripts
+
+TODO: should junk this subsect?
+
+You can add scripts by editing @file{scm/script.scm} and
+@file{ly/script-init.ly}. This file contains a table, listing script
+definitions and aliases. The following syntax accesses a script
+definition from the table:
+
+@example
+ \script @var{alias}
+@end example
+Usually the @code{\script} keyword is not used directly. Various
+helpful identifier definitions appear in @file{script.ly}.
+@c . {Grace notes}
+@node Grace notes
+@subsection Grace notes
@cindex grace notes
@cindex @code{graceAlignPosition}
+
Grace notes are ornaments that are written out, but do not take up any
logical time in a measure. LilyPond has limited support for grace notes.
The syntax is as follows.
@menu
* Repeat syntax::
+* Repeats and MIDI::
* Manual repeat commands::
* Tremolo repeats::
* Tremolo subdivisions::
}
@end lilypond
-@subsection Unfolding repeats for MIDI output.
+@node Repeats and MIDI
+@subsection Repeats and MIDI
@cindex expanding repeats
-See @file{input/test/unfold-all-repeats.ly}.
+For instructions on how to unfoldi repeats for MIDI output, see
+the example file @file{input/test/unfold-all-repeats.ly}.
@refbugs
Voices can switch automatically between the top and the bottom
staff. The syntax for this is
@example
- \autochange @var{contexttype} @var{musicexp}
+ \autochange @var{contexttype} \context @var{childcontexttype}
+ @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.
+@c
+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}, and
+@internalsref{Voice} for @var{childcontexttype}. 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 <
The associated grob is @internalsref{VoiceFollower}.
+@node Tablatures
+@section Tablatures
+
+@menu
+* Tablatures basic::
+* Non-guitar tablatures::
+* Tablature in addition to normal staff::
+@end menu
+
+@node Tablatures basic
+@subsection Tablatures basic
+@cindex Tablatures basic
+
+Tablature can be typeset with Lilypond by using the
+@internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
+tablatures is a recent feature in Lilypond, most of the guitar special
+effects (hammer, pull, bend, ...) are not yet supported.
+
+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).
+
+@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
+
+
+@node Non-guitar tablatures
+@subsection Non-guitar tablatures
+@cindex Non-guitar tablatures
+
+There are many ways to customize Lilypond tablatures.
+
+First you can change the number of string, e.g.
+@code{StaffSymbol \override #'line-count = #5} to have only 5 strings.
+Because of a kind of bug in Lilypond, you MUST create a new type of
+context if you want different tablatures with diiferent number of
+strings.
+
+Then you can change the strings tuning. String tuning is given as a
+Scheme list with one integer number for each string, the number being
+the string note pitch if not fretted (open note).
+
+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.
+
+
+@node Tablature in addition to normal staff
+@subsection Tablature in addition to normal staff
+@cindex Tablature in addition to normal staff
+
+It is possible to typeset both tablature and a "normal" staff, as
+commonly done in many parts.
+
+A common trick for that is to put the notes in a variables, and to hide
+the fingering information (which correspond to the string number) for
+the standard staff.
+
+@lilypond[fragment,verbatim]
+ part = \notes {
+ a,4-2 c'-5 a-4 e'-6
+ e-3 c'-5 a-4 e'-6
+ }
+ \context StaffGroup <
+ \context Staff <
+ % Hide fingering number (used for string number) for the "normal" staff
+ \property Staff.Fingering \override #'transparent = ##t
+
+ \part
+ >
+ \context TabStaff <
+ \property Staff.Stem \override #'direction = #1
+
+ \part
+ >
+ >
+@end lilypond
+
+
+
@node Lyrics
@section Lyrics
@c . {Custodes}
+@node Ancient notation
+@section Ancient notation
+
+@menu
+* Ancient note heads::
+* Custodes::
+@end menu
+
+
+@node Ancient note heads
+@subsection Ancient note heads
+
+ To get a longa note head, you have to use mensural note heads. This
+is accomplished by setting the @code{style} property of the
+NoteHead grob to @code{mensural}. There is also a note head style
+@code{baroque} which gives mensural note heads for @code{\longa} and
+@code{\breve} but standard note heads for shorter notes.
+
+@lilypond[fragment,singleline,verbatim]
+ \property Voice.NoteHead \set #'style = #'mensural
+ \property Voice.NoteHead \set #'font-family = #'ancient
+ a'\longa
+@end lilypond
+
@node Custodes
-@section Custodes
+@subsection Custodes
+
@cindex Custos
@cindex Custodes
@}
@end example
+@node Ancient clefs
+@section Ancient clefs
+
+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 the following values
+
+@table @code
+@item clefs-C
+ modern style C clef
+@item clefs-F
+ modern style F clef
+@item clefs-G
+ modern style G clef
+@item clefs-vaticana_do
+ Editio Vaticana style do clef
+@item clefs-vaticana_fa
+ Editio Vaticana style fa clef
+@item clefs-medicaea_do
+ Editio Medicaea style do clef
+@item clefs-medicaea_fa
+ Editio Medicaea style fa clef
+@item clefs-mensural1_c
+ modern style mensural C clef
+@item clefs-mensural2_c
+ historic style small mensural C clef
+@item clefs-mensural3_c
+ historic style big mensural C clef
+@item clefs-mensural1_f
+ historic style traditional mensural F clef
+@item clefs-mensural2_f
+ historic style new mensural F clef
+@item clefs-mensural_g
+ historic style mensural G clef
+@item clefs-hufnagel_do
+ historic style hufnagel do clef
+@item clefs-hufnagel_fa
+ historic style hufnagel fa clef
+@item clefs-hufnagel_do_fa
+ historic style hufnagel combined do/fa clef
+@item clefs-percussion
+ modern style percussion clef
+@end table
+
+@emph{Modern style} means ``as is typeset in current editions.''
+@emph{Historic style} means ``as was typeset or written in contemporary
+historic editions''. @emph{Editio XXX style} means ``as is/was printed in
+Editio XXX.''
+
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel clefs
+
+
@c . {Figured bass}
@node Figured bass
@code{\revert} properties that are expected to be set by default,
LilyPond may crash.
+
+@cindex adjusting staff symbol
+@cindex StaffSymbol, using \property
+@cindex staff lines, setting number of
+
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
Context definitions follow precisely the same syntax as within the
\paper block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/performer.ly}.
+The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
@node MIDI instrument names
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.
-
+performance contexts can be found in @file{ly/engraver-init.ly} and
+@file{ly/performer-init.ly}, respectively.
@node Creating contexts
@subsection Creating contexts
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}.
+@code{VoiceContext}, see @file{ly/engraver-init.ly}.
@node Defining new contexts
@subsection Defining new contexts