Subject: bug#7865: 24.0.50; doc of display-buffer-reuse-frames

From: "Drew Adams" <[email-masked]>
Date: Wed, 19 Jan 2011 08:47:45 -0800

This option is used in only `display-buffer', in a test that is
essentially (or pop-up-frames display-buffer-reuse-frames ...)
 
That means that this option has no effect if `pop-up-frames' is non-nil.
This should be made clear wherever `display-buffer-reuse-frames' is
documented.  (Alternatively, make it clear in one place and
cross-reference that place from the others.)
 
These are the places it is documented:
 
1. Elisp manual, node `Displaying Buffers'
2. Elisp manual, node `Choosing Window'
3. Emacs manual, node `Select Buffer
4. Doc string
 
Only in #1 is this made clear: "If either of the variables
`display-buffer-reuse-frames' or `pop-up-frames' is non-`nil'...".
(Although "option" would be better than "variable" here - and
throughout.)
 
Each of the other spots describes the option without mentioning this.
Either add this info to #2 and #3 or reduce/remove their descriptions of
the option and just cross-reference to the full description in #1 that
does mention this.
 
In any case, the doc string should mention it.
 
Finally, the description of this option in #3 just ends with this: "If
there is no such window or `display-buffer-reuse-frames' is `nil', the
behavior of `display-buffer' is determined by the variables described
next."
 
There follow descriptions of 15 other user options!  Does that sentence
mean all 15 or just the first two, which are followed by the description
of a function?  `pop-up-frames' is one of the 15, but it appears after
the function description, as the 6th option after
`display-buffer-reuse-frames'.  And of course `pop-up-frame' determines
the behavior even if `display-buffer-reuse-frames' is non-nil - its
description should come first.
 
Just remove that last sentence, please - it is confusing and doesn't say
anything.  If you want, replace it with a sentence saying only that when
it is nil it has no effect on the buffer display (other things come into
play to govern the behavior).

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-01-17 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'