bug#69305: outline-minor-mode for tabulated-list-mode

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 69305@debbugs.gnu.org
> Date: Wed, 28 Feb 2024 09:36:30 +0200
> 
> >> >> But tabulated-list-groups is not a defcustom.
> >> >> There are no defcustoms here.
> >> >
> >> > Buffer-menu-group-by _is_ a defcustom, and it is documented thusly:
> >> >
> >> >   +  "If non-nil, buffers are grouped by function.
> >> >   +This function takes one argument: a list of entries in the same format
> >> >   +as in `tabulated-list-entries', and should return a list in the format
> >> >   +suitable for `tabulated-list-groups'.
> >> >
> >> > So you are inviting users to write functions that return values of a
> >> > certain format, but the format's documentation IMO doesn't make it
> >> > clear how to specify a grouping, and for its important part alludes to
> >> > another variable (tabulated-list-entries), whose documentation is
> >> > suitable for different kind of uses, not for grouping of entries.
> >> 
> >> The format 'tabulated-list-entries' is input.
> >> The format 'tabulated-list-groups' is output.
> >
> > Yes, I'm well aware of that.
> >
> >> > Since tabulated-list-groups is such an important part of the
> >> > documentation of Buffer-menu-group-by, the doc string of
> >> > tabulated-list-groups is in effect part of the doc string of
> >> > Buffer-menu-group-by, and should IMO be worded as appropriate for user
> >> > options.
> >> 
> >> The docstring of 'tabulated-list-groups' already
> >> sufficiently documents the format:
> >
> > No, it doesn't document it sufficiently.  As I already said several
> > times.
> >
> >>   (defvar-local tabulated-list-groups nil
> >>     "Groups displayed in the current Tabulated List buffer.
> >>   This should be either a function, or a list.
> >>   If a list, each element has the form (GROUP-NAME ENTRIES),
> >>   where:
> >> 
> >>    - GROUP-NAME is a group name as a string, which is displayed
> >>      at the top line of each group.
> >> 
> >>    - ENTRIES is a list described in `tabulated-list-entries'.
> >> 
> >> There is no need to duplicate the description of linked
> >> 'tabulated-list-entries'.
> >
> > This is not about duplication.  This is about adding information that
> > currently isn't there.
> >
> >> And here it's clear that the function should add GROUP-NAME to
> >> groups from 'tabulated-list-entries'.
> >
> > Which doesn't clarify the issue at hand even a single bit.
> 
> Sorry, I don't understand what is missing here.
> Please show an example of changes that you want.

Sorry, I cannot show an example of something whose use I don't
understand.  Which is why I asked _you_ to show an example: how to set
up Buffer-menu-group-by to group buffers by major-mode.