Edge cases in TOC hierarchies

[Jean Abou Samra]

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