From: Reinhold Kainhofer Date: Wed, 6 Aug 2008 21:05:59 +0000 (+0200) Subject: Merge branch 'master' of ssh://kainhofer@git.sv.gnu.org/srv/git/lilypond into dev... X-Git-Tag: release/2.11.58-1~32^2~80 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=455b90148f571c9f9a965b8d250c2dfdc115a7f6;hp=8800c721024c34ec50b54ca4c0cdf4ce4a82f56d;p=lilypond.git Merge branch 'master' of ssh://kainhofer@git.sv.gnu.org/srv/git/lilypond into dev/texi2html --- diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 1f92554435..b7a905254e 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -7,11 +7,12 @@ 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 @@ -121,7 +122,17 @@ further explanation and with links to the IR. @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 @@ -134,115 +145,118 @@ A Score context is instantiated implicitly when a 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. @@ -787,10 +801,10 @@ ossia = { f4 f f f } @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 @@ -1084,7 +1098,7 @@ Fingering_engraver is part of contexts: @dots{} @rinternals{Voice} @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) @@ -1108,11 +1122,11 @@ LP-specific? @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 @@ -1729,13 +1743,349 @@ restricted to a sub-set of the spanners. @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 @@ -1773,7 +2123,7 @@ d,2 \glissando d'2 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 @@ -1789,14 +2139,14 @@ right end point. Of course, it is also possible to adjust the 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 @@ -1821,7 +2171,7 @@ head it is attached to. @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 @@ -1913,6 +2263,7 @@ Internals Reference: @rinternals{TextSpanner}, * Vertical grouping of grobs:: * Modifying ends of spanners:: * Modifying stencils:: +* Modifying shapes:: @end menu @@ -1941,6 +2292,11 @@ VerticalAxisGroup. @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 diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely index 5bc88ae90f..5d8dd6ec00 100644 --- a/Documentation/user/spacing.itely +++ b/Documentation/user/spacing.itely @@ -1606,8 +1606,7 @@ Proportional notation is supported; see @ref{Proportional notation}. @seealso Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing}, -@rinternals{StaffSpacing}, @rinternals{SeparationItem}, and -@rinternals{SeparatingGroupSpanner}. +@rinternals{StaffSpacing}, and @rinternals{SeparationItem}. @knownissues diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely index 8d8925bd89..e59614f71a 100644 --- a/Documentation/user/tweaks.itely +++ b/Documentation/user/tweaks.itely @@ -1006,8 +1006,8 @@ We see from the properties specified in the @code{grob-interface} page in the IR that the @code{transparent} property is a boolean. This should be set to @code{#t} to make the grob transparent. -In this next example let us make the time signature invisible -rather than the bar lines. +In this next example let us make the time signature invisible +rather than the bar lines. To do this we need to find the grob name for the time signature. Back to the @q{All layout objects} page in the IR to find the properties @@ -1028,10 +1028,10 @@ transparent is: @end lilypond @noindent -The time signature is gone, but this command leaves a gap where +The time signature is gone, but this command leaves a gap where the time signature should be. Maybe this is what is wanted for -an exercise for the student to fill it in, but in other -circumstances a gap might be undesirable. To remove it, the +an exercise for the student to fill it in, but in other +circumstances a gap might be undesirable. To remove it, the stencil for the time signature should be set to @code{#f} instead: @@ -1053,8 +1053,16 @@ leaves it where it is, but makes it invisible. @subheading color @cindex color property -Finally we could make the bar lines invisible by coloring -them white. The @code{grob-interface} specifies that the +Finally let us try making the bar lines invisible by coloring +them white. (There is a difficulty with this in that the +white bar line may or may not blank out the staff lines where +they cross. You may see in some of the examples below that this +happens unpredictably. The details of why this is so and how to +control it are covered in @ruser{Painting objects white}. But at +the moment we are learning about color, so please just accept this +limitation for now.) + +The @code{grob-interface} specifies that the color property value is a list, but there is no explanation of what that list should be. The list it requires is actually a list of values in internal units, @@ -1080,7 +1088,7 @@ and again, we see the bar lines are not visible. Note that a symbol, but a @emph{function}. When called, it provides the list of internal values required to set the color to white. The other colors in the normal list are functions -too. To convince yourself this is working you might like +too. To convince yourself this is working you might like to change the color to one of the other functions in the list. @@ -1113,7 +1121,7 @@ an apostrophe and the two enclosed in brackets. There is yet a third function, one which converts RGB values into internal colors -- the @code{rgb-color} function. This takes -three arguments giving the intensities of the red, green and +three arguments giving the intensities of the red, green and blue colors. These take values in the range 0 to 1. So to set the color to red the value should be @code{(rgb-color 1 0 0)} and to white it should be @code{(rgb-color 1 1 1)}: diff --git a/lily/staff-symbol.cc b/lily/staff-symbol.cc index 6e376434ca..6fefc48010 100644 --- a/lily/staff-symbol.cc +++ b/lily/staff-symbol.cc @@ -170,8 +170,7 @@ Staff_symbol::height (SCM smob) bool Staff_symbol::on_line (Grob *me, int pos) { - Grob *st = Staff_symbol_referencer::get_staff_symbol (me); - SCM line_positions = st->get_property ("line-positions"); + SCM line_positions = me->get_property ("line-positions"); if (scm_is_pair (line_positions)) { Real min_line = HUGE_VAL; @@ -195,7 +194,7 @@ Staff_symbol::on_line (Grob *me, int pos) return false; } else - return ((abs (pos + line_count (st)) % 2) == 1); + return ((abs (pos + line_count (me)) % 2) == 1); } ADD_INTERFACE (Staff_symbol,