>> > > - list of contexts: my *danger unmaintainable*
>> > > alarm just went off. I'm
-
I knew it would... And leaving out some of them is perfectly fine
-with me.
-I do think that a list like this, with the main contexts and a
-brief
-description of what they do (perhaps also with a note about what
-default
-behavior is associated with each of them, but this may be
-unmanageable),
-should be there, and then we could simply list the remaining ones
-without
-further explanation and with links to the IR.
+with me. I do think that a list like this, with the main contexts and a
+brief description of what they do (perhaps also with a note about what
+default behavior is associated with each of them, but this may be
+unmanageable), should be there, and then we could simply list the
+remaining ones without further explanation and with links to the IR.
@end ignore
@c TODO Improve layout, order and consistency of wording -td
@strong{@emph{DrumStaff}}
-Handles typesetting for percussion. Can contain @code{DrumVoice}
+Handles typesetting for percussion. Can contain @code{DrumVoice}.
@strong{@emph{VaticanaStaff}}
Contexts are usually terminated at the first musical moment in
which they have nothing to do. So @code{Voice} contexts die as
-soon as they contain no events; @code{Staff} contexts die as soon
-as all the @code{Voice} contexts within them contain no events; etc.
+soon as they contain no events, @code{Staff} contexts die as soon
+as all the @code{Voice} contexts within them contain no events, etc.
This can cause difficulties if earlier contexts which have died
have to be referenced, for example, when changing staves with
@code{\change} commands, associating lyrics with a voice with
@}
@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
@cindex engravers, including in contexts
@funindex \alias
-@funindex alias
@funindex \name
-@funindex name
@funindex \type
-@funindex type
@funindex \consists
-@funindex consists
@funindex \accepts
-@funindex accepts
@funindex \denies
-@funindex denies
Specific contexts, like @code{Staff} and @code{Voice}, are made from
simple building blocks. It is possible to create new types of
@qq{main}, it should be defined like this:
@example
-@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+\new Staff \with @{ alignAboveContext = #"main" @}
@end example
A similar situation arises when positioning a temporary lyrics
@end table
@end quotation
-By increasing the value of @code{padding}, we can move the
-fingering away from the note head. The following command inserts
-3 staff spaces of white
-between the note and the fingering:
+By increasing the value of @code{padding}, we can move the fingering
+away from the note head. The following command will insert @qq{three
+staff spaces} worth of distance between the note and a fingering mark:
+
@example
\once \override Voice.Fingering.padding = #3
@end example
-Inserting this command before the Fingering object is created,
-i.e., before @code{c2}, yields the following result:
+Inserting the padding before the fingering object is created results in
+the following:
@lilypond[quote,fragment,verbatim]
\once \override Voice.Fingering.padding = #3
c''-2
@end lilypond
-
-In this case, the context for this tweak is @code{Voice}. This
-fact can also be deduced from the program reference, for the page for
-the @rinternals{Fingering_engraver} plug-in says
+In this case, the context for this tweak is @code{Voice}. See
+@rinternals{Fingering_engraver} plug-in, which says:
@quotation
Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
conventions:
@itemize
-@item scheme functions: lowercase-with-hyphens (incl. one-word
+@item scheme functions: lowercase-with-hyphens (also includes one-word
names)
-@item scheme functions: ly:plus-scheme-style
+
+@item LilyPond-specific scheme functions: ly:plus-scheme-style
+
@item music events, music classes and music properties:
as-scheme-functions
+
@item Grob interfaces: scheme-style
+
@item backend properties: scheme-style (but X and Y!)
+
@item contexts (and MusicExpressions and grobs): Capitalized or
CamelCase
+
@item context properties: lowercaseFollowedByCamelCase
-@item engravers:
-Capitalized_followed_by_lowercase_and_with_underscores
+
+@item engravers: Capitalized_followed_by_lowercase_and_with_underscores
@end itemize
Questions to be answered:
@itemize
+
@item Which of these are conventions and which are rules?
+
@item Which are rules of the underlying language, and which are
-LP-specific?
+LilyPond-specific?
@end itemize
@node Modifying properties
* The override command::
* The tweak command::
* set versus override::
+* The offset command::
* Modifying alists::
@end menu
Contexts properties are usually named in
@code{studlyCaps}. They mostly control the translation from
-music to notation, e.g. @code{localAlterations} (for determining
+music to notation, e.g., @code{localAlterations} (for determining
whether to print accidentals), or @code{measurePosition} (for
determining when to print a bar line). Context properties can
change value over time while interpreting a piece of music;
@cindex \once
-Preceding a @code{\set} command by @code{\once} makes the
-setting apply to only a single time-step:
+Preceding a @code{\set} or @code{\unset} command by @code{\once}
+makes the setting apply to only a single time-step:
@lilypond[quote,fragment,verbatim]
c''4
@funindex \once
@cindex overriding for only one moment
-@code{\once} can be used with @code{\override}
+@code{\once} can be used with @code{\override} or @code{\revert}
to affect only the current time step:
@lilypond[quote,verbatim]
@funindex \set
@funindex \override
-Both @code{\set} and @code{\override} manipulate properties
-associated with contexts. In either case, properties heed the
-hierarchy of contexts: properties not set in a context itself show
-the values of the respective parent context.
-
-Values and lifetime of context properties are dynamic and only
-available when music is being interpreted, @q{iterated}. At the
-time of context creation, properties are initialized from the
-corresponding context definition and possible context
-modifications. Afterwards, changes are achieved with
-property-setting commands in the music itself.
-
-Now grob definitions are a special category of context properties.
-Since their structure, bookkeeping and use is different from
-ordinary context properties, they are accessed with a different
-set of commands, and treated separately in the documentation.
-
-As opposed to plain context properties, grob definitions are
-subdivided into grob properties. A @qq{grob} (graphical object)
-is usually created by an engraver at the time of interpreting a
-music expression and receives its initial properties from the
-current grob definition of the engraver's context. The engraver
-(or other @q{backend} parts of LilyPond) may subsequently add or
-change properties to the grob, but that does not affect the
-context's grob definition.
-
-What we call @q{grob properties} in the context of user-level
-tweaking are actually the properties of a context's grob
-definition. In contrast to ordinary context properties, grob
-definitions have the bookkeeping required to keep track of its
-parts, the individual grob properties (and even subproperties of
-them) separately so that it is possible to define those parts in
-different contexts and have the overall grob definition at the
-time of grob creation be assembled from pieces provided in
-different contexts among the current context and its parents.
-
-Grob definitions are manipulated using @code{\override} and
-@code{\revert} and have a name starting with a capital letter
-(like @samp{NoteHead}) whereas ordinary context properties are
-manipulated using @code{\set} and @code{\unset} and are named
-starting with a lowercase letter.
+
+The @code{\set} and @code{\override} commands manipulate properties
+associated with contexts. In both cases, the properties follow a
+@emph{hierarchy of contexts}; properties that are not set themselves in
+a context will still show the values of their respective parent's
+context.
+
+The lifetime and value of a context property is dynamic and only
+available when music is being interpreted (i.e., @q{iterated}). At the
+time of the context's creation, properties are initialized from its
+corresponding definitions (along with any other modifications) of that
+context. Any subsequent changes are achieved with any
+@q{property-setting} commands that are within the music itself.
+
+Graphical Object (or @qq{grob}) definitions are a @emph{special}
+category of context properties as their structure and use is different
+from that of normal context properties. Unlike normal context
+properties, grob definitions are subdivided into @emph{grob properties}.
+
+Also, in contrast to normal context properties, grob definitions have
+their own internal @q{bookkeeping} used to keep track of their own
+individual grob properties and any sub-properties. This means that it
+is possible to define those parts within different contexts and yet
+still have the overall grob definition at the time of grob creation from
+all the pieces provided amongst the current context and its parent(s).
+
+A grob is usually created by an engraver at the time of interpreting a
+music expression and receives its initial properties from the current
+grob definition of the engraver's context. The engraver (or other
+@q{backend} parts of LilyPond) can then change (or add to) the grob's
+initial properties. However, this does not affect the context's own
+grob definition.
+
+What LilyPond calls @emph{grob properties} in the context of
+@q{user-level} tweaks are really the properties of a @emph{context's}
+own grob definition.
+
+Grob definitions are accessed with a different set of commands and are
+manipulated using @code{\override} and @code{\revert} and have a name
+starting with a capital letter (e.g., @samp{NoteHead}); whereas normal
+context properties are manipulated using @code{\set} and @code{\unset}
+and are named starting with a lowercase letter.
@cindex tweak, relation to @code{\override}
@funindex \tweak
@funindex \overrideProperty
-The special commands @code{\tweak} and @code{\overrideProperty}
-change grob properties bypassing context properties completely.
-Instead they catch grobs as they are being created and then
-directly set properties on them when they originate from a tweaked
-music event or are of a particular kind, respectively.
+
+The commands @code{\tweak} and @code{\overrideProperty} change grob
+properties by bypassing all context properties completely and, instead,
+catch grobs as they are being created, setting properties on them for
+a music event (@code{\tweak}) or, in the case of
+@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 slur piece on the first line is effectively untouched since
+@code{0} is added to its default value. The segment on the second
+line is raised two staff-spaces from its default height. The default
+height happens to be @code{2}, though it is not necesssary to know this.
+
+@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
* The direction property::
@end menu
+
@node Articulation direction indicators
@unnumberedsubsubsec Articulation direction indicators
-By default some directions are always up or always down (e.g.
+By default some directions are always up or always down (e.g.,
dynamics or fermata), while other things can alternate between
up or down based on the stem direction (like slurs or accents).
@item @code{\tweak} commands
@item @code{\markup} commands
@item @code{\tag} commands
-@item string markups, e.g. -"string"
-@item fingering instructions, e.g. @w{@code{-1}}
-@item articulation shortcuts, e.g. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
+@item string markups, e.g., -"string"
+@item fingering instructions, e.g., @w{@code{-1}}
+@item articulation shortcuts, e.g., @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
@end itemize
Direction indicators affect only the next note:
}
@end lilypond
+
@node The direction property
@unnumberedsubsubsec The direction property
direction. These are of the form
@example
-@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+\xxxUp, \xxxDown or \xxxNeutral
@end example
@noindent
@end lilypond
In polyphonic music, it is generally better to specify an explicit
-@code{voice} than change an object's direction. For more information.
-See @ref{Multiple voices}.
+@code{voice} than change an object's direction. For more information,
+see @ref{Multiple voices}.
@seealso
Learning Manual:
@item arrow
Setting this sub-property to @code{#t} produces an arrowhead at the
-end of the line.
+end-points of the line.
@item padding
This sub-property controls the space between the specified
even give errors. The following limitations apply:
@itemize @bullet
-@item Bar lines cannot be printed at start of line.
-@item A bar number cannot be printed at the start of the first
-line unless it is set to be different from 1.
-@item Clef -- see below
-@item Double percent repeats are either all printed or all
-suppressed. Use begin-of line-invisible to print and
-all-invisible to suppress.
-@item Key signature -- see below
-@item ClefModifier -- see below
+@item Bar lines cannot be printed at the start of line.
+
+@item A bar number cannot be printed at the start of the @emph{first}
+line unless it is set to be different from @code{1}.
+
+@item Clef -- see the next section.
+
+@item Double percent repeats are either @emph{all printed} or
+@emph{all suppressed}. Use @code{begin-of-line-invisible}
+to print them and @code{all-invisible} to suppress them.
+
+@item Key signature -- see the next section.
+
+@item ClefModifier -- see the next section.
@end itemize
+
@node Special considerations
@unnumberedsubsubsec Special considerations
The @code{break-visibility} property controls the visibility of
key signatures and changes of clef only at the start of lines,
-i.e. after a break. It has no effect on the visibility of the
+i.e., after a break. It has no effect on the visibility of the
key signature or clef following an explicit key change or an
explicit clef change within or at the end of a line. In the
following example the key signature following the explicit change
VerticalAxisGroup groups together different grobs like Staff, Lyrics,
etc. VerticalAlignment then vertically aligns the different grobs
grouped together by VerticalAxisGroup. There is usually only one
-VerticalAlignment per score but every Staff, Lyrics, etc. has its own
+VerticalAlignment per score but every Staff, Lyrics, etc., has its own
VerticalAxisGroup.
}
@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}.
-@c TODO Add inserting eps files or ref to later
+@file{EPS} files and Postscript commands can both be inserted inline
+using the @code{\epsfile} and @code{\postscript} markup commands
+respectively -- see @ref{Graphic}.
-@c TODO Add inserting Postscript or ref to later
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@ref{Formatting text},
@ref{Text markup commands},
-@ref{The Feta font}.
+@ref{The Emmentaler font},
+@ref{Graphic}.
@node Modifying shapes
The syntax of @code{\shape} is
@example
-[-]@code{\shape} @var{displacements} @var{item}
+[-]\shape @var{displacements} @var{item}
@end example
This will reposition the control-points of @var{item} by the amounts
The syntax for @code{\alterBroken} is
@example
-[-]@code{\alterBroken} @var{property} @var{values} @var{item}
+[-]\alterBroken @var{property} @var{values} @var{item}
@end example
The argument @var{values} is a list of values, one for each
for a spanner that is no longer broken or is split into more
segments than before. Explicit use of @code{\break} can guard
against this situation.
-
+
The @code{\alterBroken} command is ineffective for spanner
properties accessed before line-breaking such as
@code{direction}.
Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
-Scheme function instead of a literal (i.e. a number or pair).
+Scheme function instead of a literal (i.e., a number or pair).
For certain grobs, the @code{Y-extent} is based on the @code{stencil}
property, overriding the stencil property of one of these will
value which is then used for fine-tuning much later during the spacing
process.
+@c TODO: The following example supposedly showing a collision no longer
+@c 'works' since 2.18.x. Another example of a collision is needed.
+@c Issue #3512
+
@lilypond[verbatim,quote,ragged-right]
#(define (square-line-circle-space grob)
(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
@item @code{@var{@dots{}music@dots{}}}
@tab normal LilyPond input, using @code{$} (in places where only
-Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
+LilyPond constructs are allowed) or @code{#} (to use it as a Scheme
value or music function argument or music inside of music lists) to
reference arguments
(eg. @samp{#arg1}).
Notation Reference:
@ref{Predefined type predicates}.
-Extending Lilypond:
+Extending LilyPond:
@rextend{Music functions}.
Installed Files:
projects / lilypond.git / blobdiff