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

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

[Drew Adams]

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?


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

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

[Eli Zaretskii]

> Date: Sun, 11 Jan 2015 18:12:04 -0800 (PST)
> From: 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.

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

[Drew Adams]

> > 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.  Nothing says that the ALIST here
is related to the ALIST mentioned for `display-buffer', at all.
Or if it is related somehow, nothing says how it is related.

The ALIST mentioned for `display-buffer' is described in its doc
string only as "an arbitrary association list (alist)."  Arbitrary.
That doesn't jibe well with "of the same form as ALIST" in the
description of `display-buffer-alist', which suggests that the ALIST
mentioned for `display-buffer-alist' has some particular form,
unspecified here.

Or else it suggests that, whatever the form an ALIST for
`display-buffer-alist' might have in any given concrete instance,
the alist to be accepted as arg to each FUNCTION must have that
same form.

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?

My guess is that, at the very least, there is some misleading text
to remove here. The description now is a puzzle.

If there is nothing to say about ALIST, so that it is simply an
"arbitrary" alist, then I'd say that nothing more should be said
about it - certainly nothing suggesting that it might need to
have a particular form.

If there is some agreement ("form" or otherwise) that must be had
between ALIST and the alist arg accepted by FUNCTION, then please
spell out what is meant by that.  For example, if the keys in the
alist accepted by FUNCTION must be a subset of the keys in the
actual ALIST for `display-buffer-alist', then say that.  (That's
just a made-up example - I have no idea what the real constraint
being suggested here might be.)

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.

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

[Eli Zaretskii]

> Date: Sun, 11 Jan 2015 21:14:47 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 19571@debbugs.gnu.org
> 
> > > 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.

> Nothing says that the ALIST here is related to the ALIST mentioned
> for `display-buffer', at all.  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.  See below.

> The ALIST mentioned for `display-buffer' is described in its doc
> string only as "an arbitrary association list (alist)."  Arbitrary.

That's not all 'display-buffer's doc has to say about ALIST.  It also
says:

  The `display-buffer' function builds a function list and an alist
  by combining the functions and alists specified in
  `display-buffer-overriding-action', `display-buffer-alist', the
  ACTION argument, `display-buffer-base-action', and
  `display-buffer-fallback-action' (in order).  Then it calls each
  function in the combined function list in turn, passing the
  buffer as the first argument and the combined alist as the second
  argument, until one of the functions returns non-nil.

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.

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

> 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.  You didn't identify any confusing
parts in the docs, nor suggested improvements to the existing text.
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?

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Sun, 18 Jan 2015 13:12:03 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 19571@debbugs.gnu.org
> 
> > > > > 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.

It's the same word, and there are no other ALISTs around, so why
wouldn't it be?

We use the same word for the same thing all over the place, and the
last thing I'd imagine is that someone could not understand they mean
the same.

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

OK, closing.