version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.11.55"
@node Changing defaults
@chapter Changing defaults
+@strong{N.B. This Chapter is under heavy development at present.}
The purpose of LilyPond's design is to provide the finest output
quality as a default. Nevertheless, it may happen that you need to
@c TODO Add introduction which explains contexts in generality -td
-@unnumberedsubsec Score - the master of all contexts
+Contexts are arranged heirarchically:
+
+@menu
+* Score - the master of all contexts::
+* Top-level contexts - staff containers::
+* Intermediate-level contexts - staves::
+* Bottom-level contexts - voices::
+@end menu
+
+@node Score - the master of all contexts
+@unnumberedsubsubsec Score - the master of all contexts
This is the top level notation context. No other context can
contain a Score context. By default the Score context handles
processed, or explicitly when a @code{\new Score} command is
executed.
-@subheading Top-level contexts: Staff containers
+@node Top-level contexts - staff containers
+@unnumberedsubsubsec Top-level contexts - staff containers
-@subsubheading StaffGroup
+@strong{@emph{StaffGroup}}
Groups staves while adding a bracket on the left side, grouping
the staves together. The bar lines of the contained staves are
connected vertically. StaffGroup only consists of a collection
of staves, with a bracket in front and spanning bar lines.
-@unnumberedsubsubsec ChoirStaff
+@strong{@emph{ChoirStaff}}
Identical to StaffGroup except that the bar lines of the contained
staves are not connected vertically.
-@unnumberedsubsubsec GrandStaff
+@strong{@emph{GrandStaff}}
A group of staves, with a brace on the left side, grouping
the staves together. The bar lines of the contained staves are
connected vertically.
-@unnumberedsubsubsec PianoStaff
+@strong{@emph{PianoStaff}}
TODO No longer correct? Check. -td
Just like GrandStaff but with a forced distance between the
staves, so cross staff beaming and slurring can be used.
-@unnumberedsubsubsec DrumStaff
-
-Handles typesetting for percussion. Can contain DrumVoice
-
-@unnumberedsubsubsec InnerStaffGroup
+@strong{@emph{InnerStaffGroup}}
TODO -td
-@unnumberedsubsubsec InnerChoirStaff
+@strong{@emph{InnerChoirStaff}}
TODO -td
-@heading Staff-level contexts
+@node Intermediate-level contexts - staves
+@unnumberedsubsubsec Intermediate-level contexts - staves
-@unnumberedsubsubsec Staff
+@strong{@emph{Staff}}
Handles clefs, bar lines, keys, accidentals. It can contain
Voice contexts.
-@unnumberedsubsubsec RhythmicStaff
+@strong{@emph{RhythmicStaff}}
Like Staff but for printing rhythms. Pitches are ignored;
the notes are printed on one line.
-@unnumberedsubsubsec TabStaff
+@strong{@emph{TabStaff}}
Context for generating tablature. By default lays the music
expression out as a guitar tablature, printed on six lines.
-@unnumberedsubsubsec VaticanaStaff
+@strong{@emph{DrumStaff}}
+
+Handles typesetting for percussion. Can contain DrumVoice
+
+@strong{@emph{VaticanaStaff}}
Same as Staff, except that it is designed for typesetting
a piece in gregorian style.
-@unnumberedsubsubsec MensuralStaff
+@strong{@emph{MensuralStaff}}
Same as Staff, except that it is designed for typesetting
a piece in mensural style.
-@unnumberedsubsec Voice-level (bottom) contexts
+@node Bottom-level contexts - voices
+@unnumberedsubsubsec Bottom-level contexts - voices
Voice-level contexts initialise certain properties and start
appropriate engravers. Being bottom-level contexts, they cannot
contain other contexts.
-@unnumberedsubsubsec Voice
+@strong{@emph{Voice}}
Corresponds to a voice on a staff. This context handles the
conversion of dynamic signs, stems, beams, super- and sub-scripts,
slurs, ties, and rests. You have to instantiate this explicitly
if you require multiple voices on the same staff.
-@unnumberedsubsubsec VaticanaVoice
+@strong{@emph{VaticanaVoice}}
Same as Voice, except that it is designed for typesetting a piece
in gregorian style.
-@unnumberedsubsubsec MensuralVoice
+@strong{@emph{MensuralVoice}}
Same as Voice, with modifications for typesetting a piece in
mensural style.
-@unnumberedsubsubsec Lyrics
+@strong{@emph{Lyrics}}
Corresponds to a voice with lyrics. Handles the printing of a
single line of lyrics.
-@unnumberedsubsubsec DrumVoice
+@strong{@emph{DrumVoice}}
The voice context used in a percussion staff.
-@unnumberedsubsubsec FiguredBass
+@strong{@emph{FiguredBass}}
The context in which BassFigure objects are created from
input entered in @code{\figuremode} mode.
-@unnumberedsubsubsec TabVoice
+@strong{@emph{TabVoice}}
The voice context used within a TabStaff context. Usually left to
be created implicitly.
-@unnumberedsubsubsec ChordNames
+@strong{@emph{ChordNames}}
Typesets chord names.
@menu
-* Navigating the program reference::
-* Layout interfaces::
-* Determining the grob property::
-* Naming conventions::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
@end menu
@node Navigating the program reference
@subsection Naming conventions
Another thing that is needed, is an overview of the various naming
-conventions:
+conventions:
scheme functions: lowercase-with-hyphens (incl. one-word
names)
@section Modifying properties
@menu
-* Overview of modifying properties::
-* The \set command::
-* The \override command::
-* \set versus \override::
-* Objects connected to the input::
+* Overview of modifying properties::
+* The \set command::
+* The \override command::
+* \set versus \override::
+* Objects connected to the input::
@end menu
@c TODO Add new subsection Shapes of objects
@c which would include Slur shapes
-@c with a Known issue: can't modify shapes if there are
+@c with a Known issue: can't modify shapes with 'control-points if there are
@c more than one at the same musical moment
@node Controlling visibility of objects
@subsection Controlling visibility of objects
-@c FIXME Write this section
+@cindex objects, visibility of
+@cindex grobs, visibility of
+@cindex visibility of objects
+
+There are four main ways in which the visibility of layout objects
+can be controlled: their stencil can be removed, they can be made
+transparent, they can be colored white, or their
+@code{break-visibility} property can be overridden. The first
+three apply to all layout objects; the last to just a few -- the
+@emph{breakable} objects. The Learning Manual introduces these
+four techniques, see @rlearning{Visibility and color of objects}.
+
+There are also a few other techniques which are specific to
+certain layout objects. These are covered under Special
+considerations.
+
+@menu
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
+@end menu
+
+
+@node Removing the stencil
+@unnumberedsubsubsec Removing the stencil
+
+@cindex stencil, removing
+
+Every layout object has a stencil property. By default this is set
+to the specific function which draws that object. If this property
+is overridden to @code{#f} no function will be called and the object
+will not be drawn. The default action can be recovered with
+@code{\revert}.
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\override Score.BarLine #'stencil = ##f
+a a
+\revert Score.BarLine #'stencil
+a a a
+@end lilypond
+
+@node Making objects transparent
+@unnumberedsubsubsec Making objects transparent
+
+@cindex transparent, making objects
+
+Every layout object has a transparent property which by default is
+set to @code{#f}. If set to @code{#t} the object still occupies
+space but is made invisible.
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \override NoteHead #'transparent = ##t
+a a
+@end lilypond
+
+@node Painting objects white
+@unnumberedsubsubsec Painting objects white
+
+@cindex objects, coloring
+@cindex coloring objects
+@cindex layers
+@cindex printing order
+@cindex overwriting objects
+@cindex objects, overwriting
+@cindex grobs, overwriting
+
+Every layout object has a color property which by default is set
+to @code{black}. If this is overridden to @code{white} the object
+will be indistinguishable from the white background. However,
+if the object crosses other objects the color of the crossing
+points will be determined by the order in which they are drawn,
+and this may leave a ghostly image of the white object, as shown
+here:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+a1
+@end lilypond
+
+This may be avoided by changing the order of printing the objects.
+All layout objects have a @code{layer} property which takes a real
+number. Objects with the lowest value of @code{layer} are drawn
+first, then objects with progressively higher values are drawn, so
+objects with higher values overwrite objects with lower values.
+By default most objects are assigned a @code{layer} value of
+@code{1}, although a few objects, including @code{StaffSymbol} and
+@code{BarLine}, are assigned a value of @code{0}. The order of
+printing objects with the same nominal value of @code{layer} is
+indeterminate.
+
+In the example above the white clef, with a default @code{layer}
+value of @code{1}, is drawn after the staff lines (default
+@code{layer} value @code{0}), so overwriting them. To change this,
+the @code{Clef} object must be given in a lower value of
+@code{layer}, say @code{-1}, so that it is drawn earlier:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+\override Staff.Clef #'layer = #-1
+a1
+@end lilypond
+
+@node Using break-visibility
+@unnumberedsubsubsec Using break-visibility
+
+@cindex break-visibility
+
+Most layout objects are printed only once, but some like
+bar lines, clefs, time signatures and key signatures, may need
+to be printed twice when a line break occurs -- once at the end
+of the line and again at the start of the next line. Such
+objects are called @emph{breakable}, and have a property, the
+@code{break-visibility} property to control their visibility
+at the three positions in which they may appear -- at the
+start of a line, within a line if they are changed, and at the
+end of a line if a change takes place there.
+
+For example, the time signature
+by default will be printed at the start of the first line, but
+nowhere else unless it changes, when it will be printed at the
+point at which the change occurs. If this change occurs at the
+end of a line the new time signature will be printed at the start
+of the next line and a cautionary time signature will be printed
+at the end of the previous line as well.
+
+This behaviour is controlled by the @code{break-visibility}
+property, which is explained in @rlearning{Visibility and color of
+objects}. This property takes a vector of three booleans which,
+in order, determine whether the object is printed at the end of,
+within the body of, or at the beginning of a line. Or to be more
+precise, before a line break, where there is no line break, or
+after a line break.
+
+Alternatively, seven of the eight combinations may be specified
+by pre-defined functions, defined in @file{scm/output-lib.scm},
+where the last three columns indicate whether the layout objects
+will be visible in the positions shown at the head of the columns:
+
+@multitable @columnfractions .40 .15 .15 .15 .15
+@c TODO check these more carefully
+@headitem Function @tab Vector @tab Before @tab At no @tab After
+@headitem form @tab form @tab break @tab break @tab break
+
+@item @code{all-invisible} @tab @code{'#(#f #f #f)} @ @ @tab no @tab no @tab no
+@item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
+@item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
+@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
+@c The center-visible function is not defined
+@c @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
+@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
+@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
+@item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
+@end multitable
+
+The @code{center-visible} function is not pre-defined.
+
+The default settings of @code{break-visibility} depend on the
+layout object. The following table shows all the layout objects
+of interest which are affected by @code{break-visibility} and the
+default setting of this property:
+
+@multitable @columnfractions .3 .3 .4
+
+@headitem Layout object @tab Usual context @tab Default setting
+
+@c omit Ambitus as it appears not to be affected by break-visibility -td
+@c @item @code{Ambitus} @tab as specified @tab @code{begin-of-line-visible}
+@item @code{BarLine} @tab @code{Score} @tab calculated
+@item @code{BarNumber} @tab @code{Score} @tab @code{begin-of-line-visible}
+@c omit the following item until it can be explained -td
+@c @item @code{BreakAlignGroup} @tab @code{Score} @tab calculated
+@item @code{BreathingSign} @tab @code{Voice} @tab @code{begin-of-line-invisible}
+@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
+@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
+@c omit KeyCancellation until it can be explained -td
+@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible}
+@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@c omit LeftEdge until it can be explained -td
+@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
+@item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible}
+@item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible}
+
+@end multitable
+
+The example below shows the use of the vector form to control the
+visibility of barlines:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+f4 g a b
+f4 g a b
+% Remove bar line at the end of the current line
+\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+Although all three components of the vector used to override
+@code{break-visibility} must be present, not all of them are
+effective with every layout object, and some combinations may
+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 OctavateEight -- see below
+@end itemize
+
+@node Special considerations
+@unnumberedsubsubsec Special considerations
+
+@strong{@emph{Visibility following explicit changes}}
+
+@cindex key signature, visibility following explicit change
+@cindex explicitKeySignatureVisibility
+@cindex clef, visibility following explicit change
+@cindex explicitClefVisibility
+
+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
+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
+to B-flat major is still visible, even though @code{all-invisible}
+is set.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+% Try to remove all key signatures
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+The visibility of such explicit key signature and clef changes is
+controlled by the @code{explicitKeySignatureVisibility} and
+@code{explicitClefVisibility} properties. These are the equivalent
+of the @code{break-visibility} property and both take a vector of
+three booleans or the predefined functions listed above, exactly like
+@code{break-visibility}. Both are properties of the Staff context,
+not the layout objects themselves, and so they are set using the
+@code{\set} command. Both are set by default to @code{all-visible}.
+These properties control only the visibility of key signatures and
+clefs resulting from explicit changes and do not affect key
+signatures and clefs at the beginning of lines;
+@code{break-visibility} must still be overridden in the appropriate
+object to remove these.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+@strong{@emph{Visibility of cautionary accidentals}}
+
+To remove the cautionary accidentals printed at an explicit key
+change, set the Staff context property @code{printKeyCancellation}
+to @code{#f}:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+With these overrides only the accidentals before the notes remain
+to indicate the change of key.
+
+@c TODO Add visibility of cautionary accidentals before notes
+
+@strong{@emph{Automatic bars}}
+
+@cindex automaticBars
+@cindex bar lines, suppressing
+
+As a special case, the printing of bar lines can also be turned off
+by setting the @code{automaticBars} property in the Score context.
+If set to @code{#f}, bar lines will not be printed automatically;
+they must be explicitly created with a @code{\bar} command. Unlike
+the @code{\cadenzaOn} predefined command, measures are still counted.
+Bar generation will resume according to that count if this property
+is later set to @code{#t}. When set to @code{#f}, line breaks can
+occur only at explicit @code{\bar} commands.
+
+@c TODO Add example
+
+@strong{@emph{Octavated clefs}}
+
+@cindex octavated clefs, visibility of
+@cindex visibility of octavated clefs
+@cindex clefs, visibility of octavation
+
+The small octavation symbol on octavated clefs is produced by the
+@code{OctavateEight} layout object. Its visibility is controlled
+independently from that of the @code{Clef} object, so it is
+necessary to apply any required @code{break-visibility} overrides
+to both the @code{Clef} and the @code{OctavateEight} layout objects
+to fully suppress such clef symbols at the start of each line.
+
+For explicit clef changes, the @code{explicitClefVisibility}
+property controls both the clef symbol and any octavation symbol
+associated with it.
+
+
+@seealso
+Learning Manual:
+@rlearning{Visibility and color of objects}
+
@node Line styles
@subsection Line styles
The information that determines the end-points is computed
on-the-fly for every graphic object, but it is possible to
-override these.
+override these.
@lilypond[relative=2,ragged-right,verbatim,fragment]
e2 \glissando f
left side with @code{left} instead of @code{right}.
If @code{Y} is not set, the value is computed from the vertical
-position of right attachment point of the spanner.
+position of right attachment point of the spanner.
In case of a line break, the values for the span-points are
extended with contents of the @code{left-broken} and
@code{right-broken} sublists, for example
@lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T
+\override Glissando #'breakable = ##T
\override Glissando #'bound-details #'right-broken #'Y = #-3
c1 \glissando \break
f1
@item X
This is the absolute coordinate of the end point. It is usually
-computed on the fly, and there is little use in overriding it.
+computed on the fly, and there is little use in overriding it.
@item stencil
Line spanners may have symbols at the beginning or end, which is
* Vertical grouping of grobs::
* Modifying ends of spanners::
* Modifying stencils::
+* Modifying shapes::
@end menu
@c FIXME Write this section
+@node Modifying shapes
+@subsection Modifying shapes
+
+@c FIXME Write this section
+@c Discussion of Bezier curves and the control-points property
@node Discussion of specific tweaks
@section Discussion of specific tweaks
projects / lilypond.git / commitdiff