X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fspacing.itely;h=377a74ea1392fb6d13a8cf68799b679ed76f08d5;hb=e9a308e9c6002900fc336733950a0175bcbcc333;hp=aa4a6039b8f9f5fffc7f6f3dd914586e9377e050;hpb=b830aaa1d3cd6ffd437dad4afee5096ef33a4896;p=lilypond.git diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely index aa4a6039b8..377a74ea13 100644 --- a/Documentation/user/spacing.itely +++ b/Documentation/user/spacing.itely @@ -1,5 +1,11 @@ @c -*- coding: utf-8; mode: texinfo; -*- @c This file is part of lilypond.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore @c A menu is needed before every deeper *section nesting of @node's; run @c M-x texinfo-all-menus-update @@ -15,8 +21,8 @@ This influences where line breaks are chosen, and thus ultimately, how many pages a piece of music takes. Globally speaking, this procedure happens in four steps: first, -flexible distances (``springs'') are chosen, based on durations. All -possible line breaking combinations are tried, and a ``badness'' score +flexible distances (@q{springs}) are chosen, based on durations. All +possible line breaking combinations are tried, and a @q{badness} score is calculated for each. Then the height of each possible system is estimated. Finally, a page breaking and line breaking combination is chosen so that neither the horizontal nor the vertical spacing is too cramped @@ -29,6 +35,7 @@ or stretched. * Horizontal spacing:: * Breaks:: * Displaying spacing:: +* Vertical collision avoidance:: @end menu @@ -229,8 +236,8 @@ book and the title of a piece). Default is@tie{}2mm. @funindex printallheaders @item printallheaders -Setting this to #t will print all headers for each \score in a -\book. Normally only the piece and opus \headers are printed. +Setting this to #t will print all headers for each \score in the +output. Normally only the piece and opus \headers are printed. @funindex systemSeparatorMarkup @item systemSeparatorMarkup @@ -332,19 +339,20 @@ add space between the titles and the first system of the score. @section Music layout @menu -* Setting global staff size:: +* Setting the staff size:: * Score layout:: @end menu -@node Setting global staff size -@subsection Setting global staff size +@node Setting the staff size +@subsection Setting the staff size @cindex font size, setting @cindex staff size, setting @funindex layout file -To set the global staff size, use @code{set-global-staff-size}. +To set the staff size globally for all scores in a file (or +in a @code{book} block, to be precise), use @code{set-global-staff-size}. @example #(set-global-staff-size 14) @@ -354,6 +362,16 @@ To set the global staff size, use @code{set-global-staff-size}. This sets the global default size to 14pt staff height and scales all fonts accordingly. +To set the staff size individually for each score, use +@example +\score@{ + ... + \layout@{ + #(layout-set-staff-size 15) + @} +@} +@end example + The Feta font provides musical symbols at eight different sizes. Each font is tuned for a different staff size: at a smaller size the font becomes heavier, to match the relatively heavier staff lines. @@ -466,7 +484,6 @@ staves inside a system. @menu * Vertical spacing inside a system:: -* Vertical spacing of piano staves:: * Vertical spacing between systems:: * Controlling spacing of individual systems:: * Two-pass vertical spacing:: @@ -520,53 +537,6 @@ Example files: @inputfileref{input/regression/,page-spacing.ly}, @inputfileref{input/regression/,alignment-vertical-spacing.ly}. -@node Vertical spacing of piano staves -@subsection Vertical spacing of piano staves - -The distance between staves of a @internalsref{PianoStaff} cannot be -computed during formatting. Rather, to make cross-staff beaming work -correctly, that distance has to be fixed beforehand. - -The distance of staves in a @code{PianoStaff} is set with the -@code{forced-distance} property of the -@internalsref{VerticalAlignment} object, created in -@internalsref{PianoStaff}. - -It can be adjusted as follows -@example -\new PianoStaff \with @{ - \override VerticalAlignment #'forced-distance = #7 -@} @{ - ... -@} -@end example - -@noindent -This would bring the staves together at a distance of 7 staff spaces, -measured from the center line of each staff. - -The difference is demonstrated in the following example, -@lilypond[quote,verbatim] -\relative c'' << - \new PianoStaff \with { - \override VerticalAlignment #'forced-distance = #7 - } << - \new Staff { c1 } - \new Staff { c } - >> - \new PianoStaff << - \new Staff { c } - \new Staff { c } - >> ->> -@end lilypond - - -@seealso - -Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}. - - @node Vertical spacing between systems @subsection Vertical spacing between systems @@ -692,7 +662,7 @@ lilypond .ly @subsection Horizontal spacing overview The spacing engine translates differences in durations into stretchable -distances (``springs'') of differring lengths. Longer durations get +distances (@q{springs}) of differring lengths. Longer durations get more space, shorter durations get less. The shortest durations get a fixed amount of space (which is controlled by @code{shortest-duration-space} in the @internalsref{SpacingSpanner} @@ -814,6 +784,11 @@ c16[ c c8] @end lilypond +The @code{\newSpacingSection} command creates a new +@internalsref{SpacingSpanner} object, and hence new @code{\override}s +may be used in that location. + + @node Changing horizontal spacing @subsection Changing horizontal spacing @@ -822,7 +797,9 @@ Horizontal spacing may be altered with the we compare the same music; once without altering the property, and then altered. Larger values of @code{ly:make-moment} will produce smaller -music. +music. Note that @code{ly:make-moment} constructs +a duration, so @code{1 4} is a longer duration +than @code{1 16}. @lilypond[relative,verbatim,line-width=12\cm] \score { @@ -847,7 +824,7 @@ music. \context { \Score \override SpacingSpanner - #'base-shortest-duration = #(ly:make-moment 1 4) + #'base-shortest-duration = #(ly:make-moment 1 16) } } } @@ -1002,7 +979,7 @@ for details. @refbugs -Line breaks can only occur if there is a ``proper'' bar line. A note +Line breaks can only occur if there is a @q{proper} bar line. A note which is hanging over a bar line is not proper, such as @lilypond[quote,ragged-right,relative=2,fragment,verbatim] @@ -1100,8 +1077,8 @@ the absence of notes. This is so that single-staff polyphony with rests in one of the parts does not throw off the @code{Page_turn_engraver}). When it finds a sufficiently long section without notes, the @code{Page_turn_engraver} will insert an @code{\allowPageTurn} at the final barline in that section, unless -there is a ``special'' barline (such as a double bar), in which case the -@code{\allowPageTurn} will be inserted at the final ``special'' barline in +there is a @q{special} barline (such as a double bar), in which case the +@code{\allowPageTurn} will be inserted at the final @q{special} barline in the section. @funindex minimumPageTurnLength @@ -1170,3 +1147,76 @@ The pairs @var{b} the upper edge of the interval. +@node Vertical collision avoidance +@section Vertical collision avoidance + +@funindex outside-staff-priority +@funindex outside-staff-padding +@funindex outside-staff-horizontal-padding + +Intuitively, there are some objects in musical notation that belong +to the staff and there are other objects that should be placed outside +the staff. Objects belonging outside the staff include things such as +rehearsal marks, text and dynamic markings (from now on, these will +be called outside-staff objects). LilyPond's rule for the +vertical placement of outside-staff objects is to place them as close +to the staff as possible but not so close that they collide with +another object. + +LilyPond uses the @code{outside-staff-priority} property to determine +whether a grob is an outside-staff object: if @code{outside-staff-priority} +is a number, the grob is an outside-staff object. In addition, +@code{outside-staff-priority} tells LilyPond in which order the objects +should be placed. + +First, LilyPond places all the objects that do not belong outside +the staff. Then it sorts the outside-staff objects according to their +@code{outside-staff-priority} (in increasing order). One by one, LilyPond +takes the outside-staff objects and places them so that they do +not collide with any objects that have already been placed. That +is, if two outside-staff grobs are competing for the same space, the one +with the lower @code{outside-staff-priority} will be placed closer to +the staff. + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +c4_"Text"\pp +r2. +\once \override TextScript #'outside-staff-priority = #1 +c4_"Text"\pp % this time the text will be closer to the staff +r2. +% by setting outside-staff-priority to a non-number, we +% disable the automatic collision avoidance +\once \override TextScript #'outside-staff-priority = ##f +\once \override DynamicLineSpanner #'outside-staff-priority = ##f +c4_"Text"\pp % now they will collide +@end lilypond + +The vertical padding between an outside-staff object and the +previously-positioned grobs can be controlled with +@code{outside-staff-padding}. + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +\once \override TextScript #'outside-staff-padding = #0 +a'^"This text is placed very close to the note" +\once \override TextScript #'outside-staff-padding = #3 +c^"This text is padded away from the previous text" +c^"This text is placed close to the previous text" +@end lilypond + +By default, outside-staff objects are placed without regard to +their horizontal distance from the previously-posititioned grobs. This +can lead to situations in which objects are placed very close to each +other horizontally. Setting @code{outside-staff-horizontal-padding} +causes an object to be offset vertically so that such a situation +doesn't occur. + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +% the markup is too close to the following note +c2^"Text" +c''2 +% setting outside-staff-horizontal-padding fixes this +R1 +\once \override TextScript #'outside-staff-horizontal-padding = #1 +c,,2^"Text" +c''2 +@end lilypond