GNU bug report logs - #69305
outline-minor-mode for tabulated-list-mode

Previous Next

Full log

View this message in rfc822 format

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69305 <at> debbugs.gnu.org
Subject: bug#69305: outline-minor-mode for tabulated-list-mode
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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.