notation elements can overlap. This is unfortunate, but in fact
rather rare. Usually the need to move objects is for clarity or
aesthetic reasons -- they would look better with a little more
-space around them.
+or a little less space around them.
There are three main main approaches to resolving overlapping
notation. They should be considered in the following order:
repositioned easily in this way. The limitation is that you
have a choice of only two positions, and neither may be
suitable.
-@smallspace
@item
The @strong{object properties}, which LilyPond uses
-when positioning layout objects, may be modified using
+when positioning layout objects, may be modified using
@code{\override}. 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 override can apply to all instances of
the same type of object. Such properties include:
@itemize
-@smallspace
@item @code{direction}
This has already been covered in some detail -- see
@ref{Within-staff objects}.
-@smallspace
@item @code{padding}, @code{left-padding},
@code{right-padding}, @code{staff-padding}
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.
-@smallspace
+
@item @code{self-alignment-X}
@cindex self-alignment-X property
that contain text. The values are @code{LEFT}, @code{RIGHT}
or @code{CENTER}. The movement is limited by the length of the
object. Any numerical value between @code{-1} and @code{+1} may
-also be specified, where @code{-1} is left-aligned and @code{+1}
-is right-aligned.
-@smallspace
-@item @code{extra-spacing-width} property
+also be specified, where @code{-1} is left-aligned, @code{+1}
+is right-aligned, and numbers inbetween move the text progressively
+from left-aligned to right-aligned.
+
+@item @code{extra-spacing-width}
@cindex extra-spacing-width property
This property is available for all objects which support the
@code{item-interface}. It takes two numbers, the first is added
-to the leftmost extent and the second is added to the rightmost
+to the leftmost extent and the second is added to the rightmost
extent. Negative numbers move the edge to the left, positive to
-the right. Note that not all objects honour both numbers. For
-example, the @code{Accidental} object only takes notice of the
-first (left edge) number.
+the right, so to widen an object the first number must be negative,
+the second positive. Note that not all objects honour both
+numbers. For example, the @code{Accidental} object only takes
+notice of the first (left edge) number.
-@smallspace
@item @code{staff-position}
@cindex staff-position property
the vertical position of the object relative to the center line
of the staff in half staff-spaces. It is useful in resolving
collisions between layout objects like multi-measure rests, ties
-and notes in different voices.
+and notes in different voices.
+
+@item @code{force-hshift}
+
+@cindex force-hshift property
+
+TODO Move this explanation and add expanation of \shiftOn etc to
+ Explicitly instantiating voices section in Fundamental concepts
+
+[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 should be used in
+complex situations where the normal @code{\shiftOn} commands (see
+@ref{Explicitly instantiating voices}) do
+not resolve the note conflict. 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, and moving the notes
+into or out of a @code{NoteColumn} affects other actions such as
+merging noteheads.
@end itemize
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.
-@smallspace
@item
-Finally, when all else fails, objects may be repositioned
-vertically relative to the staff center line, or by
+Finally, when all else fails, objects may be manually repositioned
+relative to the staff center line verically, or by
displacing them by any distance to a new position. The
disadvantages are that the correct values for the repositioning
have to be worked out, often by trial and error, for every object
if the music is later modified. The properties that can be used
for this type of manual repositioning are:
@itemize
-@smallspace
@item @code{extra-offset}
@cindex extra-offset property
displacement is made after the typesetting of objects is
finished, so an object may be repositioned anywhere without
affecting anything else.
-@smallspace
-@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.
-@smallspace
@item @code{positions}
@cindex positions property
should be looked up in the IR in order to discover which properties
should be used to move them.
-@multitable @columnfractions .4 .6
+@multitable @columnfractions .5 .5
@headitem Object type @tab Object name
@item Articulations @tab @code{Script}
+@item Beams @tab @code{Beam}
@item Dynamics (vertically) @tab @code{DynamicLineSpanner}
@item Dynamics (horizontally) @tab @code{DynamicText}
@item Fingerings @tab @code{Fingering}
@item Slurs @tab @code{Slur}
@item Text e.g. @code{^"text"} @tab @code{TextScript}
@item Ties @tab @code{Tie}
+@item Tuplets @tab @code{TupletBracket}
@end multitable
@section Page layout
@menu
+* Introduction to layout::
+* Global sizes::
+* Line breaks::
+* Page breaks::
* Fitting music onto fewer pages::
@end menu
+@node Introduction to layout
+@subsection Introduction to layout
+
+The global paper layout is determined by three factors:
+the page layout, the line breaks, and the spacing. These all
+influence each other. The choice of spacing determines how
+densely each system of music is set. This influences where line
+breaks are chosen, and thus ultimately, how many pages a piece
+of music takes.
+
+Settings which influence layout may be placed in two blocks.
+The @code{\paper @{ ... @}} block is placed outside any
+@code{\score @{ ... @}} blocks and contains settings that
+relate to the entire document. The @code{\layout @{ ... @}}
+block is placed within a @code{\score @{ ... @}} block and
+contains settings for that particular score. If you have
+only one @code{\score @{ ... @}} block the two have the same
+effect. In general the commands shown in this section can
+be placed in either.
+
+Much more detail on the options for tweaking the laying out
+of music are contained in @ruser{Spacing issues}.
+
+@node Global sizes
+@subsection Global sizes
+
+The default @strong{paper size} which LilyPond assumes in laying
+out the music is A4. This may be changed in two ways:
+
+@example
+#(set-default-paper-size "a6")
+
+\paper @{
+#(set-paper-size "letter")
+@}
+@end example
+
+@noindent
+The first command sets the size of all pages. The second command
+sets the size of the pages to which the \paper block applies \96 if
+the \paper block is at the top of the file, then it will apply
+to all pages. Support for the following paper sizes are included:
+a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid).
+
+If the symbol @code{landscape} is supplied as an argument to
+@code{set-default-paper-size}, the pages will be rotated by 90
+degrees, and wider line widths will be set correspondingly, e.g.
+
+@example
+#(set-default-paper-size "a6" 'landscape)
+@end example
+
+The default @strong{staff size} is set to 20 points.
+This may be changed in two ways:
+
+@example
+#(set-global-staff-size 14)
+
+\paper @{
+#(set-global-staff-size 16)
+@}
+@end example
+
+@noindent
+The first command sets the size in all pages. The second command
+sets the size in the pages to which the \paper block applies \96 if
+the \paper block is at the top of the file, then it will apply
+to all pages. All the fonts are automatically scaled to suit
+the new value of the staff size.
+
+@node Line breaks
+@subsection Line breaks
+
+Line breaks are normally computed automatically. They are chosen
+so that lines look neither cramped nor loose, and that consecutive
+lines have similar density. Occasionally you might want to
+override the automatic breaks; you can do this by specifying
+@code{\break}. This will force a line break at this point. Line
+breaks can only occur at the end of @q{complete} bars, i.e., where
+there are no notes or tuplets left @q{hanging} over the bar line.
+If you want to have a line break where there is no bar line, you
+can force an invisible bar line by entering @code{\bar ""}.
+Similarly, @code{\noBreak} forbids a line break at a point.
+
+The most basic settings influencing line spacing are @code{indent}
+and @code{line-width}. They are set in the @code{\layout} block.
+They control the indentation of the first line of music, and the
+lengths of the lines.
+
+If @code{ragged-right} is set to true in the @code{\layout} block,
+then systems end at their natural horizontal length, instead of
+being spread horizontally to fill the whole line. This is useful
+for short fragments, and for checking how tight the natural
+spacing is.
+
+The option @code{ragged-last} is similar to @code{ragged-right},
+but only affects the last line of the piece.
+
+@example
+\layout @{
+indent = #0
+line-width = #150
+ragged-last = ##t
+@}
+@end example
+
+@node Page breaks
+@subsection Page breaks
+
+The default page breaking may be overriden by inserting
+@code{\pageBreak} or @code{\noPageBreak} commands.
+These commands are analogous to @code{\break} and @code{\noBreak}.
+These commands force and forbid a page-break from happening.
+Of course, the @code{\pageBreak} command also forces a line break.
+Like @code{\break}, the @code{\pageBreak} command is effective only
+at the end of a @q{complete} bar as defined above. For more
+details see @ruser{Page breaking} and following sections.
+
+There are also analogous settings to @code{ragged-right} and
+@code{ragged-last} which have the same effect on vertical spacing:
+@code{ragged-bottom} and @code{ragged-last-bottom}. If set to
+@code{##t} the systems on all pages or just the last page
+respectively are not justified vertically.
+
+For more details see @ruser{Vertical spacing}.
+
@node Fitting music onto fewer pages
@subsection Fitting music onto fewer pages
@ruser{Changing horizontal spacing}, for more details. Here's
an example first showing the default behaviour:
-@lilypond[verbatim,quote]
+@lilypond[verbatim,quote,ragged-right]
\score {
\relative c'' {
g4 e e2 |
value of @code{1/4} (a quarter note is the most common in this
example) to @code{1/2}:
-@lilypond[verbatim,quote]
+@lilypond[verbatim,quote,ragged-right]
\score {
\relative c'' {
g4 e e2 |
+
projects / lilypond.git / commitdiff