bug#6824: 24.0.50; Wdired doc. Doc string of wdired-change-to-wdired-mode.

bug#6824: 24.0.50; Wdired doc. Doc string of wdired-change-to-wdired-mode.

[Drew Adams]

emacs -Q
 
C-h f wdired RET
 
That shows the doc string of `wdired-change-to-wdired-mode', which ends
with this: "See `wdired-mode'."  The latter function (or var) is not a
link, but it should be.  Otherwise, how are you supposed to "see" it?
 
C-h r
i wdired
 
Takes you to node Wdired.  This node is woefully incomplete.  It tells
you very little about Wdired.  There is no Wdired manual, so this node
is all users have for doc.
 
Well, that and `C-h m', once they are in `wdired-mode'.  But that too is
nearly useless - far from complete.  This is all it says:
 
 File Names Editing mode.
 Press C-c C-c to make the changes to take effect and
 exit.  To abort the edit, use C-c ESC.
 In this mode you can edit the names of the files, the target of the
 links and the permission bits of the files.  You can `customize-group'
 wdired.
 Editing things out of the filenames, or adding or deleting lines is
 not allowed, because the rest of the buffer is read-only.
 
That's it.  Much of what it says is just how to turn it off!  The main
commands and keys for the mode should be described, at least summarily.
At least tell users how to use the mode and what operations they can
perform (e.g. how to toggle permissions).
 
And the link for `customize-group', which you might think would take you
to the Wdired Customize group, just gives you `C-h f customize-group' -
useless.  There is even a function, `wdired-customize', defined to
customize all of the Wdired options.  That is far better to use for a
link than is `customize-group'.
 
And what does this mean: "Editing things out of the filenames"?
 
The Wdired doc really needs to be improved to make Wdired more useful
and available.
 
Also, why use `Edit filenames' in the mode line? We should use a proper
mode name as the lighter, and use a single (possibly compound) word with
proper capitalization.  (This is UI, not doc per se, but is related.)


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

bug#6824: 24.0.50; Wdired doc. Doc string of wdired-change-to-wdired-mode.

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> emacs -Q
>  
> C-h f wdired RET
>  
> That shows the doc string of `wdired-change-to-wdired-mode', which ends
> with this: "See `wdired-mode'."  The latter function (or var) is not a
> link, but it should be.  Otherwise, how are you supposed to "see" it?

This is fixed in the trunk.