bug#28963: 24.5; doc string of `dired-find-alternate-file'

bug#28963: 24.5; doc string of `dired-find-alternate-file'

[Drew Adams]

This doc string needs improvement:

  In Dired, visit this file or directory instead of the Dired buffer.

The real meaning depends on what one understands by "instead of the
Dired buffer".  Many users will likely (mis)understand only that the
file or directory is visited in place of the current Dired buffer.
They won't understand that the current buffer will be killed.

If the idea is to keep the doc string short, it would be far more
helpful to say that it uses `find-alternate-file', because that command
has much better documentation.  In particular, it says explicitly: "kill
previous buffer".

It shouldn't be _necessary_ to keep the doc string to a minimum and only
reference `find-alternate-file'.  But if there is no desire to provide
the kind of info we provide for `find-alternate-file' then it would be
fine to just reference that function's doc.



In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#28963: 24.5; doc string of `dired-find-alternate-file'

[Eli Zaretskii]

> Date: Mon, 23 Oct 2017 19:07:02 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This doc string needs improvement:
> 
>   In Dired, visit this file or directory instead of the Dired buffer.
> 
> The real meaning depends on what one understands by "instead of the
> Dired buffer".  Many users will likely (mis)understand only that the
> file or directory is visited in place of the current Dired buffer.
> They won't understand that the current buffer will be killed.
> 
> If the idea is to keep the doc string short, it would be far more
> helpful to say that it uses `find-alternate-file', because that command
> has much better documentation.  In particular, it says explicitly: "kill
> previous buffer".

I did both, thanks.