From: Graham Percival Date: Mon, 4 Feb 2008 12:23:20 +0000 (-0800) Subject: Update from Trevor, and move Page layout stuff into Spacing. X-Git-Tag: release/2.11.39-1~1^2~16^2 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=4344279f11dd8ac9b694c6251081e35348f34e16;p=lilypond.git Update from Trevor, and move Page layout stuff into Spacing. --- diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely index 03bcc9b717..2d6136abf2 100644 --- a/Documentation/user/spacing.itely +++ b/Documentation/user/spacing.itely @@ -35,6 +35,7 @@ or stretched. * Breaks:: * Vertical spacing:: * Horizontal spacing:: +* Page layout MOVED FROM LM:: @end menu @@ -563,7 +564,7 @@ The pairs * Page breaking:: * Optimal page breaking:: * Optimal page turning:: -* Minimal page breaking:: +* Minimal page breaking:: * Explicit breaks:: * Using an extra voice for breaks:: @end menu @@ -2051,3 +2052,262 @@ to break across systems and pages. See the respective parts of the manual for these related settings. + +@node Page layout MOVED FROM LM +@section Page layout MOVED FROM LM + +@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 + +TODO Check all these examples + +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 -- if +the \paper block is at the top of the file, then it will apply +to all pages. Support for the following paper sizes is available: +a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid). +Setting the paper size automatically sets suitable margins and +line length. + +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 -– 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 determined automatically. They are chosen +so that lines look neither cramped nor loose, and 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. However, +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 ""}, +although again there must be no notes left hanging over in any of +the staves at this point, or it will be ignored. + +The opposite command, @code{\noBreak}, forbids a line break at the +bar line where it is inserted. + +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 affects only 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 the @code{\break} and +@code{\noBreak} commands discused above and force or forbid +a page-break at the point where they are inserted. +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 will not be justified vertically. + +For more details see @ruser{Vertical spacing}. + +@node Fitting music onto fewer pages +@subsection Fitting music onto fewer pages + +Sometimes you can end up with one or two staves on a second +(or third, or fourth...) page. This is annoying, especially +if you look at previous pages and it looks like there is plenty +of room left on those. + +When investigating layout issues, @code{annotate-spacing} is +an invaluable tool. This command prints the values of various +layout spacing commands; see @ruser{Displaying spacing}, for more +details. From the output of @code{annotate-spacing}, we can +see which margins we may wish to alter. + +Other than margins, there are a few other options to save space: + +@itemize +@item +You may tell LilyPond to place systems as close together as +possible (to fit as many systems as possible onto a page), but +then to space those systems out so that there is no blank +space at the bottom of the page. + +@example +\paper @{ + between-system-padding = #0.1 + between-system-space = #0.1 + ragged-last-bottom = ##f + ragged-bottom = ##f +@} +@end example + +@item +You may force the number of systems (i.e., if LilyPond wants +to typeset some music with 11 systems, you could force it to +use 10). + +@example +\paper @{ + system-count = #10 +@} +@end example + +@item +Avoid (or reduce) objects which increase the vertical size of +a system. For example, volta repeats (or alternate repeats) +require extra space. If these repeats are spread over two +systems, they will take up more space than one system with +the volta repeats and another system without. + +Another example is moving dynamics which @q{stick out} of +a system, as in the second bar here: + +@lilypond[verbatim,quote,fragment,ragged-right,relative=1] +e4 c g\f c +\override DynamicText #'extra-offset = #'( -2.2 . 2.0) +e4 c g\f c +@end lilypond + +@item +Alter the horizontal spacing via @code{SpacingSpanner}. See +@ruser{Changing horizontal spacing}, for more details. Here's +an example first showing the default behaviour: + +@lilypond[verbatim,quote,ragged-right] +\score { + \relative c'' { + g4 e e2 | + f4 d d2 | + c4 d e f | + g4 g g2 | + g4 e e2 | + } +} +@end lilypond + +@noindent +and now with @code{common-shortest-duration} increased from the +value of @code{1/4} (a quarter note is the most common in this +example) to @code{1/2}: + +@lilypond[verbatim,quote,ragged-right] +\score { + \relative c'' { + g4 e e2 | + f4 d d2 | + c4 d e f | + g4 g g2 | + g4 e e2 | + } + \layout { + \context { + \Score + \override SpacingSpanner + #'common-shortest-duration = #(ly:make-moment 1 2) + } + } +} +@end lilypond + +@noindent +Note that this override cannot be modified dynamically, so it must +always be placed in a @code{\context@{..@}} block so that it applies +to the whole score. + +TODO Add description of using \context in this way earlier if it is +not already anywhere -td + +@end itemize + + + diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely index a30cbd6d1b..c35303a3a0 100644 --- a/Documentation/user/tweaks.itely +++ b/Documentation/user/tweaks.itely @@ -24,7 +24,6 @@ not yet complete. Don't translate yet! * Appearance of objects:: * Placement of objects:: * Collisions of objects:: -* Page layout:: * Further tweaking:: @end menu @@ -723,7 +722,21 @@ let us suppose the exercise is to supply the missing bar lines in a piece of music. But the bar lines are normally inserted automatically. How do we prevent them printing? -As before, we go to the IR to find the layout object which prints +Before we tackle this, let us remember that object properties +are grouped in what are called @emph{interfaces} -- see +@ref{Properties found in interfaces}. This is simply to +group together those properties that are commonly required +together -- if one of them is required for an object, so are +the others. Some objects then need the properties in some +interfaces, others need them from other interfaces. The +interfaces which contain the properties required by a +particular grob are listed in the IR at the bottom of the +page describing that grob, and those properties may be +viewed by looking at those interfaces. + +We explained how to find information about grobs in +@ref{Properties of layout objects}. Using the same approach, +we go to the IR to find the layout object which prints bar lines. Going via @emph{Backend} and @emph{All layout objects} we find there is a layout object called @code{BarLine}. Its properties include @@ -735,6 +748,8 @@ of these can affect the visibility of bar lines (and, of course, by extension, many other layout objects too.) Let's consider each of these in turn. +@c FIXME: is this what you meant? +@c TODO Change all other headings like this @subheading stencil @cindex stencil property @@ -1522,13 +1537,22 @@ the default numerical values for some of the commonest outside-staff objects which are, by default, placed in the @code{Staff} Context. -@multitable @columnfractions .3 .3 -@headitem Layout Object @tab Priority -@item @code{DynamicLineSpanner} @tab @code{ 250} -@item @code{DynamicText} @tab @code{ 250} -@item @code{OttavaBracket} @tab @code{ 400} -@item @code{TextScript} @tab @code{ 450} -@item @code{TextSpanner} @tab @code{ 350} +@multitable @columnfractions .3 .3 .3 +@headitem Layout Object + @tab Priority + @tab Controls position of: +@item @code{DynamicLineSpanner} + @tab @code{ 250} + @tab All dynamic markings +@item @code{OttavaBracket} + @tab @code{ 400} + @tab Ottava brackets +@item @code{TextScript} + @tab @code{ 450} + @tab Markup text +@item @code{TextSpanner} + @tab @code{ 350} + @tab Text spanners @end multitable Here is an example showing the default placement of these. @@ -2723,263 +2747,6 @@ lhMusic = \relative c' { @end lilypond -@node Page layout -@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 - -TODO Check all these examples - -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 -- if -the \paper block is at the top of the file, then it will apply -to all pages. Support for the following paper sizes is available: -a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid). -Setting the paper size automatically sets suitable margins and -line length. - -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 -– 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 determined automatically. They are chosen -so that lines look neither cramped nor loose, and 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. However, -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 ""}, -although again there must be no notes left hanging over in any of -the staves at this point, or it will be ignored. - -The opposite command, @code{\noBreak}, forbids a line break at the -bar line where it is inserted. - -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 affects only 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 the @code{\break} and -@code{\noBreak} commands discused above and force or forbid -a page-break at the point where they are inserted. -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 will not be justified vertically. - -For more details see @ruser{Vertical spacing}. - -@node Fitting music onto fewer pages -@subsection Fitting music onto fewer pages - -Sometimes you can end up with one or two staves on a second -(or third, or fourth...) page. This is annoying, especially -if you look at previous pages and it looks like there is plenty -of room left on those. - -When investigating layout issues, @code{annotate-spacing} is -an invaluable tool. This command prints the values of various -layout spacing commands; see @ruser{Displaying spacing}, for more -details. From the output of @code{annotate-spacing}, we can -see which margins we may wish to alter. - -Other than margins, there are a few other options to save space: - -@itemize -@item -You may tell LilyPond to place systems as close together as -possible (to fit as many systems as possible onto a page), but -then to space those systems out so that there is no blank -space at the bottom of the page. - -@example -\paper @{ - between-system-padding = #0.1 - between-system-space = #0.1 - ragged-last-bottom = ##f - ragged-bottom = ##f -@} -@end example - -@item -You may force the number of systems (i.e., if LilyPond wants -to typeset some music with 11 systems, you could force it to -use 10). - -@example -\paper @{ - system-count = #10 -@} -@end example - -@item -Avoid (or reduce) objects which increase the vertical size of -a system. For example, volta repeats (or alternate repeats) -require extra space. If these repeats are spread over two -systems, they will take up more space than one system with -the volta repeats and another system without. - -Another example is moving dynamics which @q{stick out} of -a system, as in the second bar here: - -@lilypond[verbatim,quote,fragment,ragged-right,relative=1] -e4 c g\f c -\override DynamicText #'extra-offset = #'( -2.2 . 2.0) -e4 c g\f c -@end lilypond - -@item -Alter the horizontal spacing via @code{SpacingSpanner}. See -@ruser{Changing horizontal spacing}, for more details. Here's -an example first showing the default behaviour: - -@lilypond[verbatim,quote,ragged-right] -\score { - \relative c'' { - g4 e e2 | - f4 d d2 | - c4 d e f | - g4 g g2 | - g4 e e2 | - } -} -@end lilypond - -@noindent -and now with @code{common-shortest-duration} increased from the -value of @code{1/4} (a quarter note is the most common in this -example) to @code{1/2}: - -@lilypond[verbatim,quote,ragged-right] -\score { - \relative c'' { - g4 e e2 | - f4 d d2 | - c4 d e f | - g4 g g2 | - g4 e e2 | - } - \layout { - \context { - \Score - \override SpacingSpanner - #'common-shortest-duration = #(ly:make-moment 1 2) - } - } -} -@end lilypond - -@noindent -Note that this override cannot be modified dynamically, so it must -always be placed in a @code{\context@{..@}} block so that it applies -to the whole score. - -TODO Add description of using \context in this way earlier if it is -not already anywhere -td - -@end itemize - - @node Further tweaking @section Further tweaking @@ -3239,3 +3006,4 @@ In some cases (see issue 246), this must be done before + diff --git a/Documentation/user/writing-sections.txt b/Documentation/user/writing-sections.txt index c43065819a..6c7cfaa30f 100644 --- a/Documentation/user/writing-sections.txt +++ b/Documentation/user/writing-sections.txt @@ -36,6 +36,7 @@ subsection, *Do not* assume that the existing text is accurate/complete; some of the manual is highly out of date. - is the material in the @refbugs still accurate? +- process anything on the TODO list on the GDP web site. - can the examples be improved (made more explanatory), or is there any missing info? (feel free to ask specific questions on -user; a couple of people claimed to be interesting in being