Re: Edge cases in TOC hierarchies

[Nate Whetsell]

Hi all,

I’m quite new to LilyPond development, so please take this well-salted.

> …I am not sure what the reason was for making \tocItem take a symbol list as 
> first argument in the first place instead of a mere level of nesting depth as 
> an integer:

For what it’s worth, I’m very much in favor of having \tocItem’s first argument 
be a nesting depth instead of a symbol list.

The only thing I can add is that, in some cases, a (signed) integer 
representing a relative level may be more useful than an absolute nesting 
level. Using relative levels, any positive integer would mean the \tocItem 
would become a child of the previous one, and negative integers would decrease 
the nesting depth:

\tocItem "foo" % Level 0
\tocItem 1 "bar" % Level 1, nested in foo
\tocItem 100 "baz" % Nested in bar
\tocItem "bla" % Also nested in bar
\tocItem -1 "spam" % Nested in foo

Where I think this would come in handy is creating a big list of bookmarks by 
\include-ing several files that all have their own \tocItems. As long as

\tocItem 1 "foo"

put "foo" at level 0 when it’s the first \tocItem encountered, then

\tocItem "oof"
\include "file.ly" % this file contains \tocItem 1 "foo"

would result in oof at level 0 with foo as a child at level 1, but one could 
still compile file.ly on its own to get foo at level 0.

(The idea of a relative bookmark level is from LaTeX’s bookmark package: 
https://ctan.org/pkg/bookmark.)

Thanks,
Nate

> On Mar 7, 2022, at 4:42 PM, Jean Abou Samra <jean@abou-samra.fr> wrote:
> 
> Hi,
> 
> Moving part of https://gitlab.com/lilypond/lilypond/-/issues/6302
> to the mailing list as it's a general design issue. The TOC outline
> code has problems with Guile 2. It's easy to fix, but as the code
> generally has some quality issues (e.g. comparing numbers with eq?
> which relies on optimizations), I'd like to take the opportunity
> to clean it up a bit. My question is: what should this do?
> 
> \version "2.23.7"
> 
> \markuplist \table-of-contents
> 
> \tocItem foo "foo"
> \tocItem baz "baz"
> \tocItem foo.bla "foo.bla"
> 
> { c'1 }
> 
> Currently, in the TOC, this puts the entries in order, disregarding
> the symbol paths, and in the PDF bookmarks (with the fix for the
> basic issue), it isn't handled well: "baz" becomes a child of
> "foo" because "foo" declares it has one child (thinking it will
> be "foo.bla" coming next). There is a code comment:
> 
>     ;; TODO -- properly handle non-linear parent-children
>     ;; relationships (within the format's limitations) -vv
> 
> I am not sure if this is the sort of thing this refers to.
> 
> There is also:
> 
> \version "2.23.7"
> 
> \markuplist \table-of-contents
> 
> \tocItem jump.straight.in.nested.levels.without.intermediate.ones "bla"
> 
> { c'1 }
> 
> of which another example is
> 
> \version "2.23.7"
> 
> \markuplist \table-of-contents
> 
> \tocItem foo.bar "foo.bar"
> \tocItem baz.bla "baz.bla"
> 
> { c'1 }
> 
> What should we do with these? I'm inclined to think that "GIGO"
> and whatever behavior they end up triggering is not important,
> but then I am not sure what the reason was for making \tocItem
> take a symbol list as first argument in the first place instead
> of a mere level of nesting depth as an integer:
> 
> \tocItem "foo" % Level 0
> \tocItem 1 "bar" % Level 1, nested in foo
> \tocItem 2 "baz" % Nested in bar
> \tocItem 2 "bla" % Also nested in bar
> \tocItem 1 "spam" % Nested in foo
> etc.
> 
> Thoughts on a strategy here?
> 
> Thanks,
> Jean
>