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

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)'
 

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

[Andreas Röhler]

Drew Adams wrote:
> 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)'
>  
>
>
>
>
>
>
>   

Would assume sorting faster with transpose-regions' than with present
`sort-subr'.

Thanks pointing at it.
Employed it for the stuff at

https://code.launchpad.net/s-x-emacs-werkstatt/

Andreas Röhler

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

[Chong Yidong]

> `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.

Glenn wrote a docstring for transpose-subr several months ago.  Closing.