GNU bug report logs - #3249
23.0.93; doc of transpose-subr and transpose-regions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3249 in the body.
You can then email your comments to 3249 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.93; doc of transpose-subr and transpose-regions
Date: Sat, 9 May 2009 08:56:59 -0700

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

Message #10 received at 3249 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Andreas Röhler <andreas.roehler <at> easy-emacs.de>
To: Drew Adams <drew.adams <at> oracle.com>, 3249 <at> debbugs.gnu.org
Subject: Re: bug#3249: 23.0.93; doc of transpose-subr and transpose-regions
Date: Sat, 09 May 2009 22:25:36 +0200

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

Message #17 received at 3249-done <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: 3249-done <at> debbugs.gnu.org
Subject: Re: 23.0.93; doc of transpose-subr and transpose-regions
Date: Sat, 28 Jan 2012 11:56:38 +0800

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.