Issue 905: Gracefully ignore UTF-8 BOM in the middle of a file

[lilypond.git] / Documentation / notation / spacing.itely

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 6789b40548d3c941ea0a46dcf6ba63897dfc236d..37557fcb2de4e7bcda6514ba7079be49d69f3b68 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.13.42"
+@c \version "2.14.0"

 
 @ignore
 GDP TODO list
 
 @ignore
 GDP TODO list


@@ -895,6 +895,7 @@ Default values not listed here are defined in
 
 @table @code
 
 
 @table @code
 

+@cindex page numbers, auto-numbering

 @item auto-first-page-number
 @funindex auto-first-page-number
 
 @item auto-first-page-number
 @funindex auto-first-page-number
 


@@ -904,6 +905,7 @@ will decide whether to start with an odd or even number.  This
 will result in the first page number remaining as is or being
 increased by one.  Default: @code{#f}.
 
 will result in the first page number remaining as is or being
 increased by one.  Default: @code{#f}.
 

+@cindex page numbers, specify the first

 @item first-page-number
 @funindex first-page-number
 
 @item first-page-number
 @funindex first-page-number
 


@@ -914,6 +916,7 @@ The value of the page number on the first page.
 
 If set to true, a page number is printed on the first page.
 
 
 If set to true, a page number is printed on the first page.
 

+@cindex page numbers, suppress

 @item print-page-number
 @funindex print-page-number
 
 @item print-page-number
 @funindex print-page-number
 


@@ -941,7 +944,7 @@ of the cover page so that page 1 is on the right hand side.
 
 The relative importance of page (vertical) spacing and line
 (horizontal) spacing.  High values will make page spacing more
 
 The relative importance of page (vertical) spacing and line
 (horizontal) spacing.  High values will make page spacing more

-important.  Default: @code{#10}.
+important.  Default: @code{10}.

 
 @item print-all-headers
 @funindex print-all-headers
 
 @item print-all-headers
 @funindex print-all-headers


@@ -1342,7 +1345,7 @@ inserted at top-level, between scores and top-level markups.
 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
 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
+@code{#t} the systems on all pages or just the last page

 respectively will not be justified vertically.  See
 @ref{Fixed vertical spacing \paper variables}.
 
 respectively will not be justified vertically.  See
 @ref{Fixed vertical spacing \paper variables}.
 


@@ -1460,7 +1463,7 @@ the section.
 The @code{Page_turn_engraver} reads the context property
 @code{minimumPageTurnLength} to determine how long a note-free section must
 be before a page turn is considered.  The default value for
 The @code{Page_turn_engraver} reads the context property
 @code{minimumPageTurnLength} to determine how long a note-free section must
 be before a page turn is considered.  The default value for

-@code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}.  If you want
+@code{minimumPageTurnLength} is @code{(ly:make-moment 1 1)}.  If you want

 to disable page turns, you can set it to something very large.
 
 @example
 to disable page turns, you can set it to something very large.
 
 @example


@@ -1746,6 +1749,19 @@ systems, scores, markups, and margins is controlled by
 @node Within-system spacing properties
 @unnumberedsubsubsec Within-system spacing properties
 
 @node Within-system spacing properties
 @unnumberedsubsubsec Within-system spacing properties
 

+@funindex staff-affinity
+@funindex staffgroup-staff-spacing
+@funindex staff-staff-spacing
+@funindex nonstaff-unrelatedstaff-spacing
+@funindex nonstaff-relatedstaff-spacing
+@funindex nonstaff-nonstaff-spacing
+@funindex default-staff-staff-spacing
+@funindex minimum-Y-extent
+@funindex extra-offset
+@funindex self-alignment-X
+@funindex X-offset
+@funindex VerticalAxisGroup
+

 The within-system vertical spacing mechanisms are controlled by
 two sets of grob properties.  The first set is associated with the
 @code{VerticalAxisGroup} grob, which is created by all staves and
 The within-system vertical spacing mechanisms are controlled by
 two sets of grob properties.  The first set is associated with the
 @code{VerticalAxisGroup} grob, which is created by all staves and


@@ -1760,7 +1776,7 @@ follow the format @code{@var{item1}-@var{item2}-spacing}, where
 spaced.  Note that @code{@var{item2}} is not necessarily below
 @code{@var{item1}}; for example,
 @code{nonstaff-relatedstaff-spacing} will measure upwards from the
 spaced.  Note that @code{@var{item2}} is not necessarily below
 @code{@var{item1}}; for example,
 @code{nonstaff-relatedstaff-spacing} will measure upwards from the

-non-staff line if @code{staff-affinity} is @code{#UP}.
+non-staff line if @code{staff-affinity} is @code{UP}.

 
 Each distance is measured between the @emph{reference points} of
 the two items.  The reference point for a staff is the vertical
 
 Each distance is measured between the @emph{reference points} of
 the two items.  The reference point for a staff is the vertical


@@ -1805,8 +1821,10 @@ labelContext =
   \context { \Dynamics    \alignToZero }
   \context { \FiguredBass \alignToZero }
   \context { \Lyrics      \alignToZero }
   \context { \Dynamics    \alignToZero }
   \context { \FiguredBass \alignToZero }
   \context { \Lyrics      \alignToZero }

-  \context { \NoteNames   \alignToZero }
-  \context { \ChordNames  \alignToZero \lowerCaseChords }
+  \context { \NoteNames   \alignToZero \staffAffinityDown }
+  \context { \ChordNames  \alignToZero
+                          \staffAffinityDown
+                         \lowerCaseChords }

   \context { \FretBoards  \alignToZero \staffAffinityDown }
   \context { \Score
     \override BarLine #'stencil = ##f
   \context { \FretBoards  \alignToZero \staffAffinityDown }
   \context { \Score
     \override BarLine #'stencil = ##f


@@ -1827,8 +1845,8 @@ labelContext =
   \new RhythmicStaff {
     \set RhythmicStaff.instrumentName = #"baseline "
     \textLengthOn
   \new RhythmicStaff {
     \set RhythmicStaff.instrumentName = #"baseline "
     \textLengthOn

-    \labelContext "ChordNames" s1 |
-    \labelContext "NoteNames"  s1 |
+    \labelContext "ChordNames " s1 |
+    \labelContext "NoteNames "  s1 |

     \labelContext "Lyrics"     s1 |
   }
   \new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
     \labelContext "Lyrics"     s1 |
   }
   \new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }


@@ -1840,7 +1858,7 @@ labelContext =
     \set RhythmicStaff.instrumentName = #"vertical center "
     \labelContext "Dynamics" s1*3
   }
     \set RhythmicStaff.instrumentName = #"vertical center "
     \labelContext "Dynamics" s1*3
   }

-  \new Dynamics { s2\mp s\fp }
+  \new Dynamics { s1\mp s\fp }

 >>
 
 %% The reference point for FiguredBass is its highest point
 >>
 
 %% The reference point for FiguredBass is its highest point


@@ -1864,9 +1882,8 @@ labelContext =
 @end lilypond
 
 Each of the vertical spacing grob properties (except
 @end lilypond
 
 Each of the vertical spacing grob properties (except

-@code{staff-affinity}) is stored as an alist (association list),
-and each uses the same alist structure as the @code{\paper}
-spacing variables discussed in
+@code{staff-affinity}) uses the same alist structure as the
+@code{\paper} spacing variables discussed in

 @ref{Flexible vertical spacing \paper variables}.  Specific methods
 for modifying alists are discussed in @ref{Modifying alists}.
 Grob properties should be adjusted with an @code{\override} inside
 @ref{Flexible vertical spacing \paper variables}.  Specific methods
 for modifying alists are discussed in @ref{Modifying alists}.
 Grob properties should be adjusted with an @code{\override} inside


@@ -1919,19 +1936,25 @@ in @rinternals{Contexts}.
 
 @table @code
 @item staff-staff-spacing
 
 @table @code
 @item staff-staff-spacing

-The distance between the current staff and the staff just below it
-in the same system, even if one or more non-staff lines (such as
-@code{Lyrics}) are placed between the two staves.  Does not apply
-to the bottom staff of a system.  This replaces any settings
-inherited from the @code{StaffGrouper} grob of the containing
-staff-group, if there is one.  If this is unset, and there are no
-@code{StaffGrouper} properties to inherit, the
-@code{default-staff-staff-spacing} property is used.
+
+Used to determine the distance between the current staff and the
+staff just below it in the same system, even if one or more
+non-staff lines (such as @code{Lyrics}) are placed between the two
+staves.  Does not apply to the bottom staff of a system.
+
+Initially, the @code{staff-staff-spacing} of a
+@code{VerticalAxisGroup} is a Scheme function that applies the
+properties of the @code{StaffGrouper} if the staff is part of a
+group, or the @code{default-staff-staff-spacing} of the staff
+otherwise.  This allows staves to be spaced differently when they
+are grouped.  For uniform spacing regardless of grouping, this
+function may be replaced by a flexible-spacing alist, using the
+complete-redefinition form of override shown above.

 
 @item default-staff-staff-spacing
 
 @item default-staff-staff-spacing

-The settings to use for @code{staff-staff-spacing} when it is
-unset.  This applies to ungrouped staves and to grouped staves
-that do not inherit settings from the @code{StaffGrouper} grob.
+A flexible-spacing alist defining the @code{staff-staff-spacing} used for
+ungrouped staves, unless @code{staff-staff-spacing} has been explicitly
+set with an @code{\override}.

 
 @item staff-affinity
 The direction of the staff to use for spacing the current
 
 @item staff-affinity
 The direction of the staff to use for spacing the current


@@ -1946,9 +1969,9 @@ set to @code{UP} should not immediately follow one that is set to
 @code{DOWN}; those at the bottom should use @code{UP}.  Setting
 @code{staff-affinity} for a staff causes it to be treated as a
 non-staff line.  Setting @code{staff-affinity} to @code{#f} causes
 @code{DOWN}; those at the bottom should use @code{UP}.  Setting
 @code{staff-affinity} for a staff causes it to be treated as a
 non-staff line.  Setting @code{staff-affinity} to @code{#f} causes

-a non-staff line to be treated as a staff.
-
-@c TODO: verify last clause below ("even if other...")
+a non-staff line to be treated as a staff.  Setting
+@code{staff-affinity} to @code{UP}, @code{CENTER}, or @code{DOWN}
+causes a staff to be spaced as a non-staff line.

 
 @item nonstaff-relatedstaff-spacing
 The distance between the current non-staff line and the nearest
 
 @item nonstaff-relatedstaff-spacing
 The distance between the current non-staff line and the nearest


@@ -1958,7 +1981,12 @@ either @code{UP} or @code{DOWN}.  If @code{staff-affinity} is
 @code{CENTER}, then @code{nonstaff-relatedstaff-spacing} is used
 for the nearest staves on @emph{both} sides, even if other
 non-staff lines appear between the current one and either of the
 @code{CENTER}, then @code{nonstaff-relatedstaff-spacing} is used
 for the nearest staves on @emph{both} sides, even if other
 non-staff lines appear between the current one and either of the

-staves.
+staves.  This means that the placement of a non-staff line depends
+on both the surrounding staves and the surrounding non-staff lines.
+Setting the @code{stretchability} of one of these types of spacing to
+a small value will make that spacing dominate.  Setting the
+@code{stretchability} to a large value will make that spacing have
+little effect.

 
 @item nonstaff-nonstaff-spacing
 The distance between the current non-staff line and the next
 
 @item nonstaff-nonstaff-spacing
 The distance between the current non-staff line and the next


@@ -1985,9 +2013,8 @@ example, to require a minimum amount of padding between a
 @item staff-staff-spacing
 The distance between consecutive staves within the current
 staff-group.  The @code{staff-staff-spacing} property of an
 @item staff-staff-spacing
 The distance between consecutive staves within the current
 staff-group.  The @code{staff-staff-spacing} property of an

-individual staff's @code{VerticalAxisGroup} grob will be used
-instead for any staves in the staff-group that have it set.  Also
-see @code{default-staff-staff-spacing}.
+individual staff's @code{VerticalAxisGroup} grob can be
+overriden with different spacing settings for that staff.

 
 @item staffgroup-staff-spacing
 The distance between the last staff of the current staff-group and
 
 @item staffgroup-staff-spacing
 The distance between the last staff of the current staff-group and


@@ -1995,21 +2022,24 @@ the staff just below it in the same system, even if one or more
 non-staff lines (such as @code{Lyrics}) exist between the two
 staves.  Does not apply to the bottom staff of a system.  The
 @code{staff-staff-spacing} property of an individual staff's
 non-staff lines (such as @code{Lyrics}) exist between the two
 staves.  Does not apply to the bottom staff of a system.  The
 @code{staff-staff-spacing} property of an individual staff's

-@code{VerticalAxisGroup} grob will be used instead for any staves
-in the staff-group that have it set.  Also see
-@code{default-staff-staff-spacing}.
+@code{VerticalAxisGroup} grob can be overriden with different
+spacing settings for that staff.

 @end table
 
 @seealso
 @end table
 
 @seealso

-Installed Files:
-@file{ly/engraver-init.ly},
-@file{scm/define-grobs.scm}.
+Notation Reference:
+@ref{Flexible vertical spacing \paper variables},
+@ref{Modifying alists}.

 
 Internals Reference:
 @rinternals{Contexts},
 @rinternals{VerticalAxisGroup},
 @rinternals{StaffGrouper}.
 
 
 Internals Reference:
 @rinternals{Contexts},
 @rinternals{VerticalAxisGroup},
 @rinternals{StaffGrouper}.
 

+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+

 
 @node Spacing of ungrouped staves
 @unnumberedsubsubsec Spacing of ungrouped staves
 
 @node Spacing of ungrouped staves
 @unnumberedsubsubsec Spacing of ungrouped staves


@@ -2024,6 +2054,7 @@ staves:
 @itemize
 @item @code{VerticalAxisGroup} properties:
 @itemize
 @itemize
 @item @code{VerticalAxisGroup} properties:
 @itemize

+@item @code{default-staff-staff-spacing}

 @item @code{staff-staff-spacing}
 @end itemize
 @end itemize
 @item @code{staff-staff-spacing}
 @end itemize
 @end itemize


@@ -2034,21 +2065,24 @@ These grob properties are described individually above; see
 Additional properties are involved for staves that are part of a
 staff-group; see @ref{Spacing of grouped staves}.
 
 Additional properties are involved for staves that are part of a
 staff-group; see @ref{Spacing of grouped staves}.
 

-The following example shows how the @code{staff-staff-spacing}
-property can affect the spacing of ungrouped staves:
+The following example shows how the @code{default-staff-staff-spacing}
+property can affect the spacing of ungrouped staves.
+The same overrides applied to @code{staff-staff-spacing} would
+have the same effect, but would also apply in cases where the staves
+are combined in a group or groups.

 
 @lilypond[verbatim,quote,staffsize=16]
 \layout {
   \context {
     \Staff
 
 @lilypond[verbatim,quote,staffsize=16]
 \layout {
   \context {
     \Staff

-    \override VerticalAxisGroup #'staff-staff-spacing =
+    \override VerticalAxisGroup #'default-staff-staff-spacing =

       #'((basic-distance . 8)
          (minimum-distance . 7)
          (padding . 1))
   }
 }
 
       #'((basic-distance . 8)
          (minimum-distance . 7)
          (padding . 1))
   }
 }
 

-\new StaffGroup <<
+<<

   % The very low note here needs more room than 'basic-distance
   % can provide, so the distance between this staff and the next
   % is determined by 'padding.
   % The very low note here needs more room than 'basic-distance
   % can provide, so the distance between this staff and the next
   % is determined by 'padding.


@@ -2063,7 +2097,7 @@ property can affect the spacing of ungrouped staves:
   % By setting 'padding to a negative value, staves can be made to
   % collide.  The lowest acceptable value for 'basic-distance is 0.
   \new Staff \with {
   % By setting 'padding to a negative value, staves can be made to
   % collide.  The lowest acceptable value for 'basic-distance is 0.
   \new Staff \with {

-    \override VerticalAxisGroup #'staff-staff-spacing =
+    \override VerticalAxisGroup #'default-staff-staff-spacing =

       #'((basic-distance . 3.5)
          (padding . -10))
   } { \clef bass g2 r | }
       #'((basic-distance . 3.5)
          (padding . -10))
   } { \clef bass g2 r | }


@@ -2100,7 +2134,6 @@ staff-groups:
 @item @code{VerticalAxisGroup} properties:
 @itemize
 @item @code{staff-staff-spacing}
 @item @code{VerticalAxisGroup} properties:
 @itemize
 @item @code{staff-staff-spacing}

-@item @code{default-staff-staff-spacing}

 @end itemize
 @item @code{StaffGrouper} properties:
 @itemize
 @end itemize
 @item @code{StaffGrouper} properties:
 @itemize


@@ -2600,7 +2633,7 @@ measure, the shortest duration is determined.  The most common shortest
 duration is taken as the basis for the spacing, with the stipulation
 that this shortest duration should always be equal to or shorter than
 an 8th note.  The shortest duration is printed when you run
 duration is taken as the basis for the spacing, with the stipulation
 that this shortest duration should always be equal to or shorter than
 an 8th note.  The shortest duration is printed when you run

-@code{lilypond} with the @code{--verbose} option.
+@code{lilypond} with the @option{--verbose} option.

 
 These durations may also be customized.  If you set the
 @code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
 
 These durations may also be customized.  If you set the
 @code{common-shortest-duration} in @rinternals{SpacingSpanner}, then


@@ -2942,10 +2975,10 @@ The @code{proportionalNotationDuration} setting takes a single argument,
 which is the reference duration against that all music will be spaced.
 The LilyPond Scheme function @code{make-moment} takes two arguments
 -- a numerator and denominator which together express some fraction of
 which is the reference duration against that all music will be spaced.
 The LilyPond Scheme function @code{make-moment} takes two arguments
 -- a numerator and denominator which together express some fraction of

-a whole note.  The call @code{#(ly:make-moment 1 20)} therefore produces
+a whole note.  The call @code{(ly:make-moment 1 20)} therefore produces

 a reference duration of a twentieth note.  Values such as
 a reference duration of a twentieth note.  Values such as

-@code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
-@code{#(ly:make-moment 3 97)} are all possible as well.
+@code{(ly:make-moment 1 16)}, @code{(ly:make-moment 1 8)}, and
+@code{(ly:make-moment 3 97)} are all possible as well.

 
 How do we select the right reference duration to pass to
 @code{proportionalNotationDuration}?  Usually by a process of trial
 
 How do we select the right reference duration to pass to
 @code{proportionalNotationDuration}?  Usually by a process of trial