@}
@end example
-Since such a @q{context modification} is specified inside of
-music, it will affect @emph{all} outputs (typesetting @emph{and}
+Alternatively, if the music is being entered using the short form of the
+input mode-specifying commands, e.g. @code{\chords} rather than
+@code{\chordmode}, the @code{\with} command must be placed immediately
+after the mode-specifying command:
+
+@example
+\chords \with @{ [context settings for this (implicit) context instance only] @}
+@{
+ @dots{}
+@}
+@end example
+
+@noindent
+as it is the implicit context created by these short forms which should
+be modified. The same consideration applies to the other input
+mode-specifying short forms (@code{\drums}, @code{\figures}), see
+@ref{Input modes}.
+
+Since context modifications specified in @code{\with} blocks are inside
+music, they will affect @emph{all} outputs (typesetting @emph{and}
Midi) as opposed to changes within an output definition.
The following types of settings may be specified:
@end itemize
+@seealso
+Notation Reference:
+@ref{Input modes}
+
@node Order of precedence
@unnumberedsubsubsec Order of precedence
* The override command::
* The tweak command::
* set versus override::
+* The offset command::
* Modifying alists::
@end menu
@code{\overrideProperty} for a specific override.
+@node The offset command
+@subsection The @code{\offset} command
+
+@funindex \offset
+@cindex offsetting
+@cindex defaults, offsetting
+
+While it is possible to set grob properties to new values with the
+@code{\override}, @code{\tweak}, and @code{\overrideProperty} commands,
+it is often more convenient to modify such properties relative to a
+default value. The @code{\offset} command is available for this
+purpose.
+
+The syntax for @code{\offset} is
+
+@example
+[-]\offset @var{property} @var{offsets} @var{item}
+@end example
+
+The command works by adding the contents of @var{offsets} to the
+default setting of the property @var{property} of the grob indicated by
+@var{item}.
+
+Depending on the formulation of the command, @code{\offset} may act
+as either a @code{\tweak} or @code{\override}. The variations in
+usage are discussed after consideration is given to grob properties
+that may be used with @code{\offset}.
+
+@subsubsubheading{Properties which may be offset}
+
+Many, but not all, grob properties may be offset. If @var{property}
+cannot be offset, the object will remain unchanged and a warning will
+be issued. In such cases, @code{\override} or @code{\tweak} should be
+used to modify the object instead.
+
+One can work by trial and error and let the warnings be the guide to
+what may or may not be offset. A more systematic approach is possible,
+however.
+
+The following criteria determine whether a property can be modified with
+@code{\offset}:
+
+@itemize
+
+@item
+The property has a @q{default setting} in the grob's description. Such
+properties are listed for each grob in @rinternals{All layout objects}.
+(They are also found in @file{scm/define-grobs.scm}.)
+
+@item
+The property takes a numerical value. Numerical values include
+@code{number}, list of @code{number}s, @code{number-pair}, and
+@code{number-pair-list}. The pages at @rinternals{All layout objects}
+list the type of data characteristic to each property. It is immaterial
+whether the default setting is a function.
+
+@item
+The property cannot be a @q{subproperty}---a property residing within
+another property.
+
+@item
+Properties set to infinite values cannot be offset. There is no
+sensible way to offset positive and negative infinity.
+@end itemize
+
+The following examples consider several grob properties against the
+criteria outlined above.
+
+@itemize
+
+@item Properties that may be offset
+
+@table @asis
+
+@item @code{Hairpin.height}
+
+This property is not a subproperty, and it is listed at
+@rinternals{Hairpin}. For a value, it takes @q{dimension, in staff
+space} set to @code{0.6666}---clearly a non-infinite @code{number}.
+
+@item @code{Arpeggio.positions}
+
+The page @rinternals{Arpeggio} lists a @code{positions} property which
+accepts a @q{pair of numbers}. It defaults to
+@code{ly:arpeggio::positions}---a callback which will be evaluated
+during the typesetting phase to yield a pair of numbers for any given
+@code{Arpeggio} object.
+
+@end table
+
+@item Properties that may not be offset
+
+@table @asis
+
+@item @code{Hairpin.color}
+
+There is no listing for @code{color} at @rinternals{Hairpin}.
+
+@item @code{Hairpin.circled-tip}
+
+The listing for @code{Hairpin.circled-tip} at @rinternals{Hairpin} shows
+that it takes a @code{boolean} value. Booleans are non-numerical.
+
+@item @code{Stem.details.lengths}
+
+Though listed at @rinternals{Stem} and defaulting to a list of
+@code{number}s, this is a @q{subproperty}. There is currently no
+support for @q{nested properties}.
+
+@end table
+
+@end itemize
+
+@subsubsubheading{@bs{}offset as an override}
+
+If @var{item} is a grob name like @code{Arpeggio} or
+@code{Staff.OttavaBracket}, the result is an @code{\override} of the
+specified grob-type.
+
+@example
+\offset @var{property} @var{offsets} [@var{context}.]@var{GrobName}
+@end example
+
+Note that the leading hyphen is @emph{never} used with the @q{override}
+form, just as it is never used with the @code{\override} command itself.
+
+The following example uses the @q{override} form to lengthen the
+default arpeggios shown in the first measure to cover the extent of
+the chords more fully. The arpeggios are stretched by a half
+staff-space to top and bottom. Also shown is the same operation done on
+the first chord with an ordinary override of the @code{positions}
+property. This method is not at all expressive of the task of
+@q{stretching by a half staff-space}, as the endpoints must be specified
+with absolute rather than relative coordinates. Furthermore, individual
+overrides would be needed for the other chords, as they vary in size and
+position.
+
+@lilypond[quote,verbatim]
+arpeggioMusic = {
+ <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
+ <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
+}
+
+{
+ \arpeggioMusic
+ \bar "||"
+ \offset positions #'(-0.5 . 0.5) Arpeggio
+ \arpeggioMusic
+ \bar "||"
+ \once \override Arpeggio.positions = #'(-3.5 . -0.5)
+ <c' e' g'>1\arpeggio
+ \bar "||"
+}
+@end lilypond
+
+In its @q{override} usage, @code{\offset} may be prefaced with
+@code{\once} or @code{\temporary} and reverted using @code{\revert} with
+@var{property}. This follows from the fact that @code{\offset} actually
+creates an @code{\override} of @var{property}.
+
+@lilypond[quote,verbatim]
+music = { c'8\< d' e' f'\! }
+
+{
+ \music
+ \offset height 1 Hairpin
+ \music
+ \music
+ \revert Hairpin.height
+ \music
+ \bar "||"
+ \once \offset height 1 Hairpin
+ \music \music
+ \bar "||"
+ \override Hairpin.height = 0.2
+ \music
+ \temporary \offset height 2 Hairpin
+ \music
+ \music
+ \revert Hairpin.height
+ \music
+ \bar "||"
+}
+@end lilypond
+
+Also like @code{\override}, the @q{override} form of @code{\offset} may
+be used with @code{\undo} and @code{\single}.
+
+@lilypond[quote,verbatim]
+longStem = \offset length 6 Stem
+
+{
+ \longStem c'4 c''' c' c''
+ \bar "||"
+ \undo \longStem c'4 c''' c' c''
+ \bar "||"
+ \single \longStem c'4 c''' c' c''
+ \bar "||"
+}
+@end lilypond
+
+@subsubsubheading{@bs{}offset as a tweak}
+
+If @var{item} is a music expression such as @code{(} or
+@code{\arpeggio}, the result is the same music expression with a tweak
+applied.
+
+@example
+[-]\offset [@var{GrobName}.]@var{property} @var{offsets} @var{music-expression}
+@end example
+
+The syntax of @code{\offset} in its @q{tweak} form is analogous to the
+@code{\tweak} command itself, both in ordering and in the presence or
+absence of the leading hyphen.
+
+The following example uses the @q{tweak} form to adjust the vertical
+position of the @code{BreathingSign} object. Compare this with the
+ordinary @code{\tweak} command also demonstrated. The syntax is
+equivalent; however, the output of @code{\tweak} is less intuitive,
+since @code{BreathingSign.Y-offset} is calculated from the middle
+staff-line. It is not necessary to know how @code{Y-offset} is
+calculated when using @code{\offset}.
+
+@lilypond[quote,verbatim]
+{
+ c''4
+ \breathe
+ c''4
+ \offset Y-offset 2 \breathe
+ c''2
+ \tweak Y-offset 3 \breathe
+}
+@end lilypond
+
+In the previous example, the tweaked objects were created directly from
+the user input: the @code{\breathe} command was an explicit instruction
+to return a @code{BreathingSign} object. Since the focus of the command
+was unambiguous, there was no need to specify the object's name. When
+an object is @emph{indirectly} created, however, it is necessary to
+include the grob's name. This is the same as for the @code{\tweak}
+command.
+
+In the following example, the @code{Beam} object is lowered two
+staff-spaces by applying @code{\offset} to the @code{positions}
+property.
+
+The first application of @code{\offset} requires that the grob's name
+be included, because nothing in the input explicitly creates the
+beam. In the second application, the beam is created manually with the
+music expression @code{[}; therefore, the grob's name is not needed.
+(Also illustrated is a shorthand: a single @code{number} will be applied
+to both members of a @code{number-pair}.)
+
+@lilypond[quote,verbatim]
+{
+ c''8 g'' e'' d''
+ \offset Beam.positions #'(-2 . -2)
+ c''8 g'' e'' d''
+ c''8 g'' e'' d''
+ c''8-\offset positions #-2 [ g'' e'' d'']
+}
+@end lilypond
+
+@subsubsubheading{@bs{}offset with broken spanners}
+
+Independently modifying segments of a spanner extending over a line
+break or breaks is also possible. In this case, @var{offsets}
+takes a list of values of the property's required data type.
+
+The @code{\offset} command used in this manner is similar to the
+@code{\alterBroken} command. (See @ref{Modifying broken spanners}.)
+In contrast with @code{\alterBroken}, however, the values given to
+@code{\offset} are relative, not absolute.
+
+The following example displaces the @q{broken} @code{OttavaBracket}
+object through its @code{staff-padding} property. Since the property
+takes a @code{number}, @var{offsets} is provided with a list of
+@code{number}s to account for the two segments created by the line
+break. The bracket piece on the first line is effectively untouched
+since @code{0} is added to its default value of @code{staff-padding}.
+The segment on the second line is raised three staff-spaces from its
+default height. The default height happens to be @code{2}, though it is
+not necessary to know this to achieve the desired positioning.
+
+@lilypond[quote,verbatim]
+{
+ \offset staff-padding #'(0 3) Staff.OttavaBracket
+ \ottava #1
+ c'''2 c'''
+ \break
+ c'''2 c'''
+}
+@end lilypond
+
+The following example mimics the effect of the @code{\shape} command by
+offsetting the @code{control-points} property of the @code{Slur} object.
+Here, @var{offsets} is a list of @code{number-pair-list}s, one for each
+slur segment. This example achieves a result identical to the
+corresponding illustration at @ref{Modifying shapes}.
+
+@lilypond[quote,verbatim]
+{
+ c'4-\offset control-points #'(
+ ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
+ ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+ ) ( f'4 g' c''
+ \break
+ d'4 c'' f' c')
+}
+@end lilypond
+
+
@node Modifying alists
@subsection Modifying alists
@subsection Input modes
The way in which the notation contained within an input file is
-interpreted is determined by the current input mode.
+interpreted is determined by the current input mode. In general,
+there are two ways of specifying the mode: a long form, e.g.
+@code{\chordmode}, and a short form, e.g. @code{\chords}. The long
+form is typically used when supplying input to a variable or when
+entering input directly into an explicitly created context. The short
+form implicitly creates a context of the correct type for the input and
+passes the input directly to it. It is useful in simple situations
+when there is no requirement to explicitly create the receiving context.
@subsubsubheading Chord mode
This is activated with the @code{\chordmode} command, and causes
input to be interpreted with the syntax of chord notation, see
-@ref{Chord notation}. Chords are rendered as notes on a staff.
+@ref{Chord notation}. Music in chord mode is rendered as chords on a staff
+when entered into a @code{Staff} context, as chord names when entered
+into a @code{ChordNames} context or as fret boards when entered into
+a @code{FretBoards} context.
-Chord mode is also activated with the @code{\chords} command.
-This also creates a new @code{ChordNames} context and
-causes the following input to be interpreted with the syntax of
-chord notation and rendered as chord names in the @code{ChordNames}
-context, see @ref{Printing chord names}.
+Chord mode is also activated with the @code{\chords} command. This
+also causes the following input to be interpreted with the syntax of
+chord notation but in addition it implicitly creates a new
+@code{ChordNames} context and renders the input into it as chord names,
+see @ref{Printing chord names}.
@subsubsubheading Drum mode
This is activated with the @code{\drummode} command, and causes
input to be interpreted with the syntax of drum notation, see
-@ref{Basic percussion notation}.
+@ref{Basic percussion notation}. Music in drum mode is rendered as
+percussion notes when entered into a @code{DrumStaff} context.
-Drum mode is also activated with the @code{\drums} command.
-This also creates a new @code{DrumStaff} context and causes the
-following input to be interpreted with the syntax of drum notation
-and rendered as drum symbols on a drum staff, see
-@ref{Basic percussion notation}.
+Drum mode is also activated with the @code{\drums} command. This
+also causes the following input to be interpreted with the syntax of
+drum notation but in addition it implicitly creates a new
+@code{DrumStaff} context and renders the input into it as percussion
+notes, see @ref{Basic percussion notation}.
@subsubsubheading Figure mode
This is activated with the @code{\figuremode} command, and causes
input to be interpreted with the syntax of figured bass, see
-@ref{Entering figured bass}.
+@ref{Entering figured bass}. Music in figure mode is rendered as
+figured bass when entered into a @code{FiguredBass} context or a
+@code{Staff} context.
Figure mode is also activated with the @code{\figures} command.
-This also creates a new @code{FiguredBass} context and causes the
-following input to be interpreted with the figured bass syntax
-and rendered as figured bass symbols in the @code{FiguredBass}
-context, see @ref{Introduction to figured bass}.
+This also causes the following input to be interpreted with the
+figured bass syntax but in addition it implicitly creates a new
+@code{FiguredBass} context and renders the input into it as figured
+bass, see @ref{Introduction to figured bass}.
@subsubsubheading Fret and tab modes
render them in a @code{TabStaff} context, see
@ref{Default tablatures}.
-To create fret diagrams above a staff, you have two choices.
-You can either use the @code{FretBoards} context (see
-@ref{Automatic fret diagrams}) or you can enter them as a markup
-above the notes using the @code{\fret-diagram} command (see
-@ref{Fret diagram markups}).
+To create fret diagrams above a staff, enter notes or chords in either
+note mode or chord mode and render them in a @code{FretBoards} context,
+see @ref{Automatic fret diagrams}. Alternatively, fret diagrams can be
+entered as markup above the notes using the @code{\fret-diagram}
+command, see @ref{Fret diagram markups}.
@subsubsubheading Lyrics mode
This is activated with the @code{\lyricmode} command, and causes
input to be interpreted as lyric syllables with optional durations
-and associated lyric modifiers, see @ref{Vocal music}.
+and associated lyric modifiers, see @ref{Vocal music}. Input in
+lyric mode is rendered as lyric syllables when entered into a
+@code{Lyrics} context.
+
+Lyric mode is also activated with the @code{\lyrics} command. This
+also causes the following input to be interpreted as lyric syllables
+but in addition it implicitly creates a new @code{Lyrics} context and
+renders the input into it as lyric syllables.
-Lyric mode is also activated with the @code{\addlyrics} command.
-This also creates a new @code{Lyrics} context and an implicit
-@code{\lyricsto} command which associates the following lyrics
-with the preceding music.
+Lyric mode is also activated with the @code{\addlyrics} command. This
+also implicitly creates a new @code{Lyrics} context and in addition it
+adds an implicit @code{\lyricsto} command which associates the following
+lyrics with the preceding music, see @ref{Automatic syllable durations}.
@subsubsubheading Markup mode
}
@end lilypond
-Any of the glyphs in the Feta Font can be supplied to the
-@code{\musicglyph} markup command -- see @ref{The Feta font}.
+Any of the @emph{Feta} glyphs used in the Emmentaler font can be
+supplied to the @code{\musicglyph} markup command -- see
+@ref{The Emmentaler font}.
@file{EPS} files and Postscript commands can both be inserted inline
using the @code{\epsfile} and @code{\postscript} markup commands
@ref{Graphic notation inside markup},
@ref{Formatting text},
@ref{Text markup commands},
-@ref{The Feta font},
+@ref{The Emmentaler font},
@ref{Graphic}.
projects / lilypond.git / blobdiff