bug#30085: 25.2: Documentation for cua-rectangle-mark-mode

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

bug#30085: 25.2: Documentation for cua-rectangle-mark-mode

Boruch Baum
`cua-rectangle-mark-mode' includes many features that I haven't found documented.

This minor mode clearly allows for several advanced features, as it
displays a helpful message on the mode line:

  C-?:help M-p:pad M-o:open M-c:close M-b:blank M-s:string M-f:fill M-i:incr M-n:seq

This is a particular shame since `cua-rectangle-mark-mode' seems much
more powerful and user-friendly than the collection of commands
that are documented in the `rectangles' section of the emacs manual.

However:

1. The documentation for the minor mode only says: "Toggle the region as
   rectangular. Activates the region if needed. Only lasts until the region
   is deactivated."

2. File `cua-rect.el' does not include a commentary of its features.

3. The emacs manual does have a section on `rectangles' that makes no
   mention of this minor mode.

4. An internet search for the feature or even its explicit name does
   not, at least prominently, yield any documentation.

5. The minor mode binds `C-?' to some help documentation. However, for
   users of emacs-nox such as myself, the keybinding `C-?' doesn't work.
   In this particular case, I did attempt the "usual" `C-@ c ?', but
   that also did not work. The standard `C-h' keybinding is available
   but unfortunately not used.

   5.1. Keybinding `C-?' invokes function `cua-help-for-rectangle' which
        does not look at all helpful over the one-line mode-line string.

6. The tail of file `cua-rect.el' includes keybindings for many features
   not listed in the mode-line doc-string, eg. `reverse-rectangle',
   `shell-command-on-rectangle'. See there for more.

File `cua-rect.el' list its author as Kim F. Storm <[hidden email]>, so
I've taken the liberty of cc'ing the author on the bug report. @Kim:
Your work seems like a great improvement over emacs' documented
rectangle support, but seems to have remained relatively unknown due to
lack of documentation. It should be front and center in any search for
emacs rectangle support.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0



Reply | Threaded
Open this post in threaded view
|

bug#30085: 25.2: Documentation for cua-rectangle-mark-mode

Eli Zaretskii
> Date: Fri, 12 Jan 2018 02:14:26 -0500
> From: Boruch Baum <[hidden email]>
>
> File `cua-rect.el' list its author as Kim F. Storm <[hidden email]>, so
> I've taken the liberty of cc'ing the author on the bug report. @Kim:
> Your work seems like a great improvement over emacs' documented
> rectangle support, but seems to have remained relatively unknown due to
> lack of documentation. It should be front and center in any search for
> emacs rectangle support.

Thanks for the comments.  Yes, cua-rect facilities are notoriously
under-documented.  I would suggest that you (or someone else who uses
cua-rect) propose specific patches to fix that, based on your
experimenting with the facility and code reading.  IME, this will
allow us to fill this gap much faster than any other alternative.

Of course, Kim's contributions to this effort will also be very
welcome.



Reply | Threaded
Open this post in threaded view
|

bug#30085: 25.2: Documentation for cua-rectangle-mark-mode

Kim Storm
On 2018-01-12 10:22, Eli Zaretskii wrote:

>> Date: Fri, 12 Jan 2018 02:14:26 -0500
>> From: Boruch Baum <[hidden email]>
>>
>> File `cua-rect.el' list its author as Kim F. Storm <[hidden email]>, so
>> I've taken the liberty of cc'ing the author on the bug report. @Kim:
>> Your work seems like a great improvement over emacs' documented
>> rectangle support, but seems to have remained relatively unknown due to
>> lack of documentation. It should be front and center in any search for
>> emacs rectangle support.
> Thanks for the comments.  Yes, cua-rect facilities are notoriously
> under-documented.  I would suggest that you (or someone else who uses
> cua-rect) propose specific patches to fix that, based on your
> experimenting with the facility and code reading.  IME, this will
> allow us to fill this gap much faster than any other alternative.
>
> Of course, Kim's contributions to this effort will also be very
> welcome.
>
Just a little history here:

In the original cua-mode file, everything was stashed together in
the same file, so I had to refactor the code before it wasincludedinEmacs 22.1So I ended up adding three files: cua-base.el
cua-gmrk.eland cua-rect.elknowing that documentation for some of the
more advanced stuff still needed some improvements. However, the other
emacs maintainers insisted that the cua-rect.el stuff didn't really have
anything to do with cua-mode as such, but rather should be merged into
the existing rect.el code. I agreed in principle, but didn't know how to
accomplish that, so I left it for someone else to do - and continued to
work on other stuff. Obviously, that merge never happened, and
therefore, the more advanced rectangle support in cua-rect stays
inaccessible for those who don't use cua-mode, and even for cua-mode
users, some features are probably not widely used due to lack of
documentation. So there are really two issues here: - merge cua-rect and
rect code - complete documentation for the combined package I might be
able to contribute on the second item, but I still don't know how to
accomplish the first.




Reply | Threaded
Open this post in threaded view
|

bug#30085: 25.2: Documentation for cua-rectangle-mark-mode

Kim Storm
In reply to this post by Eli Zaretskii
On 2018-01-12 10:22, Eli Zaretskii wrote:

>> Date: Fri, 12 Jan 2018 02:14:26 -0500
>> From: Boruch Baum <[hidden email]>
>>
>> File `cua-rect.el' list its author as Kim F. Storm <[hidden email]>, so
>> I've taken the liberty of cc'ing the author on the bug report. @Kim:
>> Your work seems like a great improvement over emacs' documented
>> rectangle support, but seems to have remained relatively unknown due to
>> lack of documentation. It should be front and center in any search for
>> emacs rectangle support.
> Thanks for the comments.  Yes, cua-rect facilities are notoriously
> under-documented.  I would suggest that you (or someone else who uses
> cua-rect) propose specific patches to fix that, based on your
> experimenting with the facility and code reading.  IME, this will
> allow us to fill this gap much faster than any other alternative.
>
> Of course, Kim's contributions to this effort will also be very
> welcome.
>
Just a little history here:

In the original cua-mode file, everything was stashed together in
the same file, so I had to refactor the code before it was included
in Emacs 22.1

So I ended up adding three files: cua-base.el cua-gmrk.eland cua-rect.el
knowing that documentation for some of the more advanced stuff still
needed some improvements.

However, the other emacs maintainers insisted that the cua-rect.el stuff
didn't really have anything to do with cua-mode as such, but rather should
be merged into the existing rect.el code.

I agreed in principle, but didn't know how to accomplish that, so I left
it for someone else to do - and continued to work on other stuff.

Obviously, that merge never happened, and therefore, the more advanced
rectangle support in cua-rect stays inaccessible for those who don't
use cua-mode, and even for cua-mode users, some features are probably
not widely used due to lack of documentation.

So there are really two issues here:
  - merge cua-rect and rect code
  - complete documentation for the combined package

I might be able to contribute on the second item, but I still don't
know how to accomplish the first.




Reply | Threaded
Open this post in threaded view
|

bug#30085: 25.2: Documentation for cua-rectangle-mark-mode

Eli Zaretskii
In reply to this post by Kim Storm
> Cc: [hidden email]
> From: Kim Storm <[hidden email]>
> Date: Fri, 12 Jan 2018 12:00:42 +0100
>
> So there are really two issues here: - merge cua-rect and rect code
> - complete documentation for the combined package I might be able to
> contribute on the second item, but I still don't know how to
> accomplish the first.

Let's just go with the second, and leave the first for another rainy
day.

Thanks.