Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.20"
+@c \version "2.17.30"
@node Changing defaults
@chapter Changing defaults
@strong{@emph{RhythmicStaff}}
-Like @code{Staff} but for printing rhythms. Pitches are ignored;
-the notes are printed on one line.
+Like @code{Staff} but for printing rhythms. Pitches are ignored
+when engraving; the notes are printed on one line. The MIDI
+rendition retains pitches unchanged.
@strong{@emph{TabStaff}}
@ref{Bottom-level contexts - voices},
@ref{The set command},
@ref{The override command},
-@ref{The \layout block}.
+@ref{The layout block,,The @code{@bs{}layout} block}.
@node Defining new contexts
\consists "Pitch_squash_engraver"
squashedPosition = #0
\override NoteHead.style = #'slash
- \override Stem.transparent = ##t
+ \hide Stem
\alias Voice
}
\context { \Staff
@example
\override NoteHead.style = #'slash
-\override Stem.transparent = ##t
+\hide Stem
@end example
All these plug-ins have to communicate under the control of the
\consists "Pitch_squash_engraver"
squashedPosition = #0
\override NoteHead.style = #'slash
- \override Stem.transparent = ##t
+ \hide Stem
\alias Voice
@}
@end example
@node set versus override
@subsection @code{\set} vs. @code{\override}
-@c TODO -- This section is probably unnecessary now.
-
-@ignore
-We have seen two methods of changing properties: @code{\set} and
-@code{\override}. There are actually two different kinds of
-properties.
-
-@code{fontSize} is a special property: it is equivalent to
-entering @code{\override @dots{} #'font-size} for all pertinent
-objects. Since this is a common change, the special
-property (modified with @code{\set}) was created.
-
-@end ignore
+@c TODO Should't a bunch of that be explained earlier?
+@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.
+
+@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.
@node Modifying alists
@subsection Modifying alists
@unnumberedsubsubsec Removing the stencil
@cindex stencil, removing
+@funindex \omit
Every layout object has a stencil property. By default this is set
to the specific function which draws that object. If this property
a a a
@end lilypond
+This rather common operation has a shortcut @code{\omit}:
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\omit Score.BarLine
+a a
+\undo \omit Score.BarLine
+a a a
+@end lilypond
+
@node Making objects transparent
@unnumberedsubsubsec Making objects transparent
@cindex transparent, making objects
+@funindex \hide
Every layout object has a transparent property which by default is
set to @code{#f}. If set to @code{#t} the object still occupies
a a
@end lilypond
+This rather common operation has a shortcut @code{\hide}:
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \hide NoteHead
+a a
+@end lilypond
+
@node Painting objects white
@unnumberedsubsubsec Painting objects white
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Modifying broken spanners::
* Unpure-pure containers::
@end menu
@rinternals{TieColumn}.
+@node Modifying broken spanners
+@subsection Modifying broken spanners
+
+@menu
+* Using alterBroken::
+@end menu
+
+@node Using alterBroken
+@unnumberedsubsubsec Using @code{\alterBroken}
+
+@cindex spanners, modifying
+@cindex broken spanners, modifying
+@funindex \alterBroken
+
+When a spanner crosses a line break or breaks, each piece
+inherits the attributes of the original spanner. Thus, ordinary
+tweaking of a broken spanner applies the same modifications to
+each of its segments. In the example below, overriding
+@code{thickness} affects the slur on either side of the line
+break.
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+r2
+\once\override Slur.thickness = 10
+c8( d e f
+\break
+g8 f e d) r2
+@end lilypond
+
+Independently modifying the appearance of individual pieces
+of a broken spanner is possible with the @code{\alterBroken}
+command. This command can produce either an @code{\override}
+or a @code{\tweak} of a spanner property.
+
+The syntax for @code{\alterBroken} is
+
+@example
+[-]@code{\alterBroken} @var{property} @var{values} @var{item}
+@end example
+
+The argument @var{values} is a list of values, one for each
+broken piece. If @var{item} is a grob name like @code{Slur} or
+@code{Staff.PianoPedalBracket}, the result is an @code{\override}
+of the specified grob type. If @var{item} is a music expression
+such as @qq{(} or @qq{[} the result is the same music expression
+with an appropriate tweak applied.
+
+The leading hyphen must be used with the @code{\tweak} form. Do
+not add it when @code{\alterBroken} is used as an
+@code{\override}.
+
+In its @code{\override} usage, @code{\alterBroken} may be
+prefaced by @code{\once} or @code{\temporary} and reverted by
+using @code{\revert} with @var{property}.
+
+The following code applies an independent @code{\override} to
+each of the slur segments in the previous example:
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+r2
+\alterBroken thickness #'(10 1) Slur
+c8( d e f
+\break
+g8 f e d) r2
+@end lilypond
+
+The @code{\alterBroken} command may be used with any spanner
+object, including @code{Tie}, @code{PhrasingSlur}, @code{Beam}
+and @code{TextSpanner}. For example, an editor preparing a
+scholarly edition may wish to indicate the absence of part of a
+phrasing slur in a source by dashing only the segment which has
+been added. The following example illustrates how this can be
+done, in this case using the @code{\tweak} form of the command:
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+% The empty list is conveniently used below, because it is the
+% default setting of dash-definition, resulting in a solid curve.
+c2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e
+\break
+g2 e\)
+@end lilypond
+
+It is important to understand that @code{\alterBroken} will set
+each piece of a broken spanner to the corresponding value in
+@var{values}. When there are fewer values than pieces, any
+additional piece will be assigned the empty list. This may lead
+to undesired results if the layout property is not set to the
+empty list by default. In such cases, each segment should be
+assigned an appropriate value.
+
+@knownissues
+Line breaks may occur in different places following changes in
+layout. Settings chosen for @code{\alterBroken} may be unsuitable
+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}.
+
+@seealso
+Extending LilyPond:
+@rextend{Difficult tweaks}.
+
+
@node Unpure-pure containers
@subsection Unpure-pure containers