Re: Regarding outline headings in emacs-lisp libraries

[Jonas Bernoulli <jonas@bernoul.li>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I don't have a strong opinion on this, but FWIW, I have a slight
> preference for the ";;;;" version over the ";;;" version (but it's very
> slight; I'm really OK either way.  In most cases I don't even notice
> the difference).

I definitely prefer the Code:-sibling approach, but if Emacs continues
to use and advertise the Code:-children approach, then I can live with
that.

What I care about more is that as many of Emacs' libraries as possible
use are split into sections.  I am happy to help with that task and if
I have to compromise on the nesting, so be it.

(For my own libraries will continue to use the sibling approach and if
Emacs sticks with the children approach, then I will probably have to
add a buffer-local variable to teach `bicycle-cycle-global' to skip the
overview state.)

> The annoyance you mention doesn't affect me, because I use

I think we will have to wait for more feedback then.  We would probably
want to hear from more than one person (me) that uses this in a way that
is even affected by whether we nest more or less.

> [ sorry, I somehow missed the end of your message on first reading.  ]

Ah... spaced out somewhere along the way. ;)

>> B) The OVERVIEW shown above isn't just not useful, for more complex
>>    libraries (which are split into more (sub*)sections) having a useful
>>    OVERVIEW is quite important.
>>
>>    For such libraries the TOC just isn't a suitable substitute for
>>    OVERVIEW.  It could be deeply nested and if one only wants a list
>>    of the "major sections of a program", then a deeply nested tree of
>>    sub*sections just isn't the same.
>
> I guess what I was saying in my previous message is that I haven't found
> a case of a file where the TOC is so large that it warrants the OVERVIEW.
> And I'd even claim that such a file would be just too large and should
> likely benefit from splitting it into a few files.

Okay, let's assume the benefit is tiny in almost all non-pathological
cases.  It's still a tiny benefit at least to have both the overview
and toc views.

Let's look at it from another perspective: what are the *benefits* of
making the "major code parts" children of "Code:"?  The only one that
I can think of is that the name of that section "Code" implies that it
contains all the code.  I would argue that is a just a tiny benefit as
well.  Also it might be that when the name of that section was chosen
little thought was given to the issue we are discussing now, so maybe
that name should not hold too much weight when deciding on this issue.

I think it comes down to: when it doubt, then do *not* add additional
hierarchies.  Only do that when there is some clear benefit.