Re: Protecting against page breaks in markup

[Richard Shann]

On Thu, 2018-11-29 at 22:53 +0100, Thomas Morley wrote:
> Hi Richard,
> 
> please bear in mind I'm not a native speaker.
> Thus work on the docs is pretty difficult for me.
ok - I'll take that as welcoming further tweaks to the wording ...
below
> 
> That said:
> 
> Am Do., 29. Nov. 2018 um 11:04 Uhr schrieb Richard Shann
> <address@hidden>:
> > On Thu, 2018-11-29 at 09:50 +0100, Thomas Morley wrote:
> > > Well, in NR 1.8.1 Writing text one can read about toplevel
> > > markup/markuplist:
> > > "
> > > Separate text
> > > ...
> > > Separate text blocks can be spread over multiple pages, making it
> > > possible to print text documents or books entirely within
> > > LilyPond.
> > > This feature, and the specific syntax it requires, are described
> > > in
> > > Multi-page markup.
> > > ...
> > > "
> > > 
> > > And later
> > > 
> > > "
> > > Multi-page markup
> > > 
> > > Although standard markup objects are not breakable, a specific
> > > syntax
> > > makes it possible to enter lines of text that can spread over
> > > multiple
> > > pages:
> > > "
> > > 
> > > Could you suggest how to improve this?
> > 
> > Yes, I think I can. The presence of the word "Although" in the
> > last-
> > quoted paragraph indicates that the writer expected that the fact
> > that
> > standard markup objects were not breakable had been documented
> > elsewhere.
> 
> I think "standard markup" is a little foggy.
> Probably:
> "Although text objects 
well, graphics too, anything gobbled up by \markup
> invoked with \markup are not breakable, ..."

Although breaks will not be generated within the output of \markup
expressions ...


> 
> and in NR 1.8.1
> 
> Separate text
> ...
> 
> Separate text entered with \markup can't be distributed over multiple
> pages, thus a a page break will happen only before or after the whole
> text. In extreme cases the text will exceed the paper bottom.

In the worst case the text will run off the bottom of the page.

(Hmm, that is rather idiomatic English - 
In the worst case the text will overrun the bottom margin and be
trucated.)

> Nevertheless, separate text blocks can be spread over multiple pages,
> making it possible to print text documents or books entirely within
> LilyPond. This feature, and the specific syntax it requires, are
> described in Multi-page markup.
> 
> 
> > I suggest
> > 
> > "4.3.2 Page breaking
> > 
> > The default page breaking may be overridden by inserting \pageBreak
> > or
> > \noPageBreak commands. "
> > 
> > could become
> > 
> > "4.3.2 Page breaking
> > 
> > By default page breaks may be inserted at bar lines and between
> > top-
> > level markups. The default page breaking may be overridden by
> > inserting
> > \pageBreak or \noPageBreak commands. "
> 
> Quoting a little more from NR:
> "The default page breaking may be overridden by inserting \pageBreak
> or \noPageBreak commands. These commands are analogous to \break and
> \noBreak. They should be inserted at a bar line.
> [...]
> The \pageBreak and \noPageBreak commands may also be inserted at
> top-level, between scores and top-level markups."
> 
> Does it not contain all what's needed to know?

Yes - that was my point: it contains all that is needed, but obliquely,
saying \pageBreak can be placed between toplevel markups hints that
automatic breaking will not occur within them and manual page breaks
cannot be placed within them.

Richard