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

[Eli Zaretskii <eliz@gnu.org>]

> From: Juri Linkov <juri@linkov.net>
> Cc: 69305@debbugs.gnu.org
> Date: Tue, 27 Feb 2024 09:30:10 +0200
> 
> >> >> >> Sorry, I don't understand what is unclear here:
> >> >> >>
> >> >> >>   If the value is a list, each list element corresponds to one group, and
> >> >> >>   should have the form @w{@code{(@var{group-name} @var{entries})}}, where
> >> >> >>   @var{group-name} is a string inserted before all group entries, and
> >> >> >>   @var{entries} have the same format as @code{tabulated-list-entries}
> >> >> >>   (see above).
> >> >> >>
> >> >> >> Basically this says that the format is (group-name entries) where
> >> >> >> entries are described in tabulated-list-entries as having the format
> >> >> >> (id contents).  There is no need to duplicate the description of entries.
> >> >> >
> >> >> > Maybe I'm missing something here.  To put it more concretely, can you
> >> >> > show a value of tabulated-list-groups that will cause the buffers in
> >> >> > buffer list grouped by major mode using the above form?
> >> >>
> >> >> Data structure for `tabulated-list-groups' is a list of elements,
> >> >> each element should of the form
> >> >>
> >> >>   (GROUP-NAME (ID . CONTENTS) (ID . CONTENTS) ...)
> >> >>
> >> >> where GROUP-NAME is the name of the group, ID is a Lisp object that
> >> >> identifies the entry and CONTENTS is a vector with the same number of
> >> >> elements as `tabulated-list-format'.  When buffers grouped by major mode:
> >> >>
> >> >>   (("* Lisp Interaction" (#<buffer *scratch*> ["." " " "*" #("*scratch*" 0 9 ...) "225" "Lisp Interaction" ""]) ...))
> >> >
> >> > This is the value that the user is supposed to supply for the
> >> > defcustom?  That is, the user must specify all the buffers explicitly?
> >> > What happens when there's one more buffer in some mode? does the user
> >> > have then to modify the value of the defcustom?
> >>
> >> This describes the internal data structure, not a defcustom.
> >
> > Well, my question above, viz.:
> >
> >>> > Maybe I'm missing something here.  To put it more concretely, can you
> >>> > show a value of tabulated-list-groups that will cause the buffers in
> >>> > buffer list grouped by major mode using the above form?
> >
> > was about the value of this defcustom.  I hoped that by having such a
> > value as part of this discussion, we will be able to clear any
> > misunderstandings that could be getting in the way.
> 
> 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.
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.