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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 22 Feb 2024 21:10:45 +0200

> From: Juri Linkov <[email-masked]>
> Cc: [email-masked]
> Date: Thu, 22 Feb 2024 19:30:20 +0200
> 
> >> +@defvar tabulated-list-groups
> >> +This buffer-local variable specifies the groups of entries displayed in
> >> +the Tabulated List buffer.  Its value should be either a list, or a
> >> +function.
> >> +
> >> +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).
> >> +
> >> +Otherwise, the value should be a function which returns a list of the
> >> +above form when called with no arguments.
> >> +@end defvar
> >
> > I think the way to specify ENTRIES for this customization should be
> > described in more detail.  Reading the above description, even the
> > idea of using ENTRIES for specifying grouping is unclear, since
> > tabulated-list-entries is basically just a list of column descriptors.
> 
> But ENTRIES are described in 'tabulated-list-entries'.  Here ENTRIES
> are no different from 'tabulated-list-entries' that are just
> column descriptors.

My point is that it isn't obvious how to describe grouping in terms of
column descriptors.  I think the manual should tell in more detail how
to use column descriptors to specify how entries should be grouped.
Maybe an example or two is all that it takes to do that.

> >> +(ert-deftest tabulated-list-groups ()
> >> +  (with-temp-buffer
> >> +    (tabulated-list-mode)
> >> +    (setq tabulated-list-groups
> >> +          (reverse
> >> +           (seq-group-by (lambda (b) (concat "* " (aref (cadr b) 3)))
> >> +                         tabulated-list--test-entries)))
> >> +    (setq tabulated-list-format tabulated-list--test-format)
> >> +    (setq tabulated-list-padding 7)
> >> +    (tabulated-list-init-header)
> >> +    (tabulated-list-print)
> >
> > This seems to test only the function value of tabulated-list-groups?
> > What about the other form of the value?
> 
> The other forms have no functional difference.

Sorry, I don't follow.  Shouldn't we test the capability of specifying
grouping by the method other than by providing a function?