@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
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
* Horizontal spacing::
* Breaks::
* Displaying spacing::
+* Vertical collision avoidance::
@end menu
@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
@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)
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.
@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}
@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
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 {
\context {
\Score
\override SpacingSpanner
- #'base-shortest-duration = #(ly:make-moment 1 4)
+ #'base-shortest-duration = #(ly:make-moment 1 16)
}
}
}
@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]
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
@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