@menu
* Paper and pages::
* Music layout::
+* Displaying spacing::
* Breaks::
* Vertical spacing::
* Horizontal spacing::
-* Displaying spacing::
-* Vertical collision avoidance::
@end menu
This manual: @ref{Changing context default settings}
+@node Displaying spacing
+@section Displaying spacing
+
+@funindex annotate-spacing
+@cindex Spacing, display of properties
+
+To graphically display the dimensions of vertical properties that may
+be altered for page formatting, set @code{annotate-spacing} in the
+@code{\paper} block, like this
+
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6" 'landscape)
+
+\book {
+ \score { { c4 } }
+ \paper { annotate-spacing = ##t }
+}
+@end lilypond
+
+@c need to have \book{} otherwise we get the separate systems. -hwn
+
+@noindent
+@c FIXME: really bad vagueness due to bug in annotate-spacing. -gp
+Some unit dimensions are measured in staff spaces, while others
+are measured in millimeters.
+The pairs
+(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
+@var{b} the upper edge of the interval.
+
+
@node Breaks
@section Breaks
* Vertical spacing between systems::
* Explicit staff and system positioning::
* Two-pass vertical spacing::
+* Vertical collision avoidance::
@end menu
lilypond <file>.ly
@end example
+
+@node Vertical collision avoidance
+@subsection 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
+
+
+
@node Horizontal spacing
@section Horizontal Spacing
* New spacing area::
* Changing horizontal spacing::
* Line length::
+* Proportional notation::
@end menu
@end example
-@node Displaying spacing
-@section Displaying spacing
+@node Proportional notation
+@subsection Proportional notation
-@funindex annotate-spacing
-@cindex Spacing, display of properties
+LilyPond supports proportional notation, a type of horizontal spacing
+in which each note consumes an amount of horizontal space exactly
+equivalent to its rhythmic duration. This type of proportional spacing
+is comparable to horizontal spacing on top of graph paper. Some late
+20th- and early 21st-century scores use proportional notation to
+clarify complex rhythmic relationships or to faciliate the placement
+of timelines or other graphics directly in the score.
-To graphically display the dimensions of vertical properties that may
-be altered for page formatting, set @code{annotate-spacing} in the
-@code{\paper} block, like this
+LilyPond supports five different settings for proportional notation,
+which may be used together or alone:
+@itemize
+proportionalNotationDuration
+uniform-stretching
+strict-note-spacing
+\remove Separating_line_group_engraver
+\override PaperColumn #'used = ##t
+@end itemize
-@lilypond[verbatim]
-#(set-default-paper-size "a6" 'landscape)
+In the examples that follow, we explore these five different
+proportional notation settings and examine how these settings interact.
-\book {
- \score { { c4 } }
- \paper { annotate-spacing = ##t }
-}
+We start with the following one-measure example, which uses classical
+spacing with ragged-right turned on.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Score <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+>>
@end lilypond
-@c need to have \book{} otherwise we get the separate systems. -hwn
+Notice that the half note which begins the measure takes up far less
+than half of the horizontal space of the measure. Likewise, the
+sixteenth notes and sixteenth-note quintuplets (or twentieth notes)
+which end the measure together take up far more than half the
+horizontal space of the measure.
-@noindent
-@c FIXME: really bad vagueness due to bug in annotate-spacing. -gp
-Some unit dimensions are measured in staff spaces, while others
-are measured in millimeters.
-The pairs
-(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
-@var{b} the upper edge of the interval.
+In classical engraving, this spacing may be exactly what we want
+because we can borrow horizontal space from the half note and conserve
+horizontal space across the measure as a whole.
+On the other hand, if we want to insert a measured timeline or other
+graphic above or below our score, we need proportional notation. We
+turn proportional notation on with the proportionalNotationDuration
+setting.
-@node Vertical collision avoidance
-@section Vertical collision avoidance
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+} <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+>>
+@end lilypond
-@funindex outside-staff-priority
-@funindex outside-staff-padding
-@funindex outside-staff-horizontal-padding
+The half note at the beginning of the measure and the faster notes in
+the second half of the measure now occupy equal amounts of horizontal
+space. We could place a measured timeline or graphic above or below
+this example.
+
+The @code{proportionalNotationDuration} setting is a context setting that
+lives in @context{Score}. Recall that context settings appear in one of
+three locations in our input file -- in a @code{\with} block, in a
+@code{\context} block, or directly in music entry
+preceeded by the @code{\set} command. As with all
+context settings, users can pick which of the three different
+locations they would like to set @code{proportionalNotationDuration}.
+
+The @code{proportionalNotationDuration} setting takes a single argument,
+which is the reference duration against which all music will be
+spaced. The LilyPond Scheme function make-moment takes two arguments
+-- a numerator and denominator which together express some fraction of
+a whole note. The call @code{#(ly:make-moment 1 20)} therefore produces a
+reference duration of a twentieth note. The values
+@code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
+@code{#(ly:make-moment 3 97)} are all possible as well.
+
+How do we select the right reference duration to pass to
+@code{proportionalNotationDuration}? Usually by a process of trial and error,
+beginning with a duration close to the fastest (or smallest) duration
+in the piece. Smaller reference durations space music loosely; larger
+reference durations space music tightly.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 8)
+} <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+>>
-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.
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 16)
+} <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+>>
-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.
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 32)
+} <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+>>
+@end lilypond
-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.
+Note that too large a reference duration -- such as the eighth note,
+above -- spaces music too tightly and can cause notehead collisions.
+Note also that proportional notation in general takes up more
+horizontal space that does classical spacing. Proportional spacing
+provides rhythmic clarity at the expense of horizontal space.
-@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
+Next we examine how to optimally space overlapping tuplets.
+
+We start by examining what happens to our original example, with
+classical spacing, when we add a second staff with a different type of
+tuplet.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Score <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ \new RhythmicStaff {
+ \times 8/9 {
+ c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ }
+ }
+>>
@end lilypond
-The vertical padding between an outside-staff object and the
-previously-positioned grobs can be controlled with
-@code{outside-staff-padding}.
+The spacing is bad because the evenly notes of the bottom staff do not
+stretch uniformly. Classical engraving includes very few complex
+triplets and so classical engraving rules can generate this type of
+result. Setting @code{proportionalNotationDuration} remedies this
+situation considerably.
-@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"
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+} <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ \new RhythmicStaff {
+ \times 8/9 {
+ c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ }
+ }
+>>
@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.
+But if we look very carefully we can see that notes of the second half
+of the 9-tuplet space ever so slightly more widely than do the notes
+of the first half of the 9-tuplet. To ensure uniform stretching, we
+turn on @code{uniform-stretching}, which is a property of
+@code{SpacingSpanner}.
-@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
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+ \override SpacingSpanner #'uniform-stretching = ##t
+} <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ \new RhythmicStaff {
+ \times 8/9 {
+ c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ }
+ }
+>>
@end lilypond
+
+Our two-staff example now spaces exactly, our rhythmic relationships
+are visually clear, and we can include a measured timeline or graphic
+if we want.
+
+The @code{SpacingSpanner} is an abstract grob that lives in the
+@context{Score} context. As with our settings of
+@code{proportionalNotationDuration},
+overrides to the @code{SpacingSpanner} can occur in any of three different
+places in our input file -- in the Score @code{\with} block, in a
+Score @code{\context} block, or in note entry directly.
+
+There is by default only one @code{SpacingSpanner} per @code{Score}. This
+means that, by default, @code{uniform-stretching} is either turned on for the
+entire score or turned off for the entire score. We can, however,
+override this behavior and turn on different spacing features at
+different places in the score. We do this with the command
+@code{\newSpacingSection}. See @ref{New spacing area} for more info.
+
+@c zzz
+
projects / lilypond.git / commitdiff