X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fspacing.itely;h=7aa0dd62645c3822d48e8f967d812f5b06ded703;hb=37ca1f80bf5401accd17056938f4f7b2c147ddb2;hp=03bcc9b7178f0fb42dd4ae149f532e1591b51b19;hpb=970c4b3f5defca050ab4589ab2f9c81a193af6f1;p=lilypond.git

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 03bcc9b717..7aa0dd6264 100644
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -7,9 +7,50 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c A menu is needed before every deeper *section nesting of @node's; run
-@c     M-x texinfo-all-menus-update
-@c to automatically fill in these menus before saving changes
+@c \version "2.11.38"
+
+@ignore
+GDP TODO list
+
+Negative numbers are allowed:
+> Are you sure? The following works well
+> \paper{
+>   first-page-number = -2
+> }
+> and prints page number -1 on the second page, for example.
+
+
+- default paper size is A4.
+
+
+In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
+states:
+
+"@code{layout-set-staff-size} does not change the distance between
+the
+staff lines."
+
+Could we add a sentence:
+"Use instead the pair               fontSize = #@var{N}
+            \override StaffSymbol #'staff-space = #(magstep
+@var{N})
+inside the Staff context to change the size of the font and the
+distance between
+staff lines accordingly."
+
+Actually I found, that the @internalsref{StaffSymbol} at line 481
+sends to an uncomplete
+documentation. The property staff-space is not explained here. I
+thought Y-extent might be of
+help, but it is in turn explained by x-space which again is
+missing from the list. Who has the
+knowledge to fix this?
+
+
+Clarify
+http://code.google.com/p/lilypond/issues/detail?id=68
+
+@end ignore
 
 @node Spacing issues
 @chapter Spacing issues
@@ -35,6 +76,7 @@ or stretched.
 * Breaks::                      
 * Vertical spacing::            
 * Horizontal spacing::          
+* Page layout MOVED FROM LM::   
 @end menu
 
 
@@ -294,7 +336,7 @@ result in the first page number remaining as is or being increased by one.
 @end quotation
 
 
-@commonprop
+@snippets
 
 The header and footer are created by the functions make-footer and
 make-header, defined in \paper.  The default implementations are in
@@ -368,7 +410,7 @@ how much space can be spent on a page, the latter creates the actual
 page given the system to put on it.
 
 
-@refbugs
+@knownissues
 
 The option right-margin is defined but doesn't set the right margin
 yet.  The value for the right margin has to be defined adjusting the
@@ -478,7 +520,7 @@ The recommended font sizes are listed in the following table:
 
 These fonts are available in any sizes.  The context property
 @code{fontSize} and the layout property @code{staff-space} (in
-@internalsref{StaffSymbol}) can be used to tune the size for individual
+@rinternals{StaffSymbol}) can be used to tune the size for individual
 staves.  The sizes of individual staves are relative to the global size.
 
 @example
@@ -490,7 +532,7 @@ staves.  The sizes of individual staves are relative to the global size.
 This manual: @ref{Selecting notation font size}.
 
 
-@refbugs
+@knownissues
 
 @code{layout-set-staff-size} does not change the distance between the
 staff lines.
@@ -563,7 +605,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
@@ -604,7 +646,7 @@ skips and repeated with @code{\repeat}:
 This makes the following 28 measures (assuming 4/4 time) be broken every
 4 measures, and only there.
 
-@refcommands
+@predefined
 
 @code{\break}, and @code{\noBreak}.
 @funindex \break
@@ -612,15 +654,15 @@ This makes the following 28 measures (assuming 4/4 time) be broken every
 
 @seealso
 
-Internals: @internalsref{LineBreakEvent}.
+Internals: @rinternals{LineBreakEvent}.
 
 A linebreaking configuration can be saved as a @code{.ly} file
 automatically.  This allows vertical alignments to be stretched to
 fit pages in a second formatting run.  This is fairly new and
 complicated.  More details are available in
-@c @lsrdir{spacing}
+@rlsr{Spacing}.
 
-@refbugs
+@knownissues
 
 Line breaks can only occur if there is a @q{proper} bar line.  A note
 which is hanging over a bar line is not proper, such as
@@ -653,7 +695,7 @@ lines.  This behavior can be changed by setting
 @node Page breaking
 @subsection Page breaking
 
-The default page breaking may be overriden by inserting
+The default page breaking may be overridden by inserting
 @code{\pageBreak} or @code{\noPageBreak} commands.  These commands are
 analogous to @code{\break} and @code{\noBreak}.  They should be
 inserted at a bar line.  These commands force and forbid a page-break
@@ -679,7 +721,7 @@ The old page breaking algorithm is called
 @code{optimal-page-breaks}.  If you are having trouble with the new page
 breakers, you can enable the old one as a workaround.
 
