`toggle-read-only' and `read-only-mode'

[Drew Adams]

`toggle-read-only' will apparently be declared obsolete in 24.3.

1. It seems to me that any functionality that users would expect from
`toggle-read-only' would pretty much be provided by `read-only-mode', and the
obselescence description supports that.

`read-only-mode' is more, but it at least does pretty much what
`toggle-read-only' does, unless I'm missing something.  They even interpret the
prefix arg the same way.

So why not make `toggle-read-only' an alias for `read-only-mode'?

That would not only help users, especially those used to `t-r-o'.  It would also
help maintainers of existing Lisp code that uses `toggle-read-only'.

For example, Emacs Dev had to change the definition of `find-file--read-only',
substituting `read-only-mode' for `toggle-read-only'.  Why should user code need
to be changed similarly?  Why not just alias `t-r-o' to `r-o-m'?


2. Also, it is not enough for `C-h f toggle-read-only' to say only:

 "This function is obsolete since 24.3;
  use `read-only-mode' instead."

That is not kosher at all.  It might be obsolete, and you might want to
recommend that users use `read-only-mode' instead.  But `t-r-o' still exists,
and it is still supported.

And its behavior is NOT exactly the same as that of `read-only-mode' (e.g. wrt
view mode).

There is now NO description of what `toggle-read-only' does.  Users deserve for
`C-h f' to tell them what it actually _does_, not just to tell them to use
`r-o-m' instead.

Taking the doc string away from a function or variable that you deprecate should
be a definite NO-NO.  Not good software development practice - very user
unfriendly, impolite.

(Oh, and Emacs convention calls for the two lines you do provide here for `C-h
f' to be separate sentences.)