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: Thu, 22 Feb 2024 09:44:40 +0200
> 
> > Thanks, but I wonder if we can be a tad more user-friendly?  The user
> > option exists, and it can accept simple enough data structures for
> > customizations, but the default is nil, and there's no example or
> > pre-cooked list of ready-to-use values anywhere in sight, not even in
> > the doc string.  Users will have to work hard to produce a grouping of
> > their liking.  E.g., suppose I want to group buffers by mode -- how
> > would I go about it?  Or what about grouping buffers by their leading
> > directories -- how can that be done?  Etc. etc. -- this could be a
> > very powerful feature, but we should make its use easier.  And, after
> > reading the documentation of tabulated-list-groups and that of
> > tabulated-list-entries several times, I have no idea how to specify
> > simple groupings such as those described above.  Which makes examples
> > or pre-cooked values even more important, IMO.
> 
> Ok, then this patch adds two pre-cooked functions as a starting point
> for users to understand the principle.  Then users will propose
> more functions and we will choose the most useful candidates
> for including to the set of default functions later.

Thanks.

> +@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.

> +(defcustom Buffer-menu-group-by nil
> +  "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'.  Also when this variable is non-nil,
> +then `outline-minor-mode' is enabled in the Buffer Menu.  Then with the
> +default value of `outline-regexp' you can use Outline minor mode commands
> +to show/hide groups of buffers.
> +The default options can group by a mode, and by a root directory of
> +a project or just `default-directory'."
> +  :type '(choice (const :tag "No grouping" nil)
> +                 (function-item :tag "Group by mode"
> +                                Buffer-menu-group-by-mode)
> +                 (function-item :tag "Group by root"
> +                                Buffer-menu-group-by-root)

I think the description text should be "Group by project" or "Group by
project root directory" or maybe "Group by project or directory".
Just "by root" is too vague.

> +If `tabulated-list-groups' is non-nil, each group of entries
> +is sorted separately after printing the group header line.

The part following "after printing" is IMO more confusing than
helpful.  What will be lost if you remove it?

> +(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?