@macro refbugs
@strong{BUGS}
-
@end macro
@section Note entry
@cindex Note entry
-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.
+Notes constitute the most basic form of music, but they do not form
+valid input on their own. Yet for the sake of brevity and simplicity,
+we'll generally omit @code{\score} blocks and @code{\paper} declarations.
@menu
LilyPond has predefined sets of note names for various other languages.
To use them, simply include the language specific init file. For
example: @code{\include "english.ly"}. The available language files and
-the names they define are:
+the note names they define are:
@example
Note Names sharp flat
@node Chromatic alterations
@subsection Chromatic alterations
-Normally, accidentals are printed automatically, but you may force
-accidentals in the following ways: A reminder accidental
+Normally, accidentals are automatically printed, but you may force
+them 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
question mark `@code{?}' after the pitch.
The automatic production of accidentals can be tuned in many
-ways. Refer to @ref{Accidentals} for more information.
+ways. For more information, refer to @ref{Accidentals}.
@c . {Rests}
@node Rests
@subsection Rests
@cindex Rests
-A rest is entered like a note, with note name `@code{r}':
+Rests are entered like notes, with an `@code{r}' note name:
@lilypond[singleline,verbatim]
r1 r2 r4 r8
@end lilypond
-Whole bar rests centered in the bar are specified using @code{R}, see
+Whole bar rests, centered in the bar, are specified using @code{R}, see
@ref{Multi measure rests}. See also @seeinternals{Rest}.
-For polyphonic music, it can be convenient to specify the rest position
-directly. You can do that by entering a note, with the keyword
-@code{\rest} appended, e.g. Rest collisions will leave these rests alone.
+For polyphonic music, it can be convenient to explicitly specify the rest's
+vertical position. This can be achieved by entering a note, with the @code{\rest}
+keyword appended. Rest collision testing will leave these rests alone.
@lilypond[singleline,verbatim]
a'4\rest d'4\rest
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 _
+@c FIXME: in Lyrics mode, we have " " and _
-In Lyrics mode, you can use `@code{" "}' and `@code{_}':
+In Lyrics mode, invisible rests are entered using either `@code{" "}'
+or `@code{_}':
@lilypond[singleline,verbatim]
<
\context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
>
@end lilypond
-The unabbreviated `@code{\skip} @var{duration}' also works outside of
-note mode:
+Note that the @code{s} syntax is only available in Note mode and Chord
+mode. In other situations, you should use the @code{\skip} command, which
+also works outside of those two modes:
@lilypond[singleline,verbatim]
\score {
}
@end lilypond
-The skip command is merely a empty musical placeholder. It does not
+The skip command is merely an empty musical placeholder. It doesn't
produce any output, not even transparent output.
+
@c . {Durations}
@node Durations
@subsection Durations
@cindex @code{\duration}
-In Note, Chord, and Lyrics mode, durations may be designated by numbers
+In Note, Chord, and Lyrics mode, durations are designated by numbers
and dots: durations are entered as their reciprocal values. For notes
longer than a whole you must use identifiers.
@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
-duration can be followed by dots (`@code{.}') to obtain dotted note
-lengths.
+If the duration is omitted then it is set to the previously entered
+duration. At the start of parsing, a quarter note is assumed. The
+duration can be followed by dots (`@code{.}') in order to obtain dotted
+note lengths:
@cindex @code{.}
@lilypond[fragment,verbatim,center]
@cindex @code{r}
@cindex @code{s}
-You can alter the length of duration by a fraction @var{N/M} by
+You can alter the length of duration by a fraction @var{N/M}
appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
-will not affect the appearance of the notes or rests produced.
+won't affect the appearance of the notes or rests produced.
Durations can also be produced through GUILE extension mechanism.
@lilypond[verbatim,fragment]
@cindex @code{~}
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{~}.
+effect extends the length of a note. Ties should not be confused with
+slurs, which indicate articulation, and phrasing slurs, which indicate
+musical phrasing. A tie is entered using the tilde symbol `@code{~}'.
@lilypond[fragment,verbatim,center]
e' ~ e' <c' e' g'> ~ <c' e' g'>
@end lilypond
-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.
+When a tie is applied to a chord, all note heads, whose pitches match, are
+connected. If you try to tie together chords that have no common pitches,
+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
+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
@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.
+And if you need to tie notes over bars, it may be easier to use
+@ref{Automatic note splitting}.
See also @seeinternals{Tie}.
@refbugs
At present, the tie is represented as a separate event, temporally
-located in between the notes. Tieing only a subset of the note heads
+located in between the notes. Tying only a subset of the note heads
of a chord is not supported in a simple way. It can be achieved by
moving the tie-engraver into the Thread context and turning on and off
ties per Thread.
-Switching staffs when a tie is active will not work.
+Switching staves when a tie is active will not work.
@node Automatic note splitting
@subsection Automatic note splitting
@c FIXME: This subsection doesn't belong in @ref{Note entry}.
-There is a facility for automatically converting long notes to tied
+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}.
@cindex triplets
@cindex @code{\times}
-Tuplets are made out of a music expression by multiplying all duration
+Tuplets are made out of a music expression by multiplying all durations
with a fraction.
@cindex @code{\times}
@itemize @bullet
@item
-@uref{http://denemo.sourceforge.net/, Denemo} was once intended as
+Denemo was once intended as
a LilyPond graphical user interface. It run on Gnome/GTK.
+
+@quotation
+@uref{http://denemo.sourceforge.net/}
+@end quotation
+
@item
-@uref{http://rnvs.informatik.tu-chemnitz.de/~jan/noteedit/noteedit.html, Noteedit}
- is a graphical score editor that runs under KDE/Qt.
+ Noteedit, a graphical score editor that runs under KDE/Qt.
+@quotation
+@uref{http://rnvs.informatik.tu-chemnitz.de/~jan/noteedit/noteedit.html,}
+@end quotation
+
@item
-@uref{http://rosegarden.sf.net/, RoseGarden}
- was the inspiration for naming LilyPond. Nowadays it has been
-rewritten from scratch and supports LilyPond export as of version
-0.1.6.
+RoseGarden was once the inspiration for naming LilyPond. Nowadays it
+has been rewritten from scratch and supports LilyPond export as of
+version 0.1.6.
+
+@quotation
+@uref{http://rosegarden.sf.net/}
+@end quotation
@end itemize
Another option is to enter the music using your favorite MIDI
sequencer, and then import it using midi2ly. midi2ly is described in
@ref{Invoking midi2ly}.
+
@c . {Relative}
@node Relative octaves
@subsection Relative octaves
a few versions behind the official Xdvi. To find out which xdvi you
are running, try @code{xdvi -version} or @code{xdvi.bin -version}.
@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
-newer. Enablle the menu Settings -> Inverse search.
+newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
+
+@cindex Xdvi
+@cindex KDVI
+@cindex KDE
+
+
+
@end itemize
-@item An editor with a client/server interface (or a lightweight GUI editor).
+@item An editor with a client/server interface (or a lightweight GUI
+editor).
+
+@cindex editor
+
@itemize @bullet
@item Emacs. Emacs is an extensible text-editor. It is available from
@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
column location.
+
+@c move this elsewhere?
+
+LilyPond also comes with support files for emacs: lilypond-mode for
+emacs provides indentation, syntax coloring and handy compile
+short-cuts. If lilypond-mode is not installed on your platform, then
+refer to the installation instructions for more information
+
+@cindex emacs
+@cindex emacs mode
+@cindex lilypond-mode for emacs
+@cindex syntax coloring
+
@item XEmacs. Xemacs is very similar to emacs.
+
+@cindex XEmacs
+
@item NEdit. NEdit runs under Windows, and Unix.
It is available from @uref{http://www.nedit.org}.
+
+@cindex NEdit
+
@item GVim. GVim is a GUI variant of VIM, the popular VI
clone. It is available from @uref{http://www.vim.org}.
+
+@cindex GVim
+@cindex Vim
+
@end itemize
@end itemize
To use point-and-click, add one of these lines to the top of your .ly
file.
@example
-#(set! point-and-click line-location)
+#(set-point-and-click! 'line)
@end example
@cindex line-location
of the @code{ly} file, replace the @code{set!} line with the following
line,
@example
-#(set! point-and-click line-column-location)
+#(set-point-and-click! 'line-column)
@end example
@cindex line-colomn-location
and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}.
The lines of the staff symbol are formed by the
-@internalsref{StaffSymbol} grob. This grob is created at the moment
+@internalsref{StaffSymbol} object. This object is created at the moment
that their context is created. You can not change the appearance of
the staff symbol by using @code{\override} or @code{\set}. At the
moment that @code{\property Staff} is interpreted, a Staff context is
Non-standard key signatures can be specified by setting this property
directly.
-The printed signature is a @internalsref{KeySignature} grob, typically
+The printed signature is a @internalsref{KeySignature} object, typically
created in @internalsref{Staff} context.
@cindex @code{keySignature}
\clef "G_8"
@end example
-The grob for this symbol is @internalsref{Clef}.
+The object for this symbol is @internalsref{Clef}.
This command is equivalent to setting @code{clefGlyph},
2/2 time.
-The grob for this symbol is @internalsref{TimeSignature}. There are
+The object 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
+@code{style} object property. See @file{input/test/time.ly} for more
examples.
This command sets the property @code{timeSignatureFraction},
-@code{beatLength} and @code{measureLength}. The property
+@code{beatLength} and @code{measureLength} in the @code{Timing}
+context, which is normally aliased to @internalsref{Score}. The property
@code{timeSignatureFraction} determine where bar lines should be
inserted, and how automatic beams should be generated. Changing the
value of @code{timeSignatureFraction} also causes a time signature
@end example
This is internally translated into
@example
- \property Score.measurePosition = -@var{length of duration}
+ \property Timing.measurePosition = -@var{length of duration}
@end example
@cindex @code{|}
The property @code{measurePosition} contains a rational number
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
+In scores with many staves, the barlines are automatically placed at
+top level, and they are connected between different staves of a
@internalsref{StaffGroup}:
@lilypond[fragment, verbatim]
< \context StaffGroup <
\context Staff = pedal { \clef bass c2 c2 } >
@end lilypond
-The grobs that are created at @internalsref{Staff} level. The name is
+The objects that are created at @internalsref{Staff} level. The name is
@internalsref{BarLine}.
The command @code{\bar @var{bartype}} is a short cut for
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:
+if you set the object property @code{merge-differently-dotted}, they are:
@lilypond[verbatim,fragment,singleline]
\context Voice < {
g'8 g'8
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
+@code{force-hshift} of the @internalsref{NoteColumn} object and pitched
rests to override typesetting decisions.
@node Beaming
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}.
+the object property @code{auto-knee-gap}.
@cindex beams, kneed
@cindex kneed beams
@refbugs
-Auto knee beams can not be used together with hara kiri staffs.
+Auto knee beams can not be used together with hara kiri staves.
[TODO from bugs]
It is not possible to specify beaming parameters for beams with mixed
durations, that differ from the beaming parameters of all separate
durations, i.e., you'll have to specify manual beams to get:
-@lilypond[fragment,singleline,relative]
+
+@lilypond[singleline,fragment,relative,noverbatim]
\property Voice.autoBeamSettings
\override #'(end * * * *) = #(make-moment 3 8)
\time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
@end lilypond
-
It is not possible to specify beaming parameters that act differently in
different parts of a measure. This means that it is not possible to use
automatic beaming in irregular meters such as @code{5/8}.
Slurs avoid crossing stems, and are generally attached to note heads.
However, in some situations with beams, slurs may be attached to stem
ends. If you want to override this layout you can do this through the
-grob-property @code{attachment} of @internalsref{Slur} in
+object 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.
Similarly, the curvature of a slur is adjusted to stay clear of note
heads and stems. When that would increase the curvature too much, the
slur is reverted to its default shape. The threshold for this
-decision is in @internalsref{Slur}'s grob-property @code{beautiful}.
+decision is in @internalsref{Slur}'s object 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
@end lilypond
Typographically, the phrasing slur behaves almost exactly like a normal
-slur. See also @seeinternals{PhrasingSlur}.
+slur. See also @seeinternals{PhrasingSlur}. But although they behave
+similarily to normal slurs, phrasing slurs count as different objects.
+A @code{\slurUp} will have no effect on a phrasing slur; instead, you
+should use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
+@code{\phrasingSlurBoth}.
+Note that the commands
+@code{\slurUp}, @code{\slurDown}, and @code{\slurBoth} will only affect
+normal slurs and not phrasing slurs.
@node Breath marks
@subsection Breath marks
\spanrequest \start "text"
\spanrequest \stop "text"
@end example
-LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
+LilyPond will respond by creating a @internalsref{TextSpanner} object (typically
in @internalsref{Voice} context). The string to be printed, as well as the
-style is set through grob properties.
+style is set through object properties.
An application---or rather, a hack---is to fake octavation indications.
@lilypond[fragment,relative,verbatim]
c''4-|_"c-|" s4
c''4->_"c->" s4
c''4-^_"c-\\^{ }" s4
+ c''4-__"c-\_" s4
}
}
@end lilypond
@cindex staccatissimo
@cindex fermata
@cindex stopped
-@cindex staccato
+@cindex staccato
+@cindex portato
@cindex tenuto
@cindex upbow
@cindex downbow
\property Score.LyricText \override #'font-shape = #'upright
\context Staff \notes {
c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
- c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
+ c''-\stopped c''-\staccato c''-\tenuto c''-\portato
+ c''-\upbow
c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
c''-\rtoe c''-\turn c''-\open c''-\flageolet
c''-\reverseturn c''-\trill c''-\prall c''-\mordent
}
\context Lyrics \lyrics {
accent__ marcato__ staccatissimo__ fermata
- stopped__ staccato__ tenuto__ upbow
+ stopped__ staccato__ tenuto__ portato
+ upbow
downbow__ lheel__ rheel__ ltoe
rtoe__ turn__ open__ flageolet
reverseturn__ trill__ prall__ mordent
commands won't work with direct PostScript output.
@c (see @ref{PostScript output}).
-Text scripts are created in form of @internalsref{TextScript} grobs, in
+Text scripts are created in form of @internalsref{TextScript} objects, in
@internalsref{Voice} context.
@ref{Text markup} describes how to change the font or access
@cindex ornaments
@cindex grace notes
-Grace notes are ornaments are written out ornaments
-@lilypond[relative=2,verbatim,ifragment]
- c4 \grace c16 c4 \grace { [c16 d16] } c4
+Grace notes are ornaments that are written out
+@lilypond[relative=2,verbatim,ifragment] c4 \grace c16 c4 \grace {
+[c16 d16] } c4
@end lilypond
In normal notation, grace notes are supposed to take up no logical
@end lilypond
The placement of these grace notes is synchronized between different
-staffs, using this grace timing.
+staves, using this grace timing.
@lilypond[relative=2,verbatim,fragment]
< \context Staff = SA { e4 \grace { c16 d e f } e4 }
Unbeamed eighth notes and shorter by default have a slash through the
-stem. This can be controlled with grob property @code{flag-style} of
+stem. This can be controlled with object property @code{stroke-style} of
@internalsref{Stem}. The change in formatting is accomplished by
inserting @code{\startGraceMusic} before handling the grace notes, and
@code{\stopGraceMusic} after finishing the grace notes. You can add to
these definitions to globally change grace note formatting. The
standard definitions are in @file{ly/grace-init.ly}.
+Notice how the @code{\override} is carefully matched with a @code{\revert}.
+
+@cindex slash
+@cindex grace slash
@lilypond[fragment,verbatim]
\relative c'' \context Voice {
\grace c8 c4 \grace { [c16 c16] } c4
\grace {
- \property Voice.Stem \override #'flag-style = #'()
+ \property Voice.Stem \override #'stroke-style = #'()
c16
- \property Voice.Stem \revert #'flag-style
+ \property Voice.Stem \revert #'stroke-style
} c4
}
@end lilypond
+
+
If you want to end a note with a grace note, then the standard trick
is to put the grace notes before a phantom ``space note'', e.g.
@lilypond[fragment,verbatim, relative=2]
}
@end lilypond
+A @code{\grace} section has some default values, and LilyPond will
+use those default values unless you specify otherwise inside the
+@code{\grace} section. For example, if you specify \slurUp
+@emph{before} your @code{\grace} section, a slur which starts inside
+the @code{\grace} won't be forced up, even if the slur ends outside
+of the @code{\grace}. Note the difference between the first and
+second bars in this example:
+
+@lilypond[fragment,verbatim]
+\relative c'' \context Voice {
+ \slurUp
+ \grace {
+ a4 ( }
+ ) a4 a4 () a2
+ \slurBoth
+
+ \grace {
+ \slurUp
+ a4 ( }
+ ) a4 a4 () a2
+ \slurBoth
+
+}
+@end lilypond
+
@refbugs
+Grace notes can not be used in the smallest size (@file{paper11.ly}).
+
Grace note synchronization can also lead to surprises. Staff notation,
such as key signatures, barlines, etc. are also synchronized. Take
-care when you mix staffs with grace notes and staffs without.
+care when you mix staves with grace notes and staves without.
@lilypond[relative=2,verbatim,fragment]
< \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
grace section is not supported, and might produce crashes or other
errors.
-@menu
-* Glissando ::
-* Dynamics::
-@end menu
-
-
-@c . {Glissando}
@node Glissando
@subsection Glissando
@cindex Glissando
@cindex diminuendo
-Dynamics are grobs of @internalsref{DynamicText} and
+Dynamics are objects of @internalsref{DynamicText} and
@internalsref{Hairpin}. Vertical positioning of these symbols is
-handled by the @internalsref{DynamicLineSpanner} grob. If you want to
+handled by the @internalsref{DynamicLineSpanner} object. If you want to
adjust padding or vertical direction of the dynamics, you must set
-properties for the @internalsref{DynamicLineSpanner} grob. Predefined
+properties for the @internalsref{DynamicLineSpanner} object. Predefined
identifiers to set the vertical direction are \dynamicUp and
\dynamicDown.
@item 'end-repeat
Print a :| bar line
@item (volta . @var{text})
- Print a volta bracket saying @var{text}.
+ Print a volta bracket saying @var{text}.
@item (volta . #f)
- Stop a running volta bracket
+ Stop a running volta bracket
@end table
@lilypond[verbatim, fragment]
@end lilypond
-Repeats brackets are @internalsref{VoltaBracket} grobs.
+Repeats brackets are @internalsref{VoltaBracket} objects.
@node Tremolo repeats
@subsection Tremolo repeats
}
@end lilypond
-Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
+Tremolo beams are @internalsref{Beam} objects. Single stem tremolos are
@internalsref{StemTremolo}. The single stem tremolo @emph{must} be
entered without @code{@{} and @code{@}}.
}
@end lilypond
-The signs are represented by these grobs: @internalsref{RepeatSlash} and
+The signs are represented by these objects: @internalsref{RepeatSlash} and
@internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
@refbugs
@rgrob{SustainPedal}, for example, for more information.
Pedals can also be indicated by a sequence of brackets, by setting the
-@code{pedal-type} property of SustainPedal grobs:
+@code{pedal-type} property of SustainPedal objects:
@lilypond[fragment,verbatim]
\property Staff.SustainPedal \override #'pedal-type = #'bracket
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
+@code{PianoPedalBracket} objects (see the detailed documentation of
@rgrob{PianoPedalBracket}) can be modified. For example, the bracket
may be extended to the end of the note head.
>
@end lilypond
-This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
+This command creates @internalsref{Arpeggio} objects. 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
+arpeggio, you should set the arpeggio object property
@code{arpeggio-direction}.
@lilypond[fragment,relative,verbatim]
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{PianoStaff.Arpeggio} objects to @code{\arpeggioBracket}, and use
@code{\arpeggio} statements within the chords as before.
@lilypond[fragment,relative,verbatim]
>
@end lilypond
-The associated grob is @internalsref{VoiceFollower}.
+The associated object is @internalsref{VoiceFollower}.
@node Tablatures
@section Tablatures
-Tablature notation is used music for plucked string instruments. It
-notates pitches not by using note heads, but by indicating on which
-string and fret a note must be played. LilyPond offers limited
-support for tablature, by abusing the fingering system.
+Tablature notation is used for notating music for plucked string
+instruments. It notates pitches not by using note heads, but by
+indicating on which string and fret a note must be played. LilyPond
+offers limited support for tablature.
@menu
* Tablatures basic::
Tablature can be typeset with Lilypond by using the
@internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
tablature is a recent feature in Lilypond, most of the guitar special
-effects such as hammer, pull, bend are not yet supported.
+effects such as 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
+is given as a backslash followed by the string number, e.g. @code{c4\3} for a C
+quarter on the third string. By default, string 1 is the highest 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
+ a,4\5 c'\2 a\3 e'\1
+ e\4 c'\2 a\3 e'\1
}
>
@end lilypond
+If you do not specify a string number then lilypond automatically selects one.
+The selection is controlled by the translator property @code{minimumFret}. -- LilyPond
+simply selects the first string that does not give a fret number less than
+@code{minimumFret}. Default is 0.
+
+Notice that LilyPond does not handle chords in any special way, and hence
+the automatic string selector may easily select the same string to two notes in a chord.
+
+@example
+e8 fis gis a b cis' dis' e'
+\property TabStaff.minimumFret = #8
+e8 fis gis a b cis' dis' e'
+@end example
+@lilypond
+frag = \notes {
+ \key e \major
+ e8 fis gis a b cis' dis' e'
+ \property TabStaff.minimumFret = #8
+ e8 fis gis a b cis' dis' e'
+}
+\score {
+ \context StaffGroup <
+ \context Staff { \clef "G_8" \frag }
+ \context TabStaff { \frag }
+ >
+}
+@end lilypond
@node Non-guitar tablatures
@subsection Non-guitar tablatures
There are many ways to customize Lilypond tablatures.
First you can change the number of strings, by setting the number of
-lines in the @internalsref{TabStaff}. You can change the strings
+lines in the @internalsref{TabStaff} (the @code{line-count} property
+of TabStaff can only be changed using @code{\outputproperty}, for more
+information, see @ref{Tuning per object}. You can change the strings
tuning. A string tuning is given as a Scheme list with one integer
number for each string, the number being the pitch of an open string.
+(The numbers specified for stringTuning are the numbers of semitons
+to subtract --- or add --- starting the specified pitch by default
+middle C, in string order: thus the notes are e, a, d & g)
+
+@lilypond[fragment,verbatim]
+ \context TabStaff <
+
+ \outputproperty #(make-type-checker 'staff-symbol-interface)
+ #'line-count = #4
+ \property TabStaff.stringTunings = #'(-5 -10 -15 -20)
+
+ \notes {
+ a,4 c' a e' e c' a e'
+ }
+
+ >
+@end lilypond
+
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
the fingering information (which correspond to the string number) for
the standard staff.
-@lilypond[verbatim]
- part = \notes {
+@c FIXME
+@c @lily pond[verbatim]
+@example
+ part = \notes @{
a,4-2 c'-5 a-4 e'-6
e-3 c'-5 a-4 e'-6
- }
- \score{
+ @}
+ \score @{
\context StaffGroup <
\context Staff <
% Hide fingering number
\part
>
>
- }
-@end lilypond
-
+ @}
+@end example
+@c @end lilypond
@c . {Chords}
@node Chords
By default, a chord name system proposed by Harald Banter (See
@ref{Literature}) is used. The system is very regular and predictable.
Typical American style chord names may be selected by setting the
-@code{style} property of the @code{ChordNames.ChordName} grob to
+@code{style} property of the @code{ChordNames.ChordName} object to
@code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
Routines that determine the names to be printed are written in Scheme,
As you can see, the mark is incremented automatically if you use
@code{\mark \default}. The value to use is stored in the property
-@code{rehearsalMark} is used and automatically incremented. The grob
+@code{rehearsalMark} is used and automatically incremented. The object
is @internalsref{RehearsalMark} in @internalsref{Score} context. See
@code{input/test/boxed-molecule.ly} if you need boxes around the
marks.
\property Score.currentBarNumber = #217
@end example
-If you want boxed bar numbers, see the example file
-@code{input/test/boxed-molecule.ly}.
+To typeset Bar Numbers at regular intervals instead of at the beginning of each line,
+you need to change the grob property @code{break-visibility} as well as the translator
+property @code{barNumberVisibility}, as illustrated in the following example which also
+adds a box around the bar numbers:
+@example
+\property Score.BarNumber \override #'break-visibility =
+ #end-of-line-invisible
+\property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
+\property Score.BarNumber \override #'molecule-callback =
+ #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule)
+\property Score.BarNumber \override #'font-relative-size = #0
+@end example
+@lilypond
+\score {
+ \context Staff \notes \transpose c''' {
+ \property Score.BarNumber \override #'break-visibility = #end-of-line-invisible
+ \property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
+ \property Score.BarNumber \override #'molecule-callback =
+ #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule)
+ \property Score.BarNumber \override #'font-relative-size = #0
+
+ \repeat unfold 16 c1 \bar "|."
+ }
+}
+@end lilypond
See also @seeinternals{BarNumber}.
@refbugs
-Printing bar numbers at regular intervals is not implemented.
Barnumbers can collide with the StaffGroup, if there is one at the
top. To solve this, You have to twiddle with the
@internalsref{padding} property of @internalsref{BarNumber} if your
@cindex whole rests for a full measure
-The grob for this object is @internalsref{MultiMeasureRest}.
+The object for this object is @internalsref{MultiMeasureRest}.
@refbugs
@node Ancient notation
@section Ancient notation
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel
+@cindex Petrucci
+@cindex mensural
+
@menu
* Ancient note heads::
+* Ancient clefs::
* Custodes::
-* Ancient clefs ::
+* Ligatures::
* Figured bass::
@end menu
@node Ancient note heads
@subsection Ancient note heads
- To get a longa note head, you have to use mensural note heads. This
+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
+NoteHead object 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 Ancient clefs
+@subsection Ancient clefs
+
+LilyPond supports a variety of clefs, many of them ancient.
+
+For modern clefs, see section @ref{Clef}. For the percussion clef, see
+section @ref{Percussion staves}. For the @code{TAB} clef, see section
+@ref{Tablatures}.
+
+The following table shows all ancient clefs that are supported via the
+@code{\clef} command. Some of the clefs use the same glyph, but differ
+only with respect to the line they are printed on. In such cases, a
+trailing number in the name is used to enumerate these clefs. Still,
+you can manually force a clef glyph to be typeset on an arbitrary line,
+as described in section @ref{Clef}. The note printed to the right side
+of each clef denotes the @code{c'} with respect to the clef.
+
+@table @code
+
+@c --- This should go somewhere else: ---
+@c @item modern style G clef (glyph: @code{clefs-G})
+@c
+@c Supported clefs:
+@c @code{treble}, @code{violin}, @code{G}, @code{G2}, @code{french}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "G" c'}
+@c
+@c @item modern style F clef (glyph: @code{clefs-F})
+@c
+@c Supported clefs:
+@c @code{varbaritone}, @code{bass}, @code{F}, @code{subbass}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "F" c'}
+@c
+@c @item modern style C clef (glyph: @code{clefs-C})
+@c
+@c Supported clefs:
+@c @code{soprano}, @code{mezzosoprano}, @code{alto}, @code{C},
+@c @code{tenor}, @code{baritone}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "C" c'}
+
+@item modern style mensural C clef (glyph: @code{clefs-neo_mensural_c'})
+
+Supported clefs:
+@code{neo_mensural_c1}, @code{neo_mensural_c2},
+@code{neo_mensural_c3}, @code{neo_mensural_c4}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "neo_mensural_c2" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c1})
+
+Supported clefs:
+@code{petrucci_c1}
+for 1st staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c1" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c2})
+
+Supported clefs:
+@code{petrucci_c2}
+for 2nd staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c2" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c3})
+
+Supported clefs:
+@code{petrucci_c3}
+for 3rd staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c3" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c4})
+
+Supported clefs:
+@code{petrucci_c4}
+for 4th staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c4" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c5})
+
+Supported clefs:
+@code{petrucci_c5}
+for 5th staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c5" c'}
+
+@item petrucci style mensural F clef (glyph: @code{clefs-petrucci_f})
+
+Supported clefs:
+@code{petrucci_f}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_f" c'}
+
+@item petrucci style mensural G clef (glyph: @code{clefs-petrucci_g})
+
+Supported clefs:
+@code{petrucci_g}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_g" c'}
+
+@item historic style mensural C clef (glyph: @code{clefs-mensural_c'})
+
+Supported clefs:
+@code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3},
+@code{mensural_c4}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_c2" c'}
+
+@item historic style mensural F clef (glyph: @code{clefs-mensural_f})
+
+Supported clefs:
+@code{mensural_f}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_f" c'}
+
+@item historic style mensural G clef (glyph: @code{clefs-mensural_g})
+
+Supported clefs:
+@code{mensural_g}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_g" c'}
+
+@item Editio Vaticana style do clef (glyph: @code{clefs-vaticana_do})
+
+Supported clefs:
+@code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_do2" c'}
+
+@item Editio Vaticana style fa clef (glyph: @code{clefs-vaticana_fa})
+
+Supported clefs:
+@code{vaticana_fa1}, @code{vaticana_fa2}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_fa2" c'}
+
+@item Editio Medicaea style do clef (glyph: @code{clefs-medicaea_do})
+
+Supported clefs:
+@code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_do2" c'}
+
+@item Editio Medicaea style fa clef (glyph: @code{clefs-medicaea_fa})
+
+Supported clefs:
+@code{medicaea_fa1}, @code{medicaea_fa2}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_fa2" c'}
+
+@item historic style hufnagel do clef (glyph: @code{clefs-hufnagel_do})
+
+Supported clefs:
+@code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do2" c'}
+
+@item historic style hufnagel fa clef (glyph: @code{clefs-hufnagel_fa})
+
+Supported clefs:
+@code{hufnagel_fa1}, @code{hufnagel_fa2}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_fa2" c'}
+
+@item historic style hufnagel combined do/fa clef (glyph: @code{clefs-hufnagel_do_fa})
+
+Supported clefs:
+@code{hufnagel_do_fa}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do_fa" c'}
+
+@c --- This should go somewhere else: ---
+@c @item modern style percussion clef (glyph: @code{clefs-percussion})
+@c
+@c Supported clefs:
+@c @code{percussion}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "percussion" c'}
+@c
+@c @item modern style tab clef (glyph: @code{clefs-tab})
+@c
+@c Supported clefs:
+@c @code{tab}
+@c
+@c @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #6 \property Staff.TimeSignature \set #'transparent = ##t \clef "tab" c'}
+
+@end table
+
+@emph{Modern style} means ``as is typeset in current editions of
+transcribed mensural music''.
+
+@emph{Petrucci style} means ``inspired by printings published by the
+famous engraver Petrucci (1466-1539)''.
+
+@emph{Historic style} means ``as was typeset or written in contemporary
+historic editions (other than those of Petrucci)''.
+
+@emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
+
+Petrucci used C clefs with differently balanced left-side vertical
+beams, depending on which staffline it was printed.
+
@node Custodes
@subsection Custodes
@}
@end example
-@node Ancient clefs
-@subsection Ancient clefs
+@node Ligatures
+@subsection Ligatures
+
+@cindex Ligatures
+
+@c TODO: Should double check if I recalled things correctly when I wrote
+@c down the following paragraph by heart.
+In musical terminology, a ligature is a coherent graphical symbol that
+represents at least two different notes. Ligatures originally appeared
+in the manuscripts of Gregorian chant notation roughly since the 9th
+century as an allusion to the accent symbols of greek lyric poetry to
+denote ascending or descending sequences of notes. Both, the shape and
+the exact meaning of ligatures changed tremendously during the following
+centuries: In early notation, ligatures where used for monophonic tunes
+(Gregorian chant) and very soon denoted also the way of performance in
+the sense of articulation. With upcoming multiphony, the need for a
+metric system arised, since multiple voices of a piece have to be
+synchronized some way. New notation systems were invented, that used
+the manifold shapes of ligatures to now denote rhythmical patterns
+(e.g. black mensural notation, mannered notation, ars nova). With the
+invention of the metric system of the white mensural notation, the need
+for ligatures to denote such patterns disappeared. Nevertheless,
+ligatures were still in use in the mensural system for a couple of
+decades until they finally disappeared during the late 16th / early 17th
+century. Still, ligatures have survived in contemporary editions of
+Gregorian chant such as the Editio Vaticana from 1905/08.
+
+Syntactically, ligatures are simply enclosed by @code{\[} and @code{\]}.
+Some ligature styles (such as Editio Vaticana) may need additional input
+syntax specific for this particular type of ligature. By default, the
+@internalsref{LigatureBracket} engraver just marks the start and end of
+a ligature by small square angles:
-LilyPond supports a variety of clefs, many of them ancient. These can
-be selected from the @code{ancient} font family, by setting
-@code{Staff.clefGlyph}) to one of the following values
+@lilypond[singleline,verbatim]
+\score {
+ \notes \transpose c'' {
+ \[ g c a f d' \]
+ a g f
+ \[ e f a g \]
+ }
+}
+@end lilypond
-@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
+To select a specific style of ligatures, a proper ligature engraver has
+to be added to the @internalsref{Voice} context, as explained in the
+following subsections. Currently, Lilypond only supports white mensural
+ligatures with certain limitations. Support for Editio Vaticana will be
+added in the future.
-@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.''
+@menu
+* White mensural ligatures::
+@end menu
-@cindex Vaticana, Editio
-@cindex Medicaea, Editio
-@cindex hufnagel clefs
+@node White mensural ligatures
+@subsubsection White mensural ligatures
+
+@cindex Mensural ligatures
+@cindex White mensural ligatures
+
+Lilypond has limited support for white mensural ligatures. The
+implementation is still experimental; it currently may output strange
+warnings or even crash in some cases or produce weird results on more
+complex ligatures. To engrave white mensural ligatures, in the paper
+block the @internalsref{MensuralLigature} engraver has to be put into
+the @internalsref{Voice} context (and you probably want to remove the
+@internalsref{LigatureBracket} engraver). There is no additional input
+language to describe the shape of a white mensural ligature. The shape
+is rather determined solely from the pitch and duration of the enclosed
+notes. While this approach may take a new user quite a while to get
+accustomed, it has a great advantage: this way, lily has full musical
+information about the ligature. This is not only required for correct
+MIDI output, but also allows for automatic transcription of the
+ligatures.
+
+Example:
+@lilypond[singleline,verbatim]
+\score {
+ \notes \transpose c'' {
+ \property Score.timing = ##f
+ \property Score.defaultBarType = "empty"
+ \property Voice.NoteHead \set #'style = #'neo_mensural
+ \property Staff.TimeSignature \set #'style = #'neo_mensural
+ \clef "petrucci_g"
+ \[ g\longa c\breve a\breve f\breve d'\longa \]
+ s4
+ \[ e1 f1 a\breve g\longa \]
+ }
+ \paper {
+ \translator {
+ \VoiceContext
+ \remove Ligature_bracket_engraver
+ \consists Mensural_ligature_engraver
+ }
+ }
+}
+@end lilypond
+
+Without replacing @code{Ligature_bracket_engraver} with
+@code{Mensural_ligature_engraver}, the same music transcribes to the
+following:
+
+@lilypond[singleline,verbatim]
+\score {
+ \notes \transpose c'' {
+ \property Score.timing = ##f
+ \property Score.defaultBarType = "empty"
+ \property Voice.NoteHead \set #'style = #'neo_mensural
+ \property Staff.TimeSignature \set #'style = #'neo_mensural
+ \clef "petrucci_g"
+ \[ g\longa c\breve a\breve f\breve d'\longa \]
+ s4
+ \[ e1 f1 a\breve g\longa \]
+ }
+}
+@end lilypond
@node Figured bass
@subsection Figured bass
The support for figured bass consists of two parts: there is an input
mode, introduced by @code{\figures}, where you can enter bass figures
as numbers, and there is a context called @internalsref{FiguredBass}
-that takes care of making @internalsref{BassFigure} grobs.
+that takes care of making @internalsref{BassFigure} objects.
In figures input mode, a group of bass figures is delimited by
@code{<} and @code{>}. The duration is entered after the @code{>}.
where you want to override its decisions. In this section we discuss
ways to do just that.
-Formatting is internally done by manipulating so called grobs (graphic
-objects). Each grob carries with it a set of properties (grob
-properties) specific to that object. For example, a stem grob has
+Formatting is internally done by manipulating so called objects (graphic
+objects). Each object carries with it a set of properties (object
+properties) specific to that object. For example, a stem object has
properties that specify its direction, length and thickness.
The most direct way of tuning the output is by altering the values of
these properties. There are two ways of doing that: first, you can
-temporarily change the definition of a certain type of grob, thus
+temporarily change the definition of a certain type of object, thus
affecting a whole set of objects. Second, you can select one specific
-object, and set a grob property in that object.
+object, and set a object property in that object.
@menu
-* Tuning groups of grobs ::
-* Tuning per grob ::
+* Tuning groups of objects ::
+* Tuning per object ::
* Font selection::
* Text markup::
@end menu
-@node Tuning groups of grobs
-@subsection Tuning groups of grobs
+@node Tuning groups of objects
+@subsection Tuning groups of objects
-@cindex grob description
+@cindex object description
-A grob definition is a Scheme association list, that is stored in a
+A object definition is a Scheme association list, that is stored in a
context property. By assigning to that property (using plain
-@code{\property}), you can change the resulting grobs.
+@code{\property}), you can change the resulting objects.
@lilypond[verbatim, fragment]
c'4 \property Voice.Stem = #'()
@cindex \set
This mechanism is fairly crude, since you can only set, but not modify,
-the definition of a grob. For this reason, there is a more advanced
+the definition of a object. For this reason, there is a more advanced
mechanism.
-The definition of a grob is actually a list of default grob
-properties. For example, the definition of the Stem grob (available in
+The definition of a object is actually a list of default object
+properties. For example, the definition of the Stem object (available in
@file{scm/grob-description.scm}), defines the following values for
@internalsref{Stem}
\set \set \set \set @var{to default value}
@end example
-If there is no default (i.e. by default, the grob property is unset),
+If there is no default (i.e. by default, the object property is unset),
then you can use
@example
\set \set \set \revert
@end example
-For the digirati, the grob description is an Scheme association
+For the digirati, the object description is an Scheme association
list. Since a Scheme list is a singly linked list, we can treat it as a
stack, and @code{\override} and @code{\revert} are just push and pop
operations. This pushing and popping is also used for overriding
@refbugs
LilyPond will hang or crash if @var{value} contains cyclic references.
-The backend is not very strict in type-checking grob properties. If you
+The backend is not very strict in type-checking object properties. If you
@code{\revert} properties that are expected to be set by default,
LilyPond may crash.
-@node Tuning per grob
-@subsection Tuning per grob
+@node Tuning per object
+@subsection Tuning per object
+
+@cindex \once
+Tuning a single object is most often done with @code{\property}. The
+form,
+@example
+ \once \property @dots{}
+@end example
+@c
+applies a setting only during one moment in the score: notice how the
+original setting for stem thickness is restored automatically in the
+following example
+@c
+@lilypond[verbatim, fragment, relative=1]
+ c4
+ \once \property Voice.Stem \set #'thickness = #4
+ c4
+ c4
+@end lilypond
+@cindex \once
@cindex \outputproperty
-A second way of tuning grobs is the more arcane @code{\outputproperty}
+A second way of tuning objects is the more arcane @code{\outputproperty}
feature. The syntax is as follows:
@example
\outputproperty @var{predicate} @var{symbol} = @var{value}
@end example
-Here @code{predicate} is a Scheme function taking a grob argument, and
+Here @code{predicate} is a Scheme function taking a object argument, and
returning a boolean. This statement is processed by the
@code{Output_property_engraver}. It instructs the engraver to feed all
-grobs that it sees to @var{predicate}. Whenever the predicate returns
-true, the grob property @var{symbol} will be set to @var{value}.
+objects that it sees to @var{predicate}. Whenever the predicate returns
+true, the object property @var{symbol} will be set to @var{value}.
+
+This command is only single shot, in contrast to @code{\override} and
+@code{\set}.
You will need to combine this statement with @code{\context} to select
the appropriate context to apply this to.
-Here are some random examples.
-
-
In the following example, all note heads occurring at current staff
level, are shifted up and right by setting their @code{extra-offset}
property.
@cindex @code{extra-offset}
-In this example, the predicate checks the @code{text} grob property, to
+In this example, the predicate checks the @code{text} object property, to
shift only the `m.d.' text, but not the fingering instruction "2".
@lilypond[verbatim,singleline]
#(define (make-text-checker text)
@cindex font size
@cindex size
-The font used for printing a grob can be selected by setting
+The font used for printing a object can be selected by setting
@code{font-name}, e.g.
@example
\property Staff.TimeSignature
fonts or fonts that do not belong to the Computer Modern font family.
Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
can also be adjusted with a more fine-grained mechanism. By setting
-the grob properties described below, you can select a different font.
-All three mechanisms work for every grob that supports
+the object properties described below, you can select a different font.
+All three mechanisms work for every object that supports
@code{font-interface}.
@table @code
@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
to override default setting, which are always present. For example:
@example
- \property Lyrics . LyricText \override #'font-series = #'bold
- \property Lyrics . LyricText \override #'font-family = #'typewriter
- \property Lyrics . LyricText \override #'font-shape = #'*
+ \property Lyrics.LyricText \override #'font-series = #'bold
+ \property Lyrics.LyricText \override #'font-family = #'typewriter
+ \property Lyrics.LyricText \override #'font-shape = #'*
@end example
@cindex @code{font-style}
There are also pre-cooked font selection qualifiers. These are
-selected through the grob property @code{font-style}. For example,
+selected through the object property @code{font-style}. For example,
the style @code{finger} selects family @code{number} and relative size
@code{-3}. Styles available include @code{volta}, @code{finger},
@code{tuplet}, @code{timesig}, @code{mmrest}, @code{script},
@cindex magnification
-The size of the font may be scaled with the grob property
+The size of the font may be scaled with the object property
@code{font-magnification}. For example, @code{2.0} blows up all
letters by a factor 2 in both directions.
@end lilypond
Normally, the Scheme markup text is stored in the @code{text} property
-of a grob. Formally, it is defined as follows:
+of a object. Formally, it is defined as follows:
@example
text: string | (head? text+)
@code{large Large dynamic}
@end example
-The markup is broken down and converted into a list of grob properties,
+The markup is broken down and converted into a list of object properties,
which are prepended to the property list. The @var{key}-@var{value}
-pair is a grob property. A list of properties available is included in
-the generated documentation for @rint{Text_interface}.
+pair is a object property. A list of properties available is included in
+the generated documentation for @internalsref{text-interface}.
The following abbreviations are defined:
@table @code
\score {
\notes\relative c'' {
- a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
+ a1^#`((columns (font-relative-size . -1))
+ ,dotted-eight-note " = 64")
}
\paper {
linewidth = -1.
@section Global layout
The global layout determined by three factors: the page layout, the
-iline breaks and the spacing. These all influence each other: The
+line breaks and the spacing. These all influence each other: The
choice of spacing determines how densely each system of music is set,
-whree line breaks breaks are chosen, and thus ultimately how many
+where line breaks breaks are chosen, and thus ultimately how many
pages a piece of music takes. In this section we will explain how the
lilypond spacing engine works, and how you can tune its results.
@subsection Vertical spacing
@cindex vertical spacing
-@cindex distance between staffs
+@cindex distance between staves
@cindex staff distance
@cindex between staves, distance
The height of each system is determined automatically by lilypond, to
keep systems from bumping into each other, some minimum distances are
-set. By changing these, you can put staffs closer together, and thus
+set. By changing these, you can put staves closer together, and thus
put more systems onto one page.
Normally staves are stacked vertically. To make
@code{(-6 . 4)}. The default value is @code{(-6 . 6)}.
Vertical aligment of staves is handled by the
-@internalsref{VerticalAlignment} grob, which lives at
+@internalsref{VerticalAlignment} object, which lives at
@internalsref{Score} level.
-The piano staffs are handled a little differently: to make cross-staff
+The piano staves are handled a little differently: to make cross-staff
beaming work correctly, it necessary that the distance between staves
is fixed. This is also done with a @internalsref{VerticalAlignment}
-grob, created in @internalsref{PianoStaff}, but a forced distance is
-set. This is done with the grob property #'forced-distance. If you
+object, created in @internalsref{PianoStaff}, but a forced distance is
+set. This is done with the object property #'forced-distance. If you
want to override this, use a @code{\translator} block as follows:
@example
\translator @{
VerticalAlignment \override #'forced-distance = #9
@}
@end example
-This would bring the staffs together at a distance of 9 staff spaces,
+This would bring the staves together at a distance of 9 staff spaces,
and again this is measured from the center line of each staff.
@end lilypond
These two amounts of space are @code{shortest-duration-space}
-@code{spacing-increment}, grob properties of
+@code{spacing-increment}, object properties of
@internalsref{SpacingSpanner}. Normally @code{spacing-increment} is
set to 1.2, which is the width of a note head, and
@code{shortest-duration-space} is set to 2.0, meaning that the
In the introduction it was explained that stem directions influence
spacing. This is controlled with @code{stem-spacing-correction} in
-@internalsref{NoteSpacing}. The @code{StaffSpacing} grob contains the
+@internalsref{NoteSpacing}. The @code{StaffSpacing} object contains the
same property for controlling the stem/barline spacing. In the
following example shows these corrections, once with default settings,
and once with exaggerated corrections.
distributed vertically on the last page. This might produce ugly
results in case there are not enough systems on the last page. Note
that @command{lilypond-book} ignores @code{lastpagefill}. See
-@ref{Insert music snippets into your texts using lilypond-book} for
+@ref{Integrating text and music with lilypond-book} for
more information.
@cindex @code{lastpagefill}
projects / lilypond.git / blobdiff