RE: Transposing words over middle words

[Drew Adams <drew.adams@oracle.com>]

> >> By the way, what does `special' do?
> >>
> >> ;; FIXME document SPECIAL. (defun
> >> transpose-subr (mover arg &optional special)
> >> "Document SPECIAL" - good idea :)
> >
> > https://debbugs.gnu.org/cgi/bugreport.cgi?bug=29328
> 
> Good. Now it says so in the source, I said
> it here, and you said it on debbugs.
> That should be enough.

Alas, far from enough.

The bug was was closed summarily, under the pretext
that it's impossible to describe parameter SPECIAL,
and that this is only an "internal subroutine" so
it need not have complete doc.

IOW, we don't know how to describe it, and we don't
need to tell _you_ what it is anyway, lusers.
Oh, and asking for this information is annoying
"bike-shedding".  Circulez ! Il n'y a rien a voir.

So the full gamut of lame reasons: It's internal;
it's unimportant; and we couldn't possibly describe
it even if we wanted to.

Anyone trying to define their own transposition
function will likely need to use `transpose-subr'
(that's what its for).  So I can't imagine why it
should be considered "internal".

To me, this is like saying that `sort-subr' is
internal.  A whole section of the Elisp manual is
devoted to that workhorse "subroutine".

http://www.gnu.org/software/emacs/manual/html_node/elisp/Sorting.html