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

From: Boruch Baum <[email-masked]>
Date: Fri, 12 Jan 2018 02:14:26 -0500

`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 <[email-masked]>, 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