all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: Jens Lechtenboerger <lechten@wi.uni-muenster.de>, 26233@debbugs.gnu.org
Subject: bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist
Date: Fri, 24 Mar 2017 07:51:06 -0700 (PDT)	[thread overview]
Message-ID: <1a350894-ae16-4706-888f-6575cdc559ec@default> (raw)
In-Reply-To: <87o9wq6c31.fsf@wi.uni-muenster.de>

> in Bug#25946 we discussed how to replace the obsolete variables
> special-display-buffer-names and special-display-regexps.  The
> attached patch extends the doc string of display-buffer-alist
> based on that discussion.

FWIW:

1. I *strongly* object to the deprecation of these user
options.

Instead of deprecating them, we should not only continue
to support them, as we have been doing, but fully
document and even promote them.  If they did not exist
then Emacs would be well advised to invent them, as they
are convenient, _simple_ ways to specify special-display
of buffers.

"Special-display" is a thing.  Or at least it was.
Now, the term has been liquidated from the manual.
The only vestige of it is in the description of menu
"`Display Property': Enabling special display features."
That's unfortunate for users.

It is fine to have introduced a generalization, which
was done with `display-buffer-alist' etc.  It is not
fine to remove these simple, easy-to-use ways of
expressing common use cases.

2. The patch, though it proceeds from a good motivation
no doubt, can suggest that adding that code or similar
(e.g. some other regexp) in your init file will give you
the behavior of those deprecated options, in general.
That impression would be incorrect.

First, there are two such options, not just the
`-regexps' one.  More importantly are the so-called 
"alternative" forms of the option values - two 
"alternatives" for each option.  Just one example such 
as that given indicates nothing about these 
possibilities.

These options, and users, deserve a complete description
of how to get their full behavior using the more general
apparatus (`display-buffer-alist' etc.).  We should have
a section in the manual that describes these options and
"special-display" in general, just as was the case in
the past.

In that section it should be shown how this or that
behavior, which you can obtain simply using these
options, can also be had using `display-buffer-alist'.

I can almost guarantee that if we did that, then, as
a side benefit (and one that is sorely needed, IMO),
users would come away with a better understanding of
`display-buffer-alist' itself, and how to use it.
To this day - years after it was introduced - users
(including me) are still in the dark and confused
about `display-buffer-alist'.

IOW, introduce these options as first-class citizens,
and show _how they correspond_ to the more general
apparatus.

3. I also object to the way the doc strings for these
options were changed, to suggest that the "alternative"
value forms are perhaps only arcane or less-important
"alternatives".

Originally, the doc strings just said, outright, that
there are 3 forms the value can take: 1, 2, 3.  None
of those forms were relegated to the background, as
an afterthought or as something obscure or inferior.
Though simple to use, these are powerful options,
which should not be trivialized.

Users should be encouraged to use these options
whenever they do the job needed, and to use the more
general constructs when they need something else.

Instead, we've hidden these simple constructs, told
users that they are now deprecated, and tossed users
immediately onto the rocks of `display-buffer-alist'
as their only resort, even for these simple use cases.
That's not right.

Just one opinion.





  reply	other threads:[~2017-03-24 14:51 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-03-24 13:25 bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist Jens Lechtenboerger
2017-03-24 14:51 ` Drew Adams [this message]
2017-03-25  7:53   ` Jens Lechtenboerger
2017-03-25  8:32     ` Eli Zaretskii
2017-03-25 14:58       ` Jens Lechtenboerger
2017-03-25 15:57         ` Eli Zaretskii
2017-03-25 17:14           ` Jens Lechtenboerger
     [not found]   ` <<878tnt6bdi.fsf@informationelle-selbstbestimmung-im-internet.de>
     [not found]     ` <<83shm1bvud.fsf@gnu.org>
2017-03-25 14:36       ` Drew Adams
2017-03-26  8:38         ` martin rudalics
2017-03-26 14:17           ` Eli Zaretskii
2017-03-26 17:45           ` Drew Adams
2017-03-24 18:54 ` martin rudalics
2017-03-25  8:00   ` Jens Lechtenboerger
2017-03-25  9:28     ` martin rudalics
2019-06-24 16:54   ` Lars Ingebrigtsen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1a350894-ae16-4706-888f-6575cdc559ec@default \
    --to=drew.adams@oracle.com \
    --cc=26233@debbugs.gnu.org \
    --cc=lechten@wi.uni-muenster.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.