-@refcommands
+@predefined
 
 @funindex \pageBreak
 @code{\pageBreak}
@@ -763,7 +805,7 @@ The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
 @code{\allowPageTurn}, may also be used at top-level, between scores and
 top-level markups.
 
-@refcommands
+@predefined
 
 @funindex \pageTurn
 @code{\pageTurn}
@@ -772,7 +814,7 @@ top-level markups.
 @funindex \allowPageTurn
 @code{\allowPageTurn}
 
-@refbugs
+@knownissues
 
 There should only be one @code{Page_turn_engraver} in a score.  If there is more
 than one, they will interfere with each other.
@@ -784,7 +826,7 @@ than one, they will interfere with each other.
 
 The @code{ly:minimal-breaking} function performs minimal computations to
 calculate the page breaking: it fills a page with as many systems as
-possible before moving to the next one.  Thus, it may be prefered for
+possible before moving to the next one.  Thus, it may be preferred for
 scores with many pages, where the other page breaking functions could be
 too slow or memory demanding, or a lot of texts.  It is enabled using:
 
@@ -805,9 +847,9 @@ commands.  There are two commands to override this behavior:
 \override NonMusicalPaperColumn #'page-break-permission = ##f
 @end example
 
-When @code{line-break-permission} is overriden to false, Lily will insert
+When @code{line-break-permission} is overridden to false, Lily will insert
 line breaks at explicit @code{\break} commands and nowhere else.  When
-@code{page-break-permission} is overriden to false, Lily will insert
+@code{page-break-permission} is overridden to false, Lily will insert
 page breaks at explicit @code{\pageBreak} commands and nowhere else.
 
 @lilypond[quote,verbatim]
@@ -952,7 +994,7 @@ 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
 property @code{minimum-Y-extent}.  When applied to a
-@internalsref{VerticalAxisGroup}, it controls the size of a horizontal
+@rinternals{VerticalAxisGroup}, it controls the size of a horizontal
 line, such as a staff or a line of lyrics.  @code{minimum-Y-extent}
 takes a pair of numbers, so
 if you want to make it smaller than its default @code{#'(-4 . 4)}
@@ -974,7 +1016,7 @@ After page breaks are determined, the vertical spacing within each
 system is reevaluated in order to fill the page more evenly; if a page
 has space left over, systems are stretched in order to fill that space.
 The amount of stretching can be configured though the @code{max-stretch}
-property of the @internalsref{VerticalAlignment} grob. By default,
+property of the @rinternals{VerticalAlignment} grob. By default,
 @code{max-stretch} is set to zero, disabling stretching. To enable
 stretching, a sane value for @code{max-stretch}
 is @code{ly:align-interface::calc-max-stretch}.
@@ -984,7 +1026,7 @@ leaving some parts fixed.  For example, if a piano part occurs in the
 middle of an orchestral score, you may want to leave the piano staves
 close to each other while stretching the rest of the score.  The
 @code{keep-fixed-while-stretching} property of
-@internalsref{VerticalAxisGroup} can be used to achieve this.  When set
+@rinternals{VerticalAxisGroup} can be used to achieve this.  When set
 to @code{##t}, this property keeps its staff (or line of lyrics) from
 moving relative to the one directly above it.  In the example above,
 you would override @code{keep-fixed-while-stretching} to @code{##t} in
@@ -1035,9 +1077,9 @@ the second piano staff:
 @seealso
 
 Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.  The context parameters
+@rinternals{VerticalAlignment} object.  The context parameters
 specifying the vertical extent are described in connection with
-the @internalsref{Axis_group_engraver}.
+the @rinternals{Axis_group_engraver}.
 
 Example files: @c @lsr{spacing,page-spacing.ly},
 @c @lsr{spacing,alignment-vertical-spacing.ly}.
@@ -1058,7 +1100,7 @@ Space between systems are controlled by four @code{\paper} variables,
 @end example
 
 When only a couple of flat systems are placed on a page, the resulting
-vertical spacing may be non-eleguant: one system at the top of the page,
+vertical spacing may be non-elegant: one system at the top of the page,
 and the other at the bottom, with a huge gap between them.  To avoid this
 situation, the space added between the systems can be limited.  This
 feature is activated by setting to @code{#t} the
@@ -1319,7 +1361,7 @@ stretched according to the data in the page layout file.
 The @code{ragged-bottom} property adds space between systems, while
 the two-pass technique adds space between staves inside a system.
 
-To allow this behaviour, a @code{tweak-key} variable has to be set in
+To allow this behavior, a @code{tweak-key} variable has to be set in
 each score @code{\layout} block, and the tweaks included in each score
 music, using the @code{\scoreTweak} music function.
 
@@ -1417,7 +1459,7 @@ c^"This text is placed close to the previous text"
 TODO: this example doesn't work any more ?
 
 By default, outside-staff objects are placed without regard to
-their horizontal distance from the previously-posititioned grobs.  This
+their horizontal distance from the previously-positioned 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
@@ -1455,10 +1497,10 @@ c''2
 @subsection Horizontal spacing overview
 
 The spacing engine translates differences in durations into stretchable
-distances (@q{springs}) of differring lengths.  Longer durations get
+distances (@q{springs}) of differing lengths.  Longer durations get
 more space, shorter durations get less.  The shortest durations get a
 fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
+@code{shortest-duration-space} in the @rinternals{SpacingSpanner}
 object).  The longer the duration, the more space it gets: doubling a
 duration adds a fixed amount (this amount is controlled by
 @code{spacing-increment}) of space to the note.
@@ -1496,7 +1538,7 @@ an 8th note.  The shortest duration is printed when you run
 @code{lilypond} with the @code{--verbose} option.
 
 These durations may also be customized.  If you set the
-@code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
+@code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
 this sets the base duration for spacing.  The maximum duration for this
 base (normally an 8th), is set through @code{base-shortest-duration}.
 
@@ -1518,9 +1560,9 @@ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
 In the introduction (see @rlearning{Engraving}), it was explained that stem
 directions influence spacing.  This is controlled with the
 @code{stem-spacing-correction} property in the
-@internalsref{NoteSpacing}, object.  These are generated for every
-@internalsref{Voice} context.  The @code{StaffSpacing} object
-(generated in @internalsref{Staff} context) contains the same property
+@rinternals{NoteSpacing}, object.  These are generated for every
+@rinternals{Voice} context.  The @code{StaffSpacing} object
+(generated in @rinternals{Staff} context) contains the same property
 for controlling the stem/bar line spacing.  The following example shows
 these corrections, once with default settings, and once with
 exaggerated corrections:
@@ -1541,12 +1583,12 @@ Proportional notation is supported; see @ref{Proportional notation}.
 
 @seealso
 
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
+Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
+@rinternals{StaffSpacing}, @rinternals{SeparationItem}, and
+@rinternals{SeparatingGroupSpanner}.
 
 
-@refbugs
+@knownissues
 
 There is no convenient mechanism to manually override spacing.  The
 following work-around may be used to insert extra space into a score.
@@ -1578,7 +1620,7 @@ c16[ c c8]
 
 
 The @code{\newSpacingSection} command creates a new
-@internalsref{SpacingSpanner} object, and hence new @code{\override}s
+@rinternals{SpacingSpanner} object, and hence new @code{\override}s
 may be used in that location.
 
 
@@ -1594,7 +1636,7 @@ music.  Note that @code{ly:make-moment} constructs
 a duration, so @code{1 4} is a longer duration
 than @code{1 16}.
 
-@lilypond[relative,verbatim,line-width=12\cm]
+@lilypond[verbatim,line-width=12\cm]
 \score {
   \relative c'' {
     g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
@@ -1605,7 +1647,7 @@ than @code{1 16}.
 }
 @end lilypond
 
-@lilypond[relative,verbatim,line-width=12\cm]
+@lilypond[verbatim,line-width=12\cm]
 \score {
   \relative c'' {
     g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
@@ -1624,7 +1666,7 @@ than @code{1 16}.
 @end lilypond
 
 
-@commonprop
+@snippets
 
 By default, spacing in tuplets depends on various non-duration
 factors (such as accidentals, clef changes, etc).  To disregard
@@ -1716,7 +1758,7 @@ 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
+clarify complex rhythmic relationships or to facilitate the placement
 of timelines or other graphics directly in the score.
 
 LilyPond supports five different settings for proportional notation,
@@ -1786,7 +1828,7 @@ The @code{proportionalNotationDuration} setting is a context setting that
 lives in @code{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
+preceded 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}.
 
@@ -1986,7 +2028,7 @@ reduces this space to zero.
 @end lilypond
 
 Nonmusical elements like time signatures, key signatures, clefs and
-accidentals are problemmatic in proportional notation.  None of these
+accidentals are problematic in proportional notation.  None of these
 elements has rhythmic duration.  But all of these elements consume
 horizontal space.  Different proportional scores approach these
 problems differently.
@@ -2051,3 +2093,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 @ref{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 overridden by inserting 
+@code{\pageBreak} or @code{\noPageBreak} commands.
+These commands are analogous to the @code{\break} and 
+@code{\noBreak} commands discussed 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 @ref{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 @ref{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 @ref{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
+@ref{Changing horizontal spacing}, for more details.  Here's
+an example first showing the default behavior:
+
+@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
+
+
+