Re: What should the relation between \book / \bookpart be?

Simon Albrecht <[email protected]> writes:

> Hi David,
>
> I’m afraid I don’t follow all of your writing, probably because I
> don’t have an understanding of how/why an “amended copy” of a \book {}
> would be used, as in
>
> On 07/08/2026 15:45, David Kastrup wrote:
>> bookA = \book { ... }
>> bookB = \bookpart { ... }
>>
>> \book { \bookA ... }
>>
>> which would mean to create a book as an amended copy of \bookA

bookA can just contain common headers and possibly a common introduction
for a number of books (like solfeges for soprano, alto, tenor, bass).

> In my understanding, there is or should be a direct relation between
> \book{} statements and output files. One \book{} statement can
> correspond to 0 or 1 output files per backend/output file format, but
> never two. Allowing syntax like
>
> \book { \book {} }
>
> or
>
> \book {
>   \book {}
>   \book {}
> }
>
> would not make sense based on that direct relation and only lead to
> confusion. Am I wrong?

Your nested book statement may actually look like \include
"volumeIII.ly" for a compilation of standalone pieces in one PDF.

It could also look like

volumeI = \book { \include "volumeIII.ly" }

\book {
  ...
  \bookpart { \volumeI }
  ...
}

> Is there ever a use case that would necessitate nested \book{}
> environments?

The point is that they would not, in effect, be nested book
environments.  In execution, the nested book would be downgraded to act
like a bookpart in that it would not produce a file of its own but be
part of the surrounding book.

What that means for things like "number-by-bookpart" is of course a
recipe for further headaches.

> Hence I would strongly lean toward this:
>
> On 07/08/2026 20:21, David Kastrup wrote:
>> [Possibility 1:] a book or bookpart gets stamped at creation
>> for being one or the other depending on whether it is done using \book
>> or \bookpart.  This is sticky and determines the allowable use.
>
> Having a hard and fast rule here creates clarity and leads users
> toward structuring their projects in an understandable and useful way.
>
> On 07/08/2026 15:45, David Kastrup wrote:
>> For rearranging an existing source into something that is only a part of
>> a larger document, the current relative fluidity between book and
>> bookpart may be convenient.
>
> It may be convenient, but allows for tangled up projects that are hard
> to understand and maintain.

The idea is not as much "tangled up" rather then being able to treat a
nested project as a black box.  That is kind of the appeal of nested
scopes and variables.

There is a point in trying to go there.  The question is whether that
point is good enough.  The results need to be something one can sensibly
describe in documentation and that people feel confident relying on.

One thing to note is people _hate_ having to write

xxx = \book { ... }
yyy = #(define-scheme-function () () #{ \book { ... } #})
\book { \xxx }
\book { \yyy }

instead of

xxx = \book { ... }
yyy = #(define-scheme-function () () #{ \book { ... } #})
\xxx
\yyy

but LilyPond does need to know whether to create two separate files or
not.  And currently the Scheme structures created by \book and \bookpart
cannot really be told apart.  The results of

xxx = \book { ... }

and

xxx = \bookpart { ... }

cannot reliably be told apart.  And I am trying to figure out whether to
change that, and how hardboiled the difference should be.

-- 
David Kastrup