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},
\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
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
\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]
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
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{flag-style} of
@internalsref{Stem}. The change in formatting is accomplished by
inserting @code{\startGraceMusic} before handling the grace notes, and
@code{\stopGraceMusic} after finishing the grace notes. You can add to
@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
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 = #'(-20 - 15 -10 -5)
+
+ \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
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.
@cindex whole rests for a full measure
-The grob for this object is @internalsref{MultiMeasureRest}.
+The object for this object is @internalsref{MultiMeasureRest}.
@refbugs
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.
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 \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
+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:
@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
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 @{
@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.
projects / lilypond.git / commitdiff