@noindent
Now only the first slur is made heavier.
+
+The @code{\once} command can also be used before @code{\set}
+and @code{\unset}, and before the command to be introduced
+in the following section -- @code{revert}.
@subheading Reverting
}
@end lilypond
-@cindex revert
-@funindex \revert
-
@noindent
or we could omit the @code{\once} command and use the
@code{\revert} command
>>
@end lilypond
-
+@c TODO Mention somewhere, probably not here, how to avoid staves
+@c interleaving too much by specifying skyline-horizontal-padding
+@c Presumably this moves the skyline boundary further out, making
+@c objects appear wider? Not yet tested. -td
@node Within-staff objects
@subsection Within-staff objects
the direction of slurs, ties, fingering and
everything else which depends on the direction of the stems.
These commands are essential when writing polyphonic music to
-permit the interweaving melodic lines to be distinguished.
+permit interweaving melodic lines to be distinguished.
But occasionally it may be necessary to override this automatic
behaviour. This can be done for whole sections of music or even
-for an individual note. The property which control this
+for an individual note. The property which controls this
behaviour is the @code{direction} property of each layout object.
We first explain what this does, and then introduce a number of
ready-made commands which avoid your having to code explicit
right or left when they point up or down. This is controlled
automatically when @code{direction} is set.
-The following example shows first the default behaviour of stems,
+The following example shows in bar 1 the default behaviour of
+stems,
with those on high notes pointing down and those on low notes
pointing up, followed by four notes with all stems forced down,
four notes with all stems forced up, and finally four notes
@item \tupletDown
@tab \tupletUp
@tab \tupletNeutral
- @tab Tuplets below or above notes
+ @tab Tuplets are below/above notes
@end multitable
Note that these predefined commands may @strong{not} be
effect to a single note you must either use the equivalent
@code{\once \override} command or use the predefined command
followed after the affected note by the corresponding
-@code{\neutralXXX} command.
+@code{\xxxNeutral} command.
@subheading Fingering
@cindex fingering, placement
c-5 a-3 f-1 c'-5
@end lilypond
-This may be suitable for single notes, but the @code{direction}
+This is how to control fingering on single notes, but the
+@code{direction}
property is ignored for chords. Instead, by default, the
-fingering is placed both above and below the notes of a chord,
-as shown:
+fingering is automatically placed both above and below the
+notes of a chord, as shown:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
<c-5 g-3>
(if @code{right} appears). Conversely, if a location is not
listed, no fingering is placed there. LilyPond takes these
contraints and works out the best placement for the fingering
-for the notes of the following chords. Note that @code{left} and
+of the notes of the following chords. Note that @code{left} and
@code{right} are mutually exclusive -- fingering may be placed
only on one side or the other, not both.
\set fingeringOrientations = #'(right)
<f-2>
< c-1 e-2 g-3 b-5 > 4
-
@end lilypond
+@noindent
+If the fingering seems a little crowded the @code{font-size}
+could be reduced. The default value can be seen from the
+@code{Fingering} object in the IR to be @code{-5}, so let's
+try @code{-7}:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+\override Fingering #'font-size = #-7
+\set fingeringOrientations = #'(left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(up left down)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(up left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(right)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+@end lilypond
+
@node Outside staff objects
@subsection Outside staff objects
-TODO - dynamics, markup
- - Priority
- - \fatText
+Outside-staff objects are automatically placed to avoid collisions.
+Objects with the lower value of @code{outside-staff-priority}
+property are placed nearer to the staff, and other outside-staff
+objects are then raised as far as necessary to avoid collisions.
+The @code{outside-staff-priority} is defined in the
+@code{grob-interface} and so is a property of all layout objects.
+It is set to @code{#f} (the default) for all within-staff objects,
+and is set explicitly to the default numerical value appropriate
+to the each object as it is created. The following table shows
+the default numerical values for some of the commonest
+outside-staff objects. Others may be found in the object
+properties listed in the IR.
+
+@multitable @columnfractions .3 .3
+@headitem Layout Object @tab Priority
+@item @code{BarNumber} @tab @code{ 100}
+@item @code{DynamicLineSpanner} @tab @code{ 250}
+@item @code{DynamicText} @tab @code{ 250}
+@item @code{MetronomeMark} @tab @code{1000}
+@item @code{OttavaBracket} @tab @code{ 400}
+@item @code{RehearsalMark} @tab @code{1500}
+@item @code{TextScript} @tab @code{ 450}
+@end multitable
+
+TODO Add example showing iteraction of all these
+
+If this ordering does not give you the placing you want, the
+priority of the objects may be overridden. Suppose we would
+like @qq{Text3} to be placed above @qq{Text4} in the example
+under Automatic behaviour, above (see @ref{Automatic behaviour}).
+All we need to do is to look up the priority of @code{TextScript}
+in the IR or in the table above, and increase the priority of
+@qq{Text3} to a higher value:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+c2^"Text1"
+c^"Text2"
+\once \override TextScript #'outside-staff-priority = #500
+c^"Text3"
+c^"Text4"
+@end lilypond
+
+This certainly lifts @qq{Text3} above @qq{Text4} but it also
+lifts it above @qq{Text2}, and @qq{Text4} now drops down.
+Perhaps this is not so good. Can we instead position them all
+at the same distance from the staff? To do this, we clearly
+will need to space the notes out horizontally to make more
+room for the text. This is done using the @code{fatText}
+command.
+
+@subheading \fatText
+
+@funindex \fatText
+@cindex notes, spreading out with text
+
+By default, text produced by markup takes up no horizontal space
+as far as laying out the music is concerned. The @code{\fatText}
+command reverses this behaviour, causing the notes to be spaced
+out as far as is necessary to accommodate the text:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\fatText % Cause notes to space out to accommodate text
+c2^"Text1"
+c^"Text2"
+c^"Text3"
+c^"Text4"
+@end lilypond
+
+The command to revert to the default behaviour is
+@code{\emptyText}. Remember @code{\once} only works with
+@code{\override}, @code{\set}, @code{\revert} or @code{unset},
+so cannot be used with @code{\fatText}.
+
+Markup text will also avoid notes which project above the staff.
+If this is not desired, the automatic displacement upwards may
+be turned off by setting the priority to @code{#f}. Here's an
+example to show how markup text interacts with such notes.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+% This markup is short enough to fit without collision
+c2^"Tex"
+c''2
+R1
+% This is too long to fit, so it is displaced upwards
+c,,2^"Text"
+c''2
+R1
+% Turn off collision avoidance
+\once \override TextScript #'outside-staff-priority = ##f
+c,,2^"Long Text "
+c''2
+R1
+% Turn off collision avoidance
+\once \override TextScript #'outside-staff-priority = ##f
+\fatText % and turn on fatText
+c,,2^"Long Text " % Spaces at end are honoured
+c''2
+@end lilypond
+
+
+@subheading Dynamics
+
+Dynamic markings will normally be positioned beneath the
+staff, but may be positioned above with the @code{dynamicUp}
+command. They will be positioned vertically relative to the
+note to which they are attached, and will float below (or above)
+all within-staff objects such as phrasing slurs and bar numbers.
+This can give quite acceptable results, as this example
+shows:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+\clef "bass"
+\key aes \major
+\time 9/8
+\dynamicUp
+bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
+ees,2.~\)\mf ees4 r8 |
+@end lilypond
+
+However, if the notes and attached dynamics are close
+together the automatic placement will avoid collisions
+by displacing later dynamic markings further away, but this may
+not be the optimum placement, as this rather artificial example
+shows:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\dynamicUp
+a4\f b\mf c\mp b\p
+@end lilypond
+
+@noindent
+Should a similar situation arise in @q{real} music, it may
+be preferable to space out the notes
+a little further, so the dynamic markings can all fit at the
+same vertical distance from the staff. We were able to do this
+for markup text by using the @code{\fatText} command, but there
+is no equivalent command for dynamic marks. So we shall have to
+work out how to do this using @code{\override} commands.
+
+@subheading Grob sizing
+
+@cindex grob sizing
+@cindex sizing grobs
+@cindex @code{X-offset}
+@cindex @code{Y-offset}
+@cindex @code{X-extent}
+@cindex @code{Y-extent}
+
+First we must learn how grobs are sized. All grobs have a
+reference point defined within them which is used to position
+them relative to their parent object. This point in the grob
+is then positioned at a horizontal distance, @code{X-offset},
+and at a vertical distance, @code{Y-offset}, from its parent.
+The horizontal extent of the object is given by a pair of
+numbers, @code{X-extent}, which say where the left and right
+edges are relative to the reference point. The vertical extent
+is similarly defined by a pair of numbers, @code{Y-extent}.
+These are properties of all grobs which support the
+@code{grob-interface}.
+
+@cindex @code{extra-spacing-width}
+
+By default, outside-staff objects are given a width of zero so
+that they may overlap in the horizontal direction. This is done
+by by the trick of adding infinity to the leftmost extent and
+minus infinity to the rightmost extent by setting the
+@code{extra-spacing-width} to @code{'(+inf.0 . -inf.0)}. So
+to ensure they do not overlap in the horizontal direction we
+must override this value of @code{extra-spacing-width} to
+@code{'(0 . 0)} so the true width shines through. This is
+the command to do this for dynamic text:
+
+@example
+\override DynamicText #'extra-spacing-width = #'(0 . 0)
+@end example
+
+@noindent
+Let's see if this works in our previous example:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\dynamicUp
+\override DynamicText #'extra-spacing-width = #'(0 . 0)
+a4\f b\mf c\mp b\p
+@end lilypond
+
+@noindent
+Well, it has certainly stopped the dynamic marks being
+displaced, but two problems remain. The marks should be
+spaced a little further apart and it would be better
+if they were all the same distance from the staff.
+We can solve the first problem easily. Instead of making
+the @code{extra-spacing-width} zero we could add a little
+more to it. The units are the space between two staff
+lines, so moving the left edge half a unit to the left and the
+right edge half a unit to the right should do it:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\dynamicUp
+% Extend width by 1 staff space
+\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
+a4\f b\mf c\mp b\p
+@end lilypond
+
+@noindent
+This looks better, but maybe we would prefer the dynamic marks
+to be aligned along the same baseline rather than going up and
+down with the notes. There is a property to control this, but
+it is not so easy to find in the IR. It is not a property of
+@code{DynamicText} but of @code{DynamicLineSpanner}.
+This is because the baseline should apply equally to @strong{all}
+dynamics, including those created as extended spanners.
+So this is the way to align the dynamic marks in our example:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\dynamicUp
+% Extend width by 1 unit
+\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
+% Align dynamics to a base line 2 units above staff
+\override DynamicLineSpanner #'staff-padding = #2
+a4\f b\mf c\mp b\p
+@end lilypond
@node Moving objects
@subsection Moving objects
-This may come as a surprise, but LilyPond is not perfect. Some notation
-elements can overlap. This is unfortunate, but (in most cases) is easily
-solved.
+This may come as a surprise, but LilyPond is not perfect. Some
+notation elements can overlap. This is unfortunate, but in fact
+rather rare. Usually the need to move objects is or clarity or
+aesthetic reasons -- they would look better with a little more
+space around them.
+
+There are three main main approaches to resolving overlapping
+notation. They should be considered in the following order:
-TODO: with the new spacing features in 2.12, these specific examples are no
-longer relevant. However, they still demonstrate powerful features
-of lilypond, so they remain until somebody creates some better examples.
+@itemize @bullet
+@item
+The @strong{direction} of one of the overlapping objects may
+be changed using the predefined commands listed above for
+within-staff objects (see @ref{Within-staff objects}).
+Stems, slurs, beams, ties, dynamics, text and tuplets may be
+repositioned easily in this way. The limitation is that you
+have a choice of only two positions, and neither may be
+suitable.
+
+@item
+The @strong{object properties} taken into account by LilyPond
+when positioning the objects may be modified. The advantages
+of making changes to this type of property are (a) that some
+other objects will be moved automatically if necessary to make
+room and (b) the single change can apply to all instances of
+the same type of object. Such properties include:
+
+@itemize @minus
+@item @code{direction}
+@item @code{left-padding}
+@item @code{padding}
+@item @code{right-padding}
+@item @code{self-alignment}
+
+Objects do not all have all of these properties in general.
+It is necessary to go to the IR to look up which properties
+are available for the object in question.
+
+@end itemize
+
+@item
+Finally, when all else fails, objects may be repositioned manually
+by changing their separation distance from other objects, or by
+repositioning them relative to the staff center line. The
+disadvantage is that the correct values for the repositioning have
+to be worked out, often by trial and error, for every object
+individually. The properties that can be used for this type of
+repositioning are:
+
+@itemize @minus
+@item @code{extra-offset}
+
+@cindex extra-offset property
+
+This property applies to any layout object
+supporting the @code{grob-interface}. It takes a pair of
+numbers giving the extra displacement in the horizontal and
+vertical directions. Negative numbers move the object to
+the left and down. The units are staff-spaces. The extra
+displacement is made after the typesetting of objects is
+finished, so an object may be repositioned anywhere without
+affecting anything else.
+
+@item @code{force-hshift}
+
+@cindex force-hshift property
+
+Closely spaced notes in a chord, or notes occuring at the same
+time in different voices, are arranged in two, occasionally more,
+columns to prevent the noteheads overlapping. These are called
+note columns, and an object called @code{NoteColumn} is created
+to lay out the notes in that column. There are separate columns
+for each voice. The @code{force-hshift}
+property is a property of a @code{NoteColumn} (actually of the
+@code{note-column-interface}). Changing it permits a note column
+to be moved in units appropriate to a note column, viz. the note
+head width of the first voice note. It is preferable to the
+@code{extra-offset} property for this purpose as there is no need
+to work out the distance in staff-spaces.
+
+@item @code{positions}
+
+@cindex positions property
+
+This is most useful for manually adjusting the slope and height
+of beams, ties, slurs, and tuplets. It takes a pair of numbers
+giving the position of the left and right ends of the beam, slur,
+etc. relative to the center line of the staff. Units are
+staff-spaces.
+
+
+@item @code{staff-position}
+
+@cindex staff-position property
+
+@code{staff-position} is a property of the
+@code{staff-symbol-referencer-interface}, which is supported by
+objects which are positioned relative to the staff. It specifies
+the vertical position of the object relative to the center line
+of the staff in half staff-spaces.
+
+@end itemize
+
+@end itemize
+
+Let us examine some of these approaches in more detail.
+
+@subheading padding
+@cindex padding
+
+When objects are being placed they are positioned so
+that a gap given by the value of the appropriate padding property
+is left between the edge of the object being placed and the edge
+of the previously placed object.
+The layout property which controls spacing is called
+@code{padding}. It specifies the gap that must be left between
+the top and bottom edges of objects which are positioned
+either above or below another previously placed object, or
+between the sides of objects which are positioned to the left or
+right of previously placed objects.
+Instead of @code{padding} some objects have instead a
+@code{left-padding} or @code{right-padding} property.
+All padding values are measured in staff spaces. For most
+objects, this value is set by default to be around 1.0 or less
+(it varies with each object). It may be overridden if a larger
+(or smaller) gap is required.
+
+To discover which padding property is required for the object
+you wish to reposition, you
+need to return to the IR and look up the object's properties.
+Be aware that the padding property might not be located in the
+obvious object. For example, the placement of accidentals is
+controlled by @code{left-padding} and @code{right-padding},
+but these are to be found in the @code{AccidentalPlacement}
+object.
+
+Here's an example.
+
+Let's try the effect of @code{padding} on the rather artificial
+example above. This is a property of
+@code{DynamicLineSpanner}, not @code{DynamicText}.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
- % temporary code to break this example:
- \override TextScript #'outside-staff-priority = ##f
-e4^\markup{ \italic ritenuto } g b e
+\dynamicUp
+% Increase vertical padding by 5 units
+\override DynamicLineSpanner #'padding = #'5
+a4\f b\mf c\mp b\p
@end lilypond
-@cindex padding
+Dynamics are positioned vertically with respect to the note to
+which they are attached. We see that this has moved all the
+dynamics up by five staff spaces, but has had no effect on the
+horizontal separation, nor on the placement of the dynamics
+relative to each other.
+
+
+@subheading extra-offset
-The easiest solution is to increase the distance between the object
-(in this case text, but it could easily be fingerings or dynamics
-instead) and the note. In LilyPond, this is called the
-@code{padding} property; it is measured in staff spaces. For most
-objects, this value is around 1.0 or less (it varies with each
-object). We want to increase it, so let's try 1.5
+
+
+TODO To be continued ....
+
+TODO Old stuff follows
+
+ We want to increase it, so let's try 1.5
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
% temporary code to break this example:
+
+
projects / lilypond.git / commitdiff