bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

[Drew Adams]

As introduction, here is one user's attempt to understand the structure
of `ibuffer-saved-filter-groups':
http://emacs.stackexchange.com/q/2087/105

The user says: "I'm guessing at the predicate bit as I can't find any
examples or documentation. What should it really look like?"

1. The doc string for these variables should describe the structure
better.  It should not send readers off to look at the doc string of
internal variable `ibuffer-filtering-qualifiers', especially since that
doc string just says that a qualifier has the form (SYMBOL . QUALIFIER),
and it does not even say what form or type this QUALIFIER has as a Lisp
entity.

This would also encourage you not to use QUALIFIER in two completely
different ways: QUALIFIER ==> (SYMBOL . QUALIFIER).

The doc of the two user options even refers to the doc string of
`ibuffer-filtering-qualifiers' *twice*, unnecessarily.

2. The defcustoms of the user options should use something more specific
(so more useful to users) as the :type than just (repeat 'sexp).  A
better :type will help users customize the option and understand its
structure.  And if you try to specify the structure for defcustom :type
then maybe that will help you do a better job of describing it for
users in the doc string.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-06 on LEG570
Bzr revision: 118063 monnier@iro.umontreal.ca-20141006174756-y7ha091r491l1ijw
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 CPPFLAGS=-DGLYPH_DEBUG=1'

bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

[Drew Adams]

Besides which, the doc string of `ibuffer-filtering-qualifiers'
seems to be plain wrong, in saying that its form is
(SYMBOL . QUALIFIER), even though QUALIFIER is unfortunately
undefined.

If you plug (SYMBOL . QUALIFIER) in for the QUALIFIERS of
`ibuffer-saved-filters' (which supposedly has the same form as
`ibuffer-filtering-qualifiers') then `ibuffer-saved-filters' should
have this form:
(("STRING" (SYMBOL . QUALIFIER))
 ("STRING" (SYMBOL . QUALIFIER))...)

But that does not match the default value of `ibuffer-saved-filters',
which is more like this:
(("STRING" ((or (SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER)...)))
 ("STRING" ((or (SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER)...))))

And even if it is a mistake to say, in the doc of
`ibuffer-filtering-qualifiers', that it has the form
(SYMBOL . QUALIFIER), and that what is really meant is that it
is a *list of conses* (SYMBOL . QUALIFIER), the doc of
`ibuffer-saved-filters' still does not match its default value.

If we plug a list ((SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER) ...)
in for the QUALIFIERS of `ibuffer-saved-filters' then that option
should have this form:

(("STRING" ((SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER) ...))
 ("STRING" ((SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER) ...))
 ...)

But the default value has that pesky `(or ...)':

(("STRING" ((or (SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER)...)))
            ^^^
 ("STRING" ((or (SYMBOL . QUALIFIER) (SYMBOL . QUALIFIER)...))))
            ^^^

Something is wrong somewhere.  Perhaps more than one something.

bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

[Drew Adams]

> This would also encourage you not to use QUALIFIER in two completely
> different ways: QUALIFIER ==> (SYMBOL . QUALIFIER).

Sorry, my bad about that part.  The first one is QUALIFIERS, not
QUALIFIER.  So no problem with that.

bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

[Alexis]

Drew Adams writes:

> As introduction, here is one user's attempt to understand the structure
> of `ibuffer-saved-filter-groups':
> http://emacs.stackexchange.com/q/2087/105
>
> The user says: "I'm guessing at the predicate bit as I can't find any
> examples or documentation. What should it really look like?"

Fwiw, here's part of the value for `ibuffer-saved-filter-groups`, from
my config file:

---BEGIN---
  (setq ibuffer-saved-filter-groups
        '(("Home"
           ("Recent" (predicate buffer-is-recent-buffer-p (current-buffer)))
           ("Helm" (name . "\*helm.+"))
           ("Dev" (or (filename . ".+\.css$")
                      (filename . ".+\.html?$")
                      (mode . android-mode)
                      (mode . clojure-mode)
                      (mode . compilation-mode)                   
                      (mode . cperl-mode)
                      (mode . emacs-lisp-mode)
                      (mode . ert-results-mode)
                      (mode . perl-mode)
                      (name . "\*Backtrace.*")
                      (name . "\*cider-repl.+")
                      (name . "\*magit.+")
                      (name . "\*scratch.+")))
           ("Docs" (or (mode . doc-view-mode)
                       (mode . Info-mode)
                       (mode . irfc-mode)
           ...
---END---

`buffer-is-recent-p` is a function i've defined elsewhere in my config -
it returns `t` if the buffer was one of the last 5 buffers accessed. It
took some guessing to learn how `predicate` could be used in this
context ....


Alexis.

bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The user says: "I'm guessing at the predicate bit as I can't find any
> examples or documentation. What should it really look like?"
>
> 1. The doc string for these variables should describe the structure
> better.  It should not send readers off to look at the doc string of
> internal variable `ibuffer-filtering-qualifiers', especially since that
> doc string just says that a qualifier has the form (SYMBOL . QUALIFIER),
> and it does not even say what form or type this QUALIFIER has as a Lisp
> entity.

I've now added a modified version of the example that Alexis gave later
in this bug report.

> This would also encourage you not to use QUALIFIER in two completely
> different ways: QUALIFIER ==> (SYMBOL . QUALIFIER).
>
> The doc of the two user options even refers to the doc string of
> `ibuffer-filtering-qualifiers' *twice*, unnecessarily.

Digging down into all the doc strings that refer to each other, it seems
to me that the information is there, it just tries to avoid repeating
the same information in several doc strings.

But the example should help tremendously.

> 2. The defcustoms of the user options should use something more specific
> (so more useful to users) as the :type than just (repeat 'sexp).  A
> better :type will help users customize the option and understand its
> structure.  And if you try to specify the structure for defcustom :type
> then maybe that will help you do a better job of describing it for
> users in the doc string.

This has been fixed somewhat since this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no