@c M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes
-@node Page settings
-@chapter Page settings
+@node Spacing issues
+@chapter Spacing issues
-This section deals with the presentation of output in pdf form.
+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.
+
+Globally spoken, this procedure happens in three steps: first,
+flexible distances (``springs'') are chosen, based on durations. All
+possible line breaking combinations are tried, and the one with the
+best results -- a layout that has uniform density and requires as
+little stretching or cramping as possible -- is chosen.
+
+After spacing and linebreaking, the systems are distributed across
+pages, taking into account the size of the page, and the size of the
+titles.
@menu
* Paper and pages::
* Music layout::
+* Vertical spacing::
+* Horizontal spacing::
+* Breaks::
+* Displaying spacing::
@end menu
@node Paper and pages
@section Paper and pages
-This section deals with the display of music on physical paper.
+This section deals with the boundaries that define the area
+that music can be printed inside.
@menu
* Paper size::
@cindex paper size
@cindex page size
-@findex papersize
+@funindex papersize
To change the paper size, there are two commands,
@example
LilyPond will do page layout, set margins, and add headers and
footers to each page.
-@findex annotate-spacing
-@cindex Spacing, display of properties
-
-To graphically display the dimensions of vertical properties
-that may be altered for page formatting, use
-
-@example
-\paper @{
- annotate-spacing = ##t
-@}
-@end example
-
-@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.
-
The default layout responds to the following settings in the
@code{\paper} block.
-@findex \paper
+@funindex \paper
@quotation
@table @code
-@findex first-page-number
+@funindex first-page-number
@item first-page-number
The value of the page number of the first page. Default is@tie{}1.
-@findex printfirst-page-number
+@funindex printfirst-page-number
@item printfirst-page-number
If set to true, will print the page number in the first page. Default is
false.
-@findex print-page-number
+@funindex print-page-number
@item print-page-number
If set to false, page numbers will not be printed.
-@findex paper-width
+@funindex paper-width
@item paper-width
The width of the page.
-@findex paper-height
+@funindex paper-height
@item paper-height
The height of the page.
-@findex top-margin
+@funindex top-margin
@item top-margin
Margin between header and top of the page.
-@findex bottom-margin
+@funindex bottom-margin
@item bottom-margin
Margin between footer and bottom of the page.
-@findex left-margin
+@funindex left-margin
@item left-margin
Margin between the left side of the page and the beginning of the music.
-@findex line-width
+@funindex line-width
@item line-width
The length of the systems.
-@findex head-separation
+@funindex head-separation
@item head-separation
Distance between the top-most music system and the page header.
-@findex foot-separation
+@funindex foot-separation
@item foot-separation
Distance between the bottom-most music system and the page footer.
-@findex page-top-space
+@funindex page-top-space
Distance from the top of the printable area to the center of the first
staff. This only works for staves which are vertically small. Big staves
are set with the top of their bounding box aligned to the top of the
printable area.
-@findex ragged-bottom
+@funindex ragged-bottom
@item ragged-bottom
If set to true, systems will not be spread vertically across the page. This
does not affect the last page.
This should be set to true for pieces that have only two or three
systems per page, for example orchestral scores.
-@findex ragged-last-bottom
+@funindex ragged-last-bottom
@item ragged-last-bottom
If set to false, systems will be spread vertically to fill the last page.
Pieces that amply fill two pages or more should have this set to
true.
-@findex system-count
+@funindex system-count
@item system-count
This variable, if set, specifies into how many lines a score should be
broken.
-@findex between-system-space
+@funindex between-system-space
@item between-system-space
This dimensions determines the distance between systems. It is the
ideal distance between the center of the bottom staff of one system
Increasing this will provide a more even appearance of the page at the
cost of using more vertical space.
-@findex between-system-padding
+@funindex between-system-padding
@item between-system-padding
This dimension is the minimum amount of white space that will always
be present between the bottom-most symbol of one system, and the
farther apart.
-@findex horizontal-shift
+@funindex horizontal-shift
@item horizontal-shift
All systems (including titles and system separators) are shifted by
this amount to the right. Page markup, such as headers and footers are
not affected by this. The purpose of this variable is to make space
for instrument names at the left.
-@findex after-title-space
+@funindex after-title-space
@item after-title-space
Amount of space between the title and the first system.
-@findex after-title-space
+@funindex after-title-space
@item before-title-space
Amount of space between the last system of the previous piece and the
title of the next.
-@findex between-title-space
+@funindex between-title-space
@item between-title-space
Amount of space between consecutive titles (e.g., the title of the
book and the title of a piece).
-@findex printallheaders
+@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.
-@findex systemSeparatorMarkup
+@funindex systemSeparatorMarkup
@item systemSeparatorMarkup
This contains a markup object, which will be inserted between
systems. This is often used for orchestral scores.
You can also define these values in Scheme. In that case @code{mm},
@code{in}, @code{pt}, and @code{cm} are variables defined in
-@file{paper-defaults.ly} with values in millimeters. That's why the
-value has to be multiplied in the example
+@file{paper-defaults.ly} with values in millimeters. That is why the
+value must be multiplied in the example
@example
\paper @{
@}
@end example
-@cindex copyright
-@cindex tagline
-
-The default footer is empty, except for the first page, where the
-@code{copyright} field from @code{\header} is inserted, and the last
-page, where @code{tagline} from @code{\header} is added. The default
-tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
-printed parts are good PR for us, so please leave the tagline if you
-can.}
-
The header and footer are created by the functions @code{make-footer}
and @code{make-header}, defined in @code{\paper}. The default
implementations are in @file{ly/@/paper@/-defaults@/.ly} and
@node Music layout
@section Music layout
-This section deals with the manner in which the music is printed
-within the boundaries defined by the @code{\paper} block.
-
-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.
-
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combinations are tried, and the one with the
-best results -- a layout that has uniform density and requires as
-little stretching or cramping as possible -- is chosen.
-
-After spacing and linebreaking, the systems are distributed across
-pages, taking into account the size of the page, and the size of the
-titles.
-
@menu
* Setting global staff size::
-* Selecting notation font size::
* Score layout::
-* Vertical spacing::
-* Vertical spacing of piano staves::
-* Horizontal spacing::
-* Line length::
-* Line breaking::
-* Page breaking::
@end menu
@cindex font size, setting
@cindex staff size, setting
-@findex layout file
+@funindex layout file
To set the global staff size, use @code{set-global-staff-size}.
This manual: @ref{Selecting notation font size}.
-@node Selecting notation font size
-@subsection Selecting notation font size
-
-The easiest method of setting the font size of any context, is by
-setting the @code{fontSize} property.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g
-@end lilypond
-
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
-
-Internally, the @code{fontSize} context property will cause the
-@code{font-size} property to be set in all layout objects. The value
-of @code{font-size} is a number indicating the size relative to the
-standard size for the current staff height. Each step up is an
-increase of approximately 12% of the font size. Six steps is exactly a
-factor two. The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\override NoteHead #'font-size = #-4
-c f
-\override NoteHead #'font-size = #3
-g
-@end lilypond
-
-LilyPond has fonts in different design sizes. The music fonts for
-smaller sizes are chubbier, while the text fonts are relatively wider.
-Font size changes are achieved by scaling the design size that is
-closest to the desired size. The standard font size (for
-@code{font-size} equals 0), depends on the standard staff height. For
-a 20pt staff, a 10pt font is selected.
-
-The @code{font-size} property can only be set on layout objects that
-use fonts. These are the ones supporting the
-@internalsref{font-interface} layout interface.
-
-@refcommands
-
-The following commands set @code{fontSize} for the current voice:
-
-@findex \tiny
-@code{\tiny},
-@findex \small
-@code{\small},
-@findex \normalsize
-@code{\normalsize}.
-
-
@node Score layout
@subsection Score layout
-@findex \layout
+@funindex \layout
While @code{\paper} contains settings that relate to the page formatting
of the whole document, @code{\layout} contains settings for score-specific
@node Vertical spacing
-@subsection Vertical spacing
+@section Vertical spacing
@cindex vertical spacing
+@cindex spacing, vertical
+
+Vertical spacing is controlled by three things: the amount of
+space available (i.e., paper size and margins), the amount of
+space between systems, and the amount of space between
+staves inside a system.
+
+@menu
+* Vertical spacing inside a system::
+* Vertical spacing of piano staves::
+* Vertical spacing between systems::
+* Controlling spacing of individual systems::
+@end menu
+
+
+@node Vertical spacing inside a system
+@subsection Vertical spacing inside a system
+
@cindex distance between staves
@cindex staff distance
-@cindex between staves, distance
-@cindex staves per page
@cindex space between staves
+@cindex space inside systems
The height of each system is determined automatically. To prevent
-systems from bumping into each other, some minimum distances are set.
-By changing these, you can put staves closer together, and thus put
-more systems onto one page.
+staves from bumping into each other, some minimum distances are set.
+By changing these, you can put staves closer together. This
+reduces the amount of space each system requires, and may result
+in having more systems per page.
Normally staves are stacked vertically. To make staves maintain a
distance, their vertical size is padded. This is done with the
This sets the vertical size of the current staff to 3 staff spaces on
either side of the center staff line. The value @code{(-3 . 3)} is
interpreted as an interval, where the center line is the 0, so the
-first number is generally negative. The staff can be made larger at
-the bottom by setting it to @code{(-6 . 4)}.
-
-The spacing of staves in a system may also be tuned per system. This is
-done with the command
-
-@example
-\overrideProperty
-#"Score.NonMusicalPaperColumn"
-#'line-break-system-details
-#'((alignment-extra-space . 15))
-@end example
-
-@noindent
-at the line break before the system to be changed. The distance
-@code{15} is distributed over all staves that have a fixed distance
-alignment. For example,
-
-@lilypond[ragged-right, fragment, relative=2, staffsize=13]
-\new StaffGroup <<
- \new Staff {
- c1\break
-
- \overrideProperty
- #"Score.NonMusicalPaperColumn"
- #'line-break-system-details
- #'((fixed-alignment-extra-space . 15))
-
- c\break
- }
- \new Staff { c c }
->>
-@end lilypond
-
-The distance for @code{alignment-extra-space} may also be negative.
+first number is generally negative. The numbers need not match;
+for example, the staff can be made larger at the bottom by setting
+it to @code{(-6 . 4)}.
-To change the amount of space between systems, use
-@code{between-system-space}. A score with only one staff is still
-considered to have systems, so setting @code{between-system-space} will
-be much more useful than changing @code{minimum-Y-extent} of a Staff
-context.
-
-@example
-\paper @{
- between-system-space = 10\mm
-@}
-@end example
-
-If you simply want to tell LilyPond ``fit as much as possible onto
-these pages, then expand to fill any available space on the pages,''
-then use the following
-
-@example
-\paper @{
- between-system-padding = #1
- ragged-bottom=##f
- ragged-last-bottom=##f
-@}
-@end example
-
-
-@c let's wait for a some comments before writing more.
-
-The vertical spacing on a page can also be changed for each system
-individually.
-Some examples are found in the example file
-@inputfileref{input/regression/,page-spacing.ly}.
-
-When setting @code{annotate-spacing} in the @code{\paper} block LilyPond
-will graphically indicate the dimensions of properties that may be set
-for page spacing,
-
-@lilypond[verbatim]
-#(set-default-paper-size "a7" 'landscape)
-\paper { annotate-spacing = ##t }
-{ c4 }
-@end lilypond
-
-@noindent
-All units dimensions are measured in staff spaces. The pairs
-(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
-@var{b} the upper edge of the interval.
-
@seealso
Internals: Vertical alignment of staves is handled by the
@internalsref{VerticalAlignment} object. The context parameters
-specifying the vertical extent are described in connection with
+specifying the vertical extent are described in connection with
the @internalsref{Axis_group_engraver}.
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
@end lilypond
+@seealso
+
+Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
+
+
+@node Vertical spacing between systems
+@subsection Vertical spacing between systems
+
+Space between systems are controlled by four @code{\paper} variables,
+
+@example
+\paper @{
+ between-system-space = 1.5\cm
+ between-system-padding = #1
+ ragged-bottom=##f
+ ragged-last-bottom=##f
+@}
+@end example
+
+
+@node Controlling spacing of individual systems
+@subsection Controlling spacing of individual systems
+
It is also possible to change the distance between for each system
individually. This is done by including the command
The distance for @code{fixed-alignment-extra-space} may also be
negative.
-@seealso
-Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
@node Horizontal spacing
-@subsection Horizontal Spacing
+@section Horizontal Spacing
+
+@cindex horizontal spacing
+@cindex spacing, horizontal
+
+@menu
+* Horizontal spacing overview::
+* Changing horizontal spacing::
+* Line length::
+@end menu
+
+
+@node Horizontal spacing overview
+@subsection Horizontal spacing overview
The spacing engine translates differences in durations into stretchable
distances (``springs'') of differring lengths. Longer durations get
this sets the base duration for spacing. The maximum duration for this
base (normally an 8th), is set through @code{base-shortest-duration}.
-@findex common-shortest-duration
-@findex base-shortest-duration
-@findex stem-spacing-correction
-@findex spacing
+@funindex common-shortest-duration
+@funindex base-shortest-duration
+@funindex stem-spacing-correction
+@funindex spacing
Notes that are even shorter than the common shortest note are
followed by a space that is proportional to their duration relative to
Proportional notation is supported; see @ref{Proportional notation}.
+
+@seealso
+
+Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
+@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
+@internalsref{SeparatingGroupSpanner}.
+
+
+@refbugs
+
+There is no convenient mechanism to manually override spacing. The
+following work-around may be used to insert extra space into a score.
+@example
+ \once \override Score.SeparationItem #'padding = #1
+@end example
+
+No work-around exists for decreasing the amount of space.
+
+
+@c FIXME: include this in 2.9; currently removed for 2.8 -gp
+@ignore
+@node New spacing area
+@subsection New spacing area
+
+New sections with different spacing parameters can be started with
+@code{newSpacingSection}. This is useful when there are
+sections with a different notions of long and short notes.
+
+In the following example, the time signature change introduces a new
+section, and hence the 16ths notes are spaced wider.
+
+@li lypond[relative,fragment,verbatim,quote]
+\time 2/4
+c4 c8 c
+c8 c c4 c16[ c c8] c4
+\newSpacingSection
+\time 4/16
+c16[ c c8]
+@e nd lilypond
+@end ignore
+
+@node Changing horizontal spacing
+@subsection Changing horizontal spacing
+
+Horizontal spacing may be altered with the
+@code{base-shortest-duration} property. Here
+we compare the same music; once without altering
+the property, and then altered. Larger values
+of @code{ly:make-moment} will produce smaller
+music.
+
+@lilypond[relative,verbatim,line-width=12\cm]
+\score {
+ \relative c'' {
+ g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ g4 e e2 | f4 d d2 | c4 e g g | c,1 |
+ d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
+ g4 e e2 | f4 d d2 | c4 e g g | c,1 |
+ }
+}
+@end lilypond
+
+@lilypond[relative,verbatim,line-width=12\cm]
+\score {
+ \relative c'' {
+ g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ g4 e e2 | f4 d d2 | c4 e g g | c,1 |
+ d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
+ g4 e e2 | f4 d d2 | c4 e g g | c,1 |
+ }
+ \layout {
+ \context {
+ \Score
+ \override SpacingSpanner
+ #'base-shortest-duration = #(ly:make-moment 1 4)
+ }
+ }
+}
+@end lilypond
+
+
+@commonprop
+
By default, spacing in tuplets depends on various non-duration
factors (such as accidentals, clef changes, etc). To disregard
such symbols and force uniform equal-duration spacing, use
@end lilypond
-@seealso
-
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
-
-@refbugs
-
-Spacing is determined on a score wide basis. If you have a score that
-changes its character (measured in durations) halfway during the
-score, the part containing the longer durations will be spaced too
-widely.
-
-There is no convenient mechanism to manually override spacing. The
-following work-around may be used to insert extra space into a score.
-@example
- \once \override Score.SeparationItem #'padding = #1
-@end example
-
-No work-around exists for decreasing the amount of space.
-
-
@node Line length
@subsection Line length
@cindex page breaks
@cindex breaking pages
-@findex indent
-@findex line-width
-@findex ragged-right
-@findex ragged-last
+@funindex indent
+@funindex line-width
+@funindex ragged-right
+@funindex ragged-last
@c Although line-width can be set in \layout, it should be set in paper
@c block, to get page layout right.
@end example
+@node Breaks
+@section Breaks
+
+@menu
+* Line breaking::
+* Page breaking::
+@end menu
+
@node Line breaking
@subsection Line breaking
@refcommands
@code{\break}, and @code{\noBreak}.
-@findex \break
-@findex \noBreak
+@funindex \break
+@funindex \noBreak
@seealso
@refcommands
-@findex \pageBreak
+@funindex \pageBreak
@code{\pageBreak}
-@findex \noPageBreak
+@funindex \noPageBreak
@code{\noPageBreak}
(@code{=""}) as in the example above, but it must be present.
+@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, use
+
+@lilypond[verbatim]
+\paper { annotate-spacing = ##t }
+{ c4 }
+@end lilypond
+
+@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.
+
+
projects / lilypond.git / blobdiff