From aca2ebd202992674424bd05a8bfc7c8003a8839b Mon Sep 17 00:00:00 2001 From: Trevor Daniels Date: Wed, 22 Oct 2014 14:23:25 +0100 Subject: [PATCH] Issue 4169: Line- and page-breaking syntactic sugar Install line- and page-breaking controls and document them. Remove now-redundant section on Explicit breaks, preserving the snippet showing how to use an extra voice to contain break commands. Amend indexing. --- Documentation/notation/spacing.itely | 122 +++++++++++++-------------- Documentation/notation/vocal.itely | 2 +- ly/property-init.ly | 18 ++++ 3 files changed, 77 insertions(+), 65 deletions(-) diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely index 1cded7566a..d8006a1e42 100644 --- a/Documentation/notation/spacing.itely +++ b/Documentation/notation/spacing.itely @@ -1365,14 +1365,19 @@ staff lines. @menu * Line breaking:: * Page breaking:: -* Explicit breaks:: @end menu @node Line breaking @subsection Line breaking -@cindex line breaks +@funindex \break +@funindex \noBreak +@funindex \autoBreaksOff +@funindex \autoBreaksOn +@funindex \autoLineBreaksOff +@funindex \autoLineBreaksOn +@cindex manual line breaks @cindex breaking lines Line breaks are normally determined automatically. They are @@ -1430,6 +1435,18 @@ c8 c] c2. | The @code{\noBreak} command forbids a line break at the bar line where it is inserted. +Within a score, automatic line breaking is prevented within music +lying between @code{\autoLineBreaksOff} and @code{\autoLineBreaksOn} +commands. If automatic page breaks should also be prevented, the +commands @code{\autoBreaksOff} and @code{\autoBreaksOn} should be +used. Manual breaks are unaffected by these commands. Note that +inhibiting automatic line breaks may cause music to run over the +right margin if it cannot all be contained within one line. + +Automatic line breaks (but not page breaks) may be enabled at single +bar lines by using @code{\once \autoLineBreaksOn} at a bar line. +This identifies a permitted rather than a forced line break. + 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 @@ -1474,12 +1491,19 @@ broken every 4 measures, and only there: @predefined -@funindex \break @code{\break}, -@funindex \noBreak -@code{\noBreak}. +@code{\noBreak}, +@code{\autoBreaksOff}, +@code{\autoBreaksOn}, +@code{\autoLineBreaksOff}, +@code{\autoLineBreaksOn}. @endpredefined +@snippets + +@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle] +{using-an-extra-voice-for-breaks.ly} + @seealso Notation Reference: @ref{paper variables for line breaking} @@ -1491,6 +1515,12 @@ Snippets: Internals Reference: @rinternals{LineBreakEvent}. +@knownissues + +Placing @code{\autoLineBreaksOff} or @code{\autoBreaksOff} before +any music will cause error messages to appear. Always place these +commands after some music. + @node Page breaking @subsection Page breaking @@ -1510,16 +1540,26 @@ how to modify them. @node Manual page breaking @unnumberedsubsubsec Manual page breaking +@funindex \pageBreak +@funindex \noPageBreak +@funindex \autoPageBreaksOn +@funindex \autoPageBreaksOff +@cindex page breaking, manual + 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 from happening. Of course, the @code{\pageBreak} -command also forces a line break. +page-break from happening at that bar line. Of course, the +@code{\pageBreak} command also forces a line break. The @code{\pageBreak} and @code{\noPageBreak} commands may also be inserted at top-level, between scores and top-level markups. +Within a score, automatic page breaks are prevented within music +lying between @code{\autoPageBreaksOff} and @code{\autoPageBreaksOn} +commands. Manual page breaks are unaffected by these commands. + There are also analogous settings to @code{ragged-right} and @code{ragged-last} which have the same effect on vertical spacing. If @code{ragged-bottom} is set to @code{#t} the systems will not @@ -1577,10 +1617,10 @@ functions may also be used in different book parts. @predefined -@funindex \pageBreak @code{\pageBreak}, -@funindex \noPageBreak -@code{\noPageBreak}. +@code{\noPageBreak}, +@code{\autoPageBreaksOn}, +@code{\autoPageBreaksOff}. @endpredefined @seealso @@ -1590,6 +1630,13 @@ Notation Reference: Snippets: @rlsr{Spacing}. +@knownissues + +The @code{\once} prefix is ineffective with @code{\autoPageBreaksOn} +and @code{\autoPageBreaksOff}. If auto page breaking is off and is +then turned on to permit a page break, it must remain on for a few +bars (the precise number of bars depends on the score) before being +turned off, else the opportunity to break the page will not be taken. @node Optimal page breaking @unnumberedsubsubsec Optimal page breaking @@ -1740,59 +1787,6 @@ Use only one @code{Page_turn_engraver} per score. If there are more, they will interfere with each other. -@node Explicit breaks -@subsection Explicit breaks - -There are cases when manual @code{\break} or @code{\pageBreak} -commands are ignored by LilyPond. There are two commands to -override this behavior: - -@example -\override NonMusicalPaperColumn.line-break-permission = ##f -\override NonMusicalPaperColumn.page-break-permission = ##f -@end example - -If @code{line-break-permission} is set to @code{##f}, all line -breaks must be explicitly inserted with a @code{\break} command. -Likewise, if @code{page-break-permission} is set to @code{##f}, -all page breaks must be explicitly inserted with a -@code{\pageBreak} command. - -@lilypond[quote,verbatim] -\paper { - indent = #0 - ragged-right = ##t - ragged-bottom = ##t -} - -music = \relative c'' { c8 c c c } - -\score { - \new Staff { - \repeat unfold 2 { \music } \break - \repeat unfold 4 { \music } \break - \repeat unfold 6 { \music } \break - \repeat unfold 8 { \music } \pageBreak - \repeat unfold 8 { \music } \break - \repeat unfold 6 { \music } \break - \repeat unfold 4 { \music } \break - \repeat unfold 2 { \music } - } - \layout { - \context { - \Score - \override NonMusicalPaperColumn.line-break-permission = ##f - \override NonMusicalPaperColumn.page-break-permission = ##f - } - } -} -@end lilypond - -@snippets - -@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle] -{using-an-extra-voice-for-breaks.ly} - @seealso Notation Reference: @ref{Vertical spacing}. @@ -2449,7 +2443,7 @@ by looking at an example that includes no overrides at all. This score isolates line- and page-breaking information in a dedicated voice. This technique of creating a breaks voice will help keep layout separate from music entry as our example becomes more complicated. -See @ref{Explicit breaks}. +See @ref{Breaks}. Explicit @code{\breaks} evenly divide the music into six measures per line. Vertical spacing results from LilyPond's defaults. To set diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely index a86c0acbab..a9914f3a72 100644 --- a/Documentation/notation/vocal.itely +++ b/Documentation/notation/vocal.itely @@ -2389,7 +2389,7 @@ Notation Reference: @ref{Score layout}, @ref{Separating systems}, @ref{Setting the staff size}, -@ref{Explicit breaks}, +@ref{Breaks}, @ref{Vertical spacing}. Internals Reference: diff --git a/ly/property-init.ly b/ly/property-init.ly index 8d6d892d17..28b9b5c2f1 100644 --- a/ly/property-init.ly +++ b/ly/property-init.ly @@ -352,6 +352,24 @@ kievanOff = { \revert NoteHead.duration-log } +%% line and page breaking controls + +autoLineBreaksOff = { + \overrideProperty Score.NonMusicalPaperColumn.line-break-permission ##f + \override Score.NonMusicalPaperColumn.line-break-permission = ##f +} +autoLineBreaksOn = { + \overrideProperty Score.NonMusicalPaperColumn.line-break-permission #'allow + \override Score.NonMusicalPaperColumn.line-break-permission = #'allow +} +autoPageBreaksOff = + \override Score.NonMusicalPaperColumn.page-break-permission = ##f +autoPageBreaksOn = + \override Score.NonMusicalPaperColumn.page-break-permission = #'allow +autoBreaksOff = { \autoLineBreaksOff \autoPageBreaksOff } +autoBreaksOn = { \autoLineBreaksOn \autoPageBreaksOn } + + %% merging mergeDifferentlyDottedOn = -- 2.39.2