bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined

[Drew Adams <drew.adams@oracle.com>]

> > > > ALIST is mentioned only here:
> > > >
> > > >  ACTION is a cons cell (FUNCTION . ALIST), where FUNCTION is a
> > > >   function or a list of functions.  Each such function should
> > > >   accept two arguments: a buffer to display and an alist of the
> > > >   same form as ALIST.  See `display-buffer' for details.
> > > >
> > > > "of the same form as ALIST"?  Really?  What form is that?  Where is
> > > > *anything* said about the form of ALIST?
> > >
> > > It's an alist.  And you are referred to the documentation of
> > > 'display-buffer' for details.  I see nothing wrong with that.
> >
> > No, you are referred to `display-buffer' for ACTION - for info about
> > everything in the ACTION paragraph.
> 
> Since (see above) "ACTION is a cons cell (FUNCTION . ALIST)",
> describing ACTION also describes ALIST, which is part of ACTION.  IOW,
> "everything in the ACTION paragraph" includes ALIST.

The very next sentence I wrote is key:

  Nothing says that the ALIST here is related to the ALIST mentioned
  for `display-buffer', at all.

That's the point.  If ALIST here is the same as ALIST in the
`display-buffer' description, then it is sufficient to refer
to the latter.

And in that case, it is wise remove anything else said for `d-b-a'
about ALIST - it can only confuse, if the `d-b' description of ALIST
is necessary & sufficient.

If the ALIST for `d-b' is only related, but not quite the same thing,
then please describe the ALIST for `d-b-a' fully in its own doc.
If helpful, please say also how it is related to the ALIST described
for `d-b'.  As I said:

  Or if it is related somehow, nothing says how it is related.

> The documentation of 'display-buffer' describes ACTION, and as part of
> that describes ALIST.

Nothing says that the ACTION described for `display-buffer-alist'
is the same as the ACTION described for `display-buffer'.

Same problem - see above.  If they are exactly the same, then
it is enough to say that - "Go see the doc of `display-buffer' for
ACTION and ALIST" - and do not describe ACTION and ALIST beyond
that.

If they are similar but not the same in all respects, then either
say nothing, in the `d-b-a' doc, about the `d-b' ACTION and ALIST
components  or explain the relation between those names for `d-b-a'
and the same names for `d-b'.

> This explicitly tells that ALIST is passed as argument to each
> function in the list, and should be interpreted and handled by these
> functions.  And now it should be clear why ALIST is arbitrary: its
> form and semantics are entirely up to the author of the called
> functions.

That tells us nothing about `display-buffer-alist'.  And in
particular nothing about the ACTION and ALIST that are mentioned in
the description of `display-buffer-alist'.

> > In that case, we are left wondering, not about some predefined but
> > unspecified form that ALIST must have, but rather what could possibly
> > even be meant by the "form" that it takes concretely.  IOW, we wonder
> > what kind of form conformance is required for the alist arg that
> > FUNCTION must accept - in what way must it agree with the "form" of
> > ALIST?
> 
> I don't understand the cause of your confusion about the form.  The
> form of an alist is well known (and the doc string of 'display-buffer'
> even spells out its full name -- "association list" -- to make it even
> more clear.  What else should or could be said about the _form_ of an
> alist whose components are up to the person or program that creates
> that alist??

What is missing is the relation between the alists mentioned in the
doc of `display-buffer-alist' and the alists mentioned in the doc
of `display-buffer'.

It is not enough to talk about "alists" in both cases, and to
mention structure components that happen to be called "ACTION" and
"ALIST" in both cases.  And to mumble something vague about "an alist
of the same form as ALIST" (whose form is completely unspecified).

Something needs to be said about the relation between each of
these components for `d-b-a' and for `d-b'.  Or else "ACTION" and
"ALIST" need to be defined for `d-b-a'.

> > But do with the doc string what you like.  If you find it perfectly
> > clear, more power to you.  I'm just reporting that I find it
> > confusing and not so helpful.  HTH.
> 
> I'm sorry, but I don't see how your report could be used to improve
> the docs.  You claim that information is missing which is actually
> there, and I pointed it out above.

No, you did not.  You simply pointed out the obvious, which was
the point of departure for the bug description: the same names
are used in two different doc descriptions, and one description
refers to the other.  It is not clear that the terms (which are
formal parameter/structure names) stand for the same things.

> You didn't identify any confusing parts in the docs, 

I certainly tried to.  I would not have bothered to file a bug
report if I didn't think the doc was confusing.  I don't
intentionally waste your time and my own.

> Would you please re-read the doc strings with the above in mind, and
> point out what's confusing and/or suggest how to improve the existing
> documentation?

See above.  If it helps, great.  If not, so be it.  To repeat:

  But do with the doc string what you like.  If you find it perfectly
  clear, more power to you.  I'm just reporting that I find it
  confusing and not so helpful.  HTH.