bug#3249: 23.0.93; doc of transpose-subr and transpose-regions

[Drew Adams]

It seems that all transpose functions in Emacs are defined using
`transpose-subr'.  If you want to define your own transpose function,
then you will presumably use `transpose-subr' too.
 
But `transpose-subr' is not even documented, making it that much
harder to try to use it to define your own transpose function.  Please
add a helpful doc string.
 
It's apparently not as simple as providing a `forward-*' function and
a numeric arg N to `transpose-subr'.  That's what `transpose-chars',
`transpose-words', `transpose-paragraphs', and `transpose-sentences do
(using `forward-char' etc.), but that apparently is not adequate for
`transpose-lines' or `transpose-sexps'.
 
So it would, in particular, be helpful to know just what is needed as
the MOVER arg of `transpose-subr'.
 
Also, the Elisp manual, node Transposition, mentions only
`transpose-regions', saying that it is used by the transposition
commands.  But it is not - the transposition commands all use
`transpose-subr', and that doesn't even call `transpose-regions'
indirectly.
 
`transpose-regions' is used in the Elisp source code in only 4 places,
in deuglify.el, mule-diag.el, and hanoi.el - never to define a
transpose command.  And `transpose-subr' is used in just as many
files, not counting simple.el.
 
So what is the correct advice to give Elisp programmers who want to
define transpose functions?  Shouldn't `transpose-subr' be documented
in the Elisp manual, in addition to getting a doc string?
 
Also, why is `transpose-regions' still defined in C code? Is that
necessary for performance?
 

In GNU Emacs 23.0.93.1 (i386-mingw-nt5.1.2600)
 of 2009-05-02 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'