-
-@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
@c to automagically fill in these menus before saving changes
+@c FIXME: singular vs. plural: Beams/Beam
+
@macro refbugs
@strong{BUGS}
@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}
+@cindex \NAME\
+\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::
* Staff notation::
* Polyphony::
* Repeats::
* Rhythmic music::
* Piano music::
+* Tablatures::
* Lyrics::
* Chords::
* Writing parts::
-* Custodes::
+* Ancient notation ::
+* Ancient clefs ::
+* Figured bass::
* Tuning output::
* Page layout::
* Output formats::
* 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
\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
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 Rests
-Rests are entered like notes, with note name `@code{r}'. The grob is
-@code{Rest}. Whole bar rests centered in the bar are specified using
-@code{R}, see @ref{Multi measure rests}.
+A rest is entered like a note, with note name `@code{r}':
+
+@lilypond[singleline,verbatim]
+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}.
+
+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}
+@c FIXME: naming.
@node Skips
@subsection Skips
@cindex Skip
+@cindex Invisible rest
+@cindex Space note
+An invisible rest, or skip, can be entered like a note with note name
+@code{s}, or with @code{\skip @var{duration}}:
-@example
- \skip @var{duration}
- s@var{duration}
-@end example
-@cindex @code{\skip}
+@lilypond[singleline,verbatim]
+a2 s4 a4 \skip 1 a4
+@end lilypond
+
+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 _
+
+In Lyrics mode, you can use `@code{" "}' and `@code{_}':
+@lilypond[singleline,verbatim]
+<
+ \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
+ \notes\relative c'' { a2 a4 a a2 a4 a }
+>
+@end lilypond
+
+The unabbreviated `@code{\skip} @var{duration}' also works outside of
+note mode:
+
+@lilypond[singleline,verbatim]
+\score {
+ \context Staff <
+ { \time 4/8 \skip 2 \time 4/4 }
+ \notes\relative c'' { a2 a1 }
+ >
+}
+@end lilypond
+
+The skip command is merely a empty musical placeholder. It does not
+produce any output, not even transparent output.
-Skips the amount of time specified by @var{duration}. If no other music
-is played, a gap will be left for the skipped time without any notes
-printed. The shorthand is only available in Note and Chord mode.
@c . {Durations}
@node Durations
@example
\duration @var{scmduration}
@end example
-Here, @var{scmduration} is a Scheme object of type @code{Duration}. See
-@ref{Duration} for more information.
+Here, @var{scmduration} is a Scheme object of type @code{Duration}.
In Note, Chord, and Lyrics mode, durations may be designated by numbers
@lilypond[]
\score {
\notes \relative c'' {
- a\breve \autoBeamOff
+ a\breve \autoBeamOff
a1 a2 a4 a8 a16 a32 a64 a64
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64
}
@end lilypond
- To get a longa note head, you have to use mensural note heads. This
-is accomplished by setting the @code{style} property of the
-NoteHead grob to @code{mensural}. There is also a note head style
-@code{baroque} which gives mensural note heads for @code{\longa} and
-@code{\breve} but standard note heads for shorter notes.
-
-@lilypond[fragment,singleline,verbatim]
- \property Voice.NoteHead \set #'style = #'mensural
- a'\longa
-@end lilypond
If the duration is omitted then it is set to the previous duration
entered. At the start of parsing a quarter note is assumed. The
@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 @code{Voice.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.
-
+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 @code{TupletBracket} grobs
+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.
@lilypond[singleline,verbatim]
\include "paper23.ly"
\score {
- \notes { c'2 e'4 f' | g'1 }
- \paper { \translator { \EasyNotation } }
+ \notes { c'2 e'4 f' | g'1 }
+ \paper { \translator { \EasyNotation } }
}
@end lilypond
-Note that @code{EasyNotation} overrides a @code{Score} context. You
+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}.
This command sets the context property @code{Staff.keySignature}.
Non-standard key signatures can be specified by setting this property
-directly, see the generated documentation for @rgrob{KeySignature}.
+directly.
-The printed signature is a @code{KeySignature} grob.
+The printed signature is a @internalsref{KeySignature} grob, typically
+created in @internalsref{Staff} context.
@cindex @code{keySignature}
@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 @code{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
@end table
By adding @code{_8} or @code{^8} to the clef name, the clef is
-transposed one octave down or up, respectively.
+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
-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 @code{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.
+
+
+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
-@c FIXME: this isn't documented except in example?
-See
-@file{input/test/time.ly} for examples.
+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.
-@code{BarLine} grobs are created by the @code{Bar_engraver}.
-
@c . {Polyphony}
@node Polyphony
@section Polyphony
@cindex polyphony
Polyphonic parts, i.e. parts with more than one voice on a staff can be
-typeset with LilyPond. 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' } >
+typeset with LilyPond.
+
+The easiest way to enter such fragments, is the Scheme function
+@code{voicify-music}. It will split chords using the separator
+@code{\\}, to make multiple voices. You can use it for small,
+short-lived voices (make a chord of voices) or for single chords:
+
+@lilypond[verbatim,fragment]
+\context Voice = VA \apply #voicify-music \relative c'' {
+ c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
+}
@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 @code{NoteColumn}).
+The function @code{voicify-music} instantiates @internalsref{Voice}
+contexts, bearing the names @code{"1"}, @code{"2"}, etc.
+
+To explicity typeset polyphonic music, 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
+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
+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,verbatim]
-\context Staff <
-\context Voice { \stemUp c''4 }
-\context Voice =VB { r4 }
+@lilypond[singleline,fragment,verbatim]
+\apply #voicify-music <
+ { c''4 } \\ { r4 }
>
@end lilypond
Note head collisions (horizontal shifting of note heads) are handled by
-the @code{NoteCollision} grob. @code{RestCollision} handles vertical
-shifting of rests.
+the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
+handles vertical shifting of rests.
-@cindex @code{NoteCollision}
-@cindex @code{RestCollision}
@refbugs
Resolving collisions is a very intricate subject, and LilyPond only
handles a few situations. When it can not cope, you are advised to use
-@code{force-hshift} of the NoteColumn grob and @code{staff-position} of
-the Rest grob to override typesetting decisions.
+@code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
+rests to override typesetting decisions.
@node Beaming
@section Beaming
Beams are used to group short notes into chunks that are aligned with
-the metrum. LilyPond guesses where beams should be inserted. If you're
-not satisfied with the automatic beaming, you can specify which patterns
-to beam automatically. In specific cases, you can also enter the beams
-explicitly.
+the metrum. They are inserted automatically in most cases.
+
+@lilypond[fragment,verbatim, relative=2]
+\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
+@end lilypond
+
+If you're not satisfied with the automatic beaming, you can enter the
+beams explicitly. If you have beaming patterns that differ from the
+defaults, you can also set the patterns for automatic beamer.
+
+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]
+
+
+@li lypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'staff-position = #4
+ \property Voice.Beam \set #'height = #-4
+ [c8 c]
+@end lilypond
+
+@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
+
+Auto knee beams can not be used together with hara kiri staffs.
+
+@menu
+* Beam typography::
+* Setting automatic beam behavior ::
+@end menu
+
+@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
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
-@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}.
-
-@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 @code{Voice.Beam}, 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]
+ \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
-Here's how you'd specify a weird looking beam that instead of being
-horizontal, falls two staff spaces:
+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}.
-@lilypond[fragment,relative,verbatim]
- \property Voice.Beam \set #'staff-position = #4
- \property Voice.Beam \set #'height = #-4
- [c8 c]
-@end lilypond
-@cindex @code{default-neutral-direction}
@node Expressive marks
@section Expressive marks
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
-@code{Voice.Slur}'s grob-property @code{attachment}. It's value is a
-pair of symbols, specifying the attachment type of the left and right end points.
+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]
- \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..
Similarly, the curvature of a slur is adjusted to stay clear of note
heads and stems. When that would increase the curvature too much, the
slur is reverted to its default shape. The threshold for this decision
-is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely
+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
+ \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
Typographically, the phrasing slur behaves almost exactly like a normal
-slur. The grob associated with it is @code{Voice.PhrasingSlur}.
+slur. The grob associated with it is @internalsref{PhrasingSlur}, in
+@internalsref{Voice} context.
@node Breath marks
@subsection Breath marks
Breath marks are entered using @code{\breathe}. The result is a
-@code{Voice.BreathingSign} grob.
+@internalsref{BreathingSign} grob in @internalsref{Voice} context.
@lilypond[fragment,relative]
c'4 \breathe d4
@end lilypond
-
-
-@refbugs
-
- Currently, only tick marks are supported, not comma style breath marks.
-
-
@c . {Tempo}
@node Tempo
@subsection Tempo
\spanrequest \start "text"
\spanrequest \stop "text"
@end example
-LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The
-string to be printed, as well as the style is set through grob
-properties.
+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]
@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.
+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
@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 @code{Script} and @code{Fingering}.
+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 @code{Voice.TextScript} grobs.
+Text scripts are created in form of @internalsref{TextScript} grobs, in
+@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.
stem.
@lilypond[fragment,verbatim]
-\relative c'' {
+\relative c'' \context Voice {
\grace c8 c4 \grace { [c16 c16] } c4
\grace {
\property Voice.Stem \override #'flag-style = #'()
@cindex @code{\glissando}
-A glissando line (grob @code{Voice.Glissando}) can be requested by attaching a
-@code{\glissando} to a note:
+A glissando line (grob @internalsref{Glissando}) can be requested by
+attaching a @code{\glissando} to a notte:
@lilypond[fragment,relative,verbatim]
c'-\glissando c'
@cindex diminuendo
-Dynamics are grobs of @code{Voice.DynamicText} and
-@code{Voice.Hairpin}. They are put together on
-@code{Voice.DynamicLineSpanner} to align them vertically.
+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
@menu
* Repeat syntax::
+* Repeats and MIDI::
* Manual repeat commands::
* Tremolo repeats::
* Tremolo subdivisions::
}
@end lilypond
+@node Repeats and MIDI
+@subsection Repeats and MIDI
+
+@cindex expanding repeats
+
+For instructions on how to unfoldi repeats for MIDI output, see
+the example file @file{input/test/unfold-all-repeats.ly}.
+
+
@refbugs
Notice that timing information is not remembered at the start of an
@end lilypond
-Repeats brackets are @code{Staff.VoltaBracket} grobs.
+Repeats brackets are @internalsref{VoltaBracket} grobs.
@node Tremolo repeats
@subsection Tremolo repeats
}
@end lilypond
-Tremolo beams are @code{Voice.Beam} grobs. Single stem tremolos are
-@code{Voice.StemTremolo}.
+Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
+@internalsref{StemTremolo}.
@refbugs
\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
-The signs are represented by these grobs: @code{Voice.RepeatSlash} and
-@code{Voice.PercentRepeat} and @code{Voice.DoublePercentRepeat}.
+The signs are represented by these grobs: @internalsref{RepeatSlash} and
+@internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
@refbugs
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
-@code{PianoStaff} is especially built to handle this cross-staffing
-behavior. In this section we discuss the @code{PianoStaff} and some
+@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
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
-@code{Staff} for @var{contexttype}. The autochanger switches on basis
-of pitch (central C is the turning point), and it looks ahead skipping
-over rests to switch rests in advance.
+@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 <
@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
These identifiers are shorthands for spanner commands of the types
-@code{Sustain}, @code{UnaCorda} and @code{Sostenuto}:
+@internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
@lilypond[fragment,verbatim]
c''4 \spanrequest \start "Sustain" c''4
@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.
+@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.
-@refbugs
+Pedals can also be indicated by a sequence of brackets, by setting the
+@code{pedal-type} property of SustainPedal grobs:
+
+@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
+
+A third style of pedal notation is a mixture of text and brackets,
+obtained by setting @code{pedal-type} to @code{mixed}:
+
+@lilypond[fragment,verbatim]
+\property Staff.SustainPedal \override #'pedal-type = #'mixed
+c''4 \sustainDown d''4 e''4 c'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
+@end lilypond
+
+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:
+
+@lilypond[fragment,verbatim]
+c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
+@end lilypond
+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.
+
+@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
-Currently, brackets are not supported, only text markings (i.e. `*Ped'
-style).
@c . {Arpeggio}
>
@end lilypond
-This command creates @code{Voice.Arpeggio} grobs. Cross staff arpeggios
+This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
are @code{PianoStaff.Arpeggio}.
+To add an arrow head to explicitly specify the direction of the
+arpeggio, you should set the arpeggio grob property
+@code{arpeggio-type}.
+
+@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>
+ }
+@end lilypond
+
+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.
+
+@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
+
+
@refbugs
It is not possible to mix connected arpeggios and unconnected arpeggios
>
@end lilypond
-The associated grob is @code{Voice.VoiceFollower}.
+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
@subsection Printing lyrics
@cindex lyrics
-Lyrics are printed by interpreting them in the @code{Lyrics} context.
+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; }
+\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 slurs to be interpreted as melismata.
+the melody staff will cause tied, slurred or beamed notes to be
+interpreted as melismata.
The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
@cindex printing chord names
@cindex chord names
@cindex chords
-@cindex @code{ChordNames}
-
-For displaying printed chord names, use the @code{ChordNames} context.
+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.
@cindex Rehearsal marks
@cindex mark
@cindex @code{\mark}
-@cindex @code{Mark_engraver}
+
@example
\mark @var{unsigned}
}
@end lilypond
-The grob is @code{Score.RehearsalMark}. See
+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
-Bar numbers (grob: @code{BarNumber}) are printed at the start of the
-line. See @code{input/test/boxed-molecule.ly} for boxed 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
@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
not disappear when it contains normal rests, you must use multi measure
rests.
-The hara kiri staff is specialized version of the Staff context. It is
-available as the context identifier @code{\HaraKiriStaffContext}.
-Observe how the second staff in this example disappears in the second
-line.
+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 {
@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
the 20th century.
For typesetting custodes, just put a @code{Custos_engraver} into the
-@code{StaffContext} when declaring the @code{\paper} block. In this
+@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
@}
@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
+@section Figured bass
+
+@cindex Basso continuo
+
+TODO. see figured-bass.ly
+
@c . {Tuning output}
@node Tuning output
@section Tuning output
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
-@code{Stem}
+@internalsref{Stem}
@example
(thickness . 0.8)
@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
@code{cmti}, etc. Setting this overrides font-family, font-shape and
font-series.
+
@end table
+
The font is selected by taking the first font that satisfies all
qualifiers specified. You can override any of these fields through
@code{\override} and @code{\revert}. The special value @code{*} matches
The style sheets and tables for selecting fonts are located in
@file{scm/font.scm}. Refer to this file for more information.
+
+Setting @code{font-name} overrides all other qualifiers. The value for
+this property should be a string, the file name of the font. You may use
+this to use special fonts, which are not a part of the style sheet, or
+which have special encodings.
+
+The size of the font may be set with the grob property
+@code{font-magnification}. It is the size of font, relative to its
+standard size. For example, @code{1.0} is normal size.
+
@refbugs
Relative size is not linked to any real size.
-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}.
-
There is no style sheet provided for other fonts besides the @TeX{}
family.
@c . {Font size}
@node Font Size
@subsection Font size
-@cindex font size
+@cindex font size, setting
+@cindex staff size, setting
+@cindex @code{paper} file
The Feta font provides musical symbols at six different sizes. These
-fonts are 11 point, 13 point, 16 point, 20 point,
-23 point, and 26 point. The point size of a font is the
-height of the five lines in a staff when displayed in the font.
+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.
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.
+@code{\paper} block is also set. These files should be imported at toplevel, i.e.
+@example
+ \include "paper26.ly"
+ \score @{ ... @}
+@end example
The font definitions are generated using a Scheme function. For more
details, see the file @file{scm/font.scm}.
@cindex @code{papersize}
To change the paper size, you must first set the
-@code{papersize} variable at top level. Set it to
+@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
- papersize = "a4"
+ \paper@{ papersize = "a4" @}
\include "paper16.ly"
@end example
The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
will set the paper variables @code{hsize} and @code{vsize} (used by
-@code{ly2dvi})
+Lilypond and @code{ly2dvi})
@c . {Line break}
@node Line break
@cindex breaking lines
Line breaks are normally computed automatically. They are chosen such
-that the resulting spacing has low variation, and looks neither cramped
-nor loose.
+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
bar line, you can force an invisible bar line by entering @code{\bar
""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
+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.
+
+
@cindex @code{\penalty}
The @code{\break} and @code{\noBreak} commands are defined in terms of
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
-
+@c FIXME: Note entry vs Music entry at top level menu is confusing.
@c . {Music entry}
@node Music entry
@section Music entry
\time 3/4 c2 e4 | g2.
@end example
+
+
+@cindex skipTypesetting
+
+Failed bar checks are most often caused by entering incorrect
+durations. Incorrect durations often completely garble up the score,
+especially if it is polyphonic, so you should start correcting the score
+by scanning for failed bar checks and incorrect durations. To speed up
+this process, you can use @code{skipTypesetting} (See @ref{Skipping
+corrected music})). Bar
+
+
@c . {Point and click}
@node Point and click
@subsection Point and click
the measure, etc.?
@end itemize
-Contexts are grouped hierarchically: A @code{Voice} context is
-contained in a @code{Staff} context (because a staff can contain
-multiple voices at any point), a @code{Staff} context is contained in
-@code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context.
+Contexts are grouped hierarchically: A @internalsref{Voice} context is
+contained in a @internalsref{Staff} context (because a staff can contain
+multiple voices at any point), a @internalsref{Staff} context is contained in
+@internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
Contexts associated with sheet music output are called @emph{notation
contexts}, those for sound output are called @emph{performance
contexts}. The default definitions of the standard notation and
-performance contexts can be found in @file{ly/engraver.ly} and
-@file{ly/performer.ly}, respectively.
-
+performance contexts can be found in @file{ly/engraver-init.ly} and
+@file{ly/performer-init.ly}, respectively.
@node Creating contexts
@subsection Creating contexts
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
Properties that are set in one context are inherited by all of the
contained contexts. This means that a property valid for the
-@code{Voice} context can be set in the @code{Score} context (for
-example) and thus take effect in all @code{Voice} contexts.
+@internalsref{Voice} context can be set in the @internalsref{Score} context (for
+example) and thus take effect in all @internalsref{Voice} contexts.
Properties can be unset using the following expression:
@example
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
@item @code{\name} @var{contextname}
- This sets the type name of the context, e.g. @code{Staff},
- @code{Voice}. If the name is not specified, the translator won't do
+ 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
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})
-
+@item Font_metric: object representing a font.
@end itemize
-
-@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 broken with emacs-21
+@c {Local emac s vars}
+@c Local varia bles:
+@c mode: texi nfo
+@c minor-mod e: font-lock
+@c minor-mo de: outline
+@c outline -layout: (-1 : 0)
+@c outlin e-use-mode-specific-leader: "@c \."
+@c outli ne-primary-bullet: "{"
+@c outli ne-stylish-prefixes: nil
+@c outli ne-override-protect: t
@c End:
projects / lilypond.git / blobdiff