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

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 <storm@cua.dk>, 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

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

[Eli Zaretskii]

> Date: Fri, 12 Jan 2018 02:14:26 -0500
> From: Boruch Baum <boruch_baum@gmx.com>
> 
> File `cua-rect.el' list its author as Kim F. Storm <storm@cua.dk>, 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.

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 <boruch_baum@gmx.com>
>>
>> File `cua-rect.el' list its author as Kim F. Storm <storm@cua.dk>, 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.

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

[Eli Zaretskii]

> Cc: 30085@debbugs.gnu.org
> From: Kim Storm <storm@cua.dk>
> 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.

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

[Boruch Baum]

I realize that some elisp code that I wrote for another purpose might be
useful for this mode.

  https://github.com/Boruch-Baum/swiper

One of the elements of `cua-rectangle-mark-mode' is a one-line cheat-sheet
style message of default keybindings of basic features, itself by
default bound to `C-?'.

In my referenced link above, I provide for `swiper' two features:

1) Cheat-sheet style messages that appear above the minibufer.

1.1) Keybinding for the messages (`M'?' by default) turns on the
     display, scrolls to the next message, and turns off the display.

1.2) The default message(s) may be supplemented or replaced by messages
     set by the user.

1.3) The message format includes an easy method to ensure that changing
     a keybinding does not require going back and editing the message.

2) Visual feedback of the current state of the mode. In the case of
   swiper, this is a single-line indication of case-fold status, regex
   method, currently selected action, and auto status. This feedback
   line appears just above the minibuffer.

The elisp code should be usable for other "complicated" emacs commands
without much of any modification. In the case of `swiper', it was
necessary to make a change to function `ivy-read' because of its
recursive nature and its use of unwind.

In the case of `swiper', a pull request has been made to the developer,
and is waiting for feedback.

An example of another candidate for this proposed feature would be
`isearch-forward'.

I would like to eventually offer it in generic form to emacs, but as for
now it hasn't even gotten approved by `swiper'.

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

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

[Boruch Baum]

[-- Attachment #1: Type: text/plain, Size: 2357 bytes --]

I had some time to look at the pacakge, and produced some notes and a
patch file, before realizing that it would be a good idea to consult
with you both before continuing and possibly wasting a lot of my
volunteer time-budget.

@Eli: In many places in the code, there exist in-line documentation that
would be appropriate as a doc-string; however, those cases are mostly
internal functions of the form `cua--foo', so the question arose for me:
is there emacs policy NOT to produce doc-strings for such functions.
Personally, it's more convenient to my work-flow to be able to use ivy
to get a pop-up docstring for thing-at-point than to open either open a
buffer (only to have to immediately kill it) or ping-pong among places
in a single buffer. So my vote and inclination is make the doc-strings,
but policy is policy.

@Kim & @ELi: My initial notes and patch file are attached, for feedback
if I got anything wrong, and for approval of the proposed changes:

1. The docstring issue, until I realized I should ask.

2. @Kim: At the end of the first diff block, I noted an issue about the
  `cua--last-killed-rectangle' data structure. Could you set me right
   about it?

3. I noticed that `M-m' was bound to `cua-copy-rectangle-as-text'
   instead of `back-to-indentation', so I took the liberty of writing a
   function `cua-resize-rectangle-back-to-indentation' and binding it to
   `M-m', which is what most users would expect. If this approved, to
   what should be bound `cua-copy-rectangle-as-text'

4. Function `cua-resize-rectangle-bot' had a bug in that it always
   placed point at the actual (point-max) even though the rectangle
   corner would not be there. This would occur when (point-max) was at a
   column number smaller than the left edge of the rectangle. The patch
   file includes the fix.

5. Two commonly used navigation functions, normally bound to `C-a' and
   `C-e' were not remapped. (DONE)

6. The help message is remapped from `C-?' to `M-?' for the sanity of
   people like me who use emacs-nox and can only perform a `C-?' by
   typing `C-x @ c ?'.

7. The current keybindings are made using an old method of keystroke
   definition that I find a bit scary. Is it OK / desirable to change
   the method uniformly to use `kbd'?

First slow steps.

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

[-- Attachment #2: cua-rect.patch --]
[-- Type: text/x-diff, Size: 7854 bytes --]

--- -	2018-03-21 08:18:33.833883945 -0400
+++ /home/optimum/cua-rect.el	2018-03-21 07:33:31.822488232 -0400
@@ -37,26 +37,58 @@
 
 (require 'rect)
 
-;; If non-nil, restrict current region to this rectangle.
-;; Value is a vector [top bot left right corner ins virt select].
-;; CORNER specifies currently active corner 0=t/l 1=t/r 2=b/l 3=b/r.
-;; INS specifies whether to insert on left(nil) or right(t) side.
-;; If VIRT is non-nil, virtual straight edges are enabled.
-;; If SELECT is a regexp, only lines starting with that regexp are affected.")
-(defvar cua--rectangle nil)
-(make-variable-buffer-local 'cua--rectangle)
+(defvar cua--rectangle nil
+  "Current cua-rectangle definition.
+
+A cua-rectangle definition is a vector used for all actions in
+`cua-rectangle-mark-mode', of the form:
+
+  [top bot left right corner ins virt select]
+
+TOP is the upper-left corner point.
+
+BOTTOM is the point at the end of line after the the lower-right
+corner point.
+
+LEFT and RIGHT are column numbers.
 
-;; Most recent rectangle geometry.  Note: car is buffer.
-(defvar cua--last-rectangle nil)
+CORNER specifies currently active corner 0=t/l 1=t/r 2=b/l 3=b/r.
 
-;; Rectangle restored by undo.
-(defvar cua--restored-rectangle nil)
+INS specifies whether to insert on left(nil) or right(t) side.
 
-;; Last rectangle copied/killed; nil if last kill was not a rectangle.
-(defvar cua--last-killed-rectangle nil)
+If VIRT is non-nil, virtual straight edges are enabled.
 
-;; List of overlays used to display current rectangle.
-(defvar cua--rectangle-overlays nil)
+If SELECT is a regexp, only lines starting with that regexp are affected.")
+(make-variable-buffer-local 'cua--rectangle)
+
+(defvar cua--last-rectangle nil
+  "Most recent rectangle geometry.
+A CONS cell, the car of which is the rectangle's buffer, and the
+cdr of which is a cua-rectangle definition. See
+`cua--rectangle'.")
+
+
+(defvar cua--restored-rectangle nil
+  "Rectangle restored by undo.")
+
+
+(defvar cua--last-killed-rectangle nil
+  "Last rectangle copied/killed; nil if last kill was not a rectangle.")
+;; NOT TRUE:
+;; + It seems to be the two most recent killed rectangles, and is not
+;;   reset upon either a `kill-region' or `kill-line'
+;; + In the following example, the rectangle full of question marks
+;;   was killed prior to the rectangle with the string "active".
+;;      (#("???e\n??? \n???i\n???," 0 19
+;;         (yank-handler
+;;          (rectangle--insert-for-yank
+;;           ("???e" "??? " "???i" "???,")
+;;           t)))
+;;       "active " "sert on" " straig" " lines ")
+
+
+(defvar cua--rectangle-overlays nil
+  "List of overlays used to display current rectangle.")
 (make-variable-buffer-local 'cua--rectangle-overlays)
 (put 'cua--rectangle-overlays 'permanent-local t)
 
@@ -393,10 +425,23 @@
         (cua--rectangle-corner -1))
     (cua--rectangle-resized)))
 
+(defun cua-resize-rectangle-back-to-indentation ()
+  "Resize rectangle to first non-whitespace character on the left."
+  (interactive)
+  (unless (bolp)
+    (back-to-indentation)
+    (cua--rectangle-left (current-column))
+    (if (cua--rectangle-right-side)
+        (cua--rectangle-corner -1))
+    (cua--rectangle-resized)))
+
 (defun cua-resize-rectangle-bot ()
   "Resize rectangle to bottom of buffer."
   (interactive)
   (goto-char (point-max))
+  (let ((col (cua--rectangle-column)))
+    (when (< (current-column) col)
+      (cua--forward-line -1)))
   (move-to-column (cua--rectangle-column))
   (cua--rectangle-bot t)
   (cua--rectangle-resized))
@@ -483,6 +528,8 @@
   (interactive "e")
   (setq this-command last-command))
 
+;;; Operations on current rectangle
+
 (defun cua--rectangle-move (dir)
   (let ((moved t)
         (top (cua--rectangle-top))
@@ -518,11 +565,8 @@
       (cua--rectangle-set-corners)
       (cua--keep-active))))
 
-
-;;; Operations on current rectangle
-
 (defun cua--tabify-start (start end)
-  ;; Return position where auto-tabify should start (or nil if not required).
+  "Return position where auto-tabify should start (or nil if not required)."
   (save-excursion
     (save-restriction
       (widen)
@@ -538,15 +582,15 @@
 	       start)))))
 
 (defun cua--rectangle-operation (keep-clear visible undo pad tabify &optional fct post-fct)
-  ;; Call FCT for each line of region with 4 parameters:
-  ;; Region start, end, left-col, right-col
-  ;; Point is at start when FCT is called
-  ;; Call fct with (s,e) = whole lines if VISIBLE non-nil.
-  ;; Only call fct for visible lines if VISIBLE==t.
-  ;; Set undo boundary if UNDO is non-nil.
-  ;; Rectangle is padded if PAD = t or numeric and (cua--rectangle-virtual-edges)
-  ;; Perform auto-tabify after operation if TABIFY is non-nil.
-  ;; Mark is kept if keep-clear is 'keep and cleared if keep-clear is 'clear.
+  "Call FCT for each line of region with 4 parameters:
+Region start, end, left-col, right-col
+Point is at start when FCT is called
+Call fct with (s,e) = whole lines if VISIBLE non-nil.
+Only call fct for visible lines if VISIBLE==t.
+Set undo boundary if UNDO is non-nil.
+Rectangle is padded if PAD = t or numeric and (cua--rectangle-virtual-edges)
+Perform auto-tabify after operation if TABIFY is non-nil.
+Mark is kept if keep-clear is 'keep and cleared if keep-clear is 'clear."
   (let* ((inhibit-field-text-motion t)
 	 (start (cua--rectangle-top))
          (end   (cua--rectangle-bot))
@@ -683,9 +727,9 @@
     (nreverse rect)))
 
 (defun cua--insert-rectangle (rect &optional below paste-column line-count)
-  ;; Insert rectangle as insert-rectangle, but don't set mark and exit with
-  ;; point at either next to top right or below bottom left corner
-  ;; Notice: In overwrite mode, the rectangle is inserted as separate text lines.
+  "Insert rectangle as insert-rectangle, but don't set mark and exit with
+point at either next to top right or below bottom left corner
+Notice: In overwrite mode, the rectangle is inserted as separate text lines."
   (if (eq below 'auto)
       (setq below (and (bolp)
                        (or (eolp) (eobp) (= (1+ (point)) (point-max))))))
@@ -1468,6 +1512,8 @@
   (define-key cua--rectangle-keymap [remap previous-line]       'cua-resize-rectangle-up)
   (define-key cua--rectangle-keymap [remap end-of-line]         'cua-resize-rectangle-eol)
   (define-key cua--rectangle-keymap [remap beginning-of-line]   'cua-resize-rectangle-bol)
+  (define-key cua--rectangle-keymap [remap move-end-of-line]       'cua-resize-rectangle-eol)
+  (define-key cua--rectangle-keymap [remap move-beginning-of-line] 'cua-resize-rectangle-bol)
   (define-key cua--rectangle-keymap [remap end-of-buffer]       'cua-resize-rectangle-bot)
   (define-key cua--rectangle-keymap [remap beginning-of-buffer] 'cua-resize-rectangle-top)
   (define-key cua--rectangle-keymap [remap scroll-down]         'cua-resize-rectangle-page-up)
@@ -1487,7 +1533,7 @@
   (define-key cua--rectangle-keymap "\r"     'cua-rotate-rectangle)
   (define-key cua--rectangle-keymap "\t"     'cua-indent-rectangle)
 
-  (define-key cua--rectangle-keymap [(control ??)] 'cua-help-for-rectangle)
+  (define-key cua--rectangle-keymap (kbd "M-?") 'cua-help-for-rectangle)
 
   (define-key cua--rectangle-keymap [mouse-1]	   'cua-mouse-set-rectangle-mark)
   (define-key cua--rectangle-keymap [down-mouse-1] 'cua--mouse-ignore)
@@ -1512,6 +1558,9 @@
   (cua--rect-M/H-key ?k	'cua-cut-rectangle-as-text)
   (cua--rect-M/H-key ?l	'cua-downcase-rectangle)
   (cua--rect-M/H-key ?m	'cua-copy-rectangle-as-text)
+; (cua--rect-M/H-key ?m	'cua-copy-rectangle-as-text) ;; TBD
+  (define-key cua--rectangle-keymap [remap back-to-indentation] 'cua-resize-rectangle-back-to-indentation)
+
   (cua--rect-M/H-key ?n	'cua-sequence-rectangle)
   (cua--rect-M/H-key ?o	'cua-open-rectangle)
   (cua--rect-M/H-key ?p	'cua-toggle-rectangle-virtual-edges)

[-- Attachment #3: cua-rect-notes.txt --]
[-- Type: text/plain, Size: 1925 bytes --]

cua-rect-notes.txt

1. Enter the mode BEFORE selecting the rectangle.

2. C-g exits the mode at any time.

3. M-x cua-rectangle-mark-mode

4. Use arrow keys to expand or contract the rectangle dimensions. Or
   use C-f, C-b, C-n, C-p, for cua-resize-rectangle-right,
   cua-resize-rectangle-left, cua-resize-rectangle-up,
   cua-resize-rectangle-down.

   + cua-resize-rectangle-eol - consider mapping this to C-e [DONE]
   + cua-resize-rectangle-bol - consider mapping this to C-a [DONE]

   + cua-resize-rectangle-bot - already mapped to M->
   + cua-resize-rectangle-top - already mapped to M-<
     + These two functions behaved unexpectedly. They extend the
       rectangle only vertically, not horizontally, so maybe they
       should be renamed or have their docstring edied to indicate
       something like "first/last line".

   + no issues with these; just noting their presence:
     + cua-resize-rectangle-page-up    M-v
     + cua-resize-rectangle-page-down  C-v

5. Mouse support - not evaluated.

6. Other navigation keys seem to be ignored for the purpose of
   selecting the cua-rectangle, even though they will move POINT. For
   example: C-a, C-e was shown to move point, but upon the next
   cua-rectangle naviigatiaa?on keystroke, POINT returned to its prior
   corner position.

7. Use the ENTER key, as needed, to toggle POINT amongst the
   rectangle's current corners in numeric POINT order (ie. for LTR
   languages, upper-left, upper-right, lower-left, lower-right).

8. Continue using the arrow keys, as needed, to expand or contract the
   rectangle dimensions.

9. One can recall the most recently selected rectangle, but only by
   returning POINT to its last selected corner, and then re-entering
   the mode.

10. cua-help-for-rectangle is currently bound to C-?, which is a pain
    for emacs-nox users. Remapped to M-?.

11. This mode does not seem to work for rtl (tested UTF-8 Hebrew)

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 2363 bytes --]

Boruch Baum <boruch_baum@gmx.com> writes:

> 1. The docstring issue, until I realized I should ask.

Thanks, I've pushed that part to master in your name with some
touch-ups.  I also added a ChangeLog entry.  See commit cfc70e51c2 on
the master branch.

> 2. @Kim: At the end of the first diff block, I noted an issue about the
>   `cua--last-killed-rectangle' data structure. Could you set me right
>    about it?

I left this as a FIXME comment, since it doesn't seem like anyone knows
the answer.  Hopefully someone so inclined will take a closer look at
some point.

> 3. I noticed that `M-m' was bound to `cua-copy-rectangle-as-text'
>    instead of `back-to-indentation', so I took the liberty of writing a
>    function `cua-resize-rectangle-back-to-indentation' and binding it to
>    `M-m', which is what most users would expect. If this approved, to
>    what should be bound `cua-copy-rectangle-as-text'
>
> 4. Function `cua-resize-rectangle-bot' had a bug in that it always
>    placed point at the actual (point-max) even though the rectangle
>    corner would not be there. This would occur when (point-max) was at a
>    column number smaller than the left edge of the rectangle. The patch
>    file includes the fix.
>
> 5. Two commonly used navigation functions, normally bound to `C-a' and
>    `C-e' were not remapped. (DONE)

Could you please provide instructions for how to test the above parts?
I don't use this mode and it's not clear to me what to do.  Also, could
you perhaps split the patch up and make it clear which parts of your
code belong to which of the above points?

Ideally, if possible, you would also add ChangeLog entries as per
etc/CONTRIBUTE.

> 6. The help message is remapped from `C-?' to `M-?' for the sanity of
>    people like me who use emacs-nox and can only perform a `C-?' by
>    typing `C-x @ c ?'.

I don't understand which part of your patch this refers to, or how to
test it.  Could you please clarify?

> 7. The current keybindings are made using an old method of keystroke
>    definition that I find a bit scary. Is it OK / desirable to change
>    the method uniformly to use `kbd'?

I have no strong opinion on this, but it seems relatively minor.  Perhaps
it's not worth the code churn.

> First slow steps.

I've attached a diff with the parts of your patch that I didn't yet push
to master.

Thanks.

[-- Attachment #2: bug30085-left-out.diff --]
[-- Type: text/x-diff, Size: 2760 bytes --]

diff --git a/lisp/emulation/cua-rect.el b/lisp/emulation/cua-rect.el
index 7ca9dc1af1..52cdcd9767 100644
--- a/lisp/emulation/cua-rect.el
+++ b/lisp/emulation/cua-rect.el
@@ -423,10 +423,23 @@ cua-resize-rectangle-bol
         (cua--rectangle-corner -1))
     (cua--rectangle-resized)))
 
+(defun cua-resize-rectangle-back-to-indentation ()
+  "Resize rectangle to first non-whitespace character on the left."
+  (interactive)
+  (unless (bolp)
+    (back-to-indentation)
+    (cua--rectangle-left (current-column))
+    (if (cua--rectangle-right-side)
+        (cua--rectangle-corner -1))
+    (cua--rectangle-resized)))
+
 (defun cua-resize-rectangle-bot ()
   "Resize rectangle to bottom of buffer."
   (interactive)
   (goto-char (point-max))
+  (let ((col (cua--rectangle-column)))
+    (when (< (current-column) col)
+      (cua--forward-line -1)))
   (move-to-column (cua--rectangle-column))
   (cua--rectangle-bot t)
   (cua--rectangle-resized))
@@ -1503,6 +1516,8 @@ cua--init-rectangles
   (define-key cua--rectangle-keymap [remap previous-line]       'cua-resize-rectangle-up)
   (define-key cua--rectangle-keymap [remap end-of-line]         'cua-resize-rectangle-eol)
   (define-key cua--rectangle-keymap [remap beginning-of-line]   'cua-resize-rectangle-bol)
+  (define-key cua--rectangle-keymap [remap move-end-of-line]       'cua-resize-rectangle-eol)
+  (define-key cua--rectangle-keymap [remap move-beginning-of-line] 'cua-resize-rectangle-bol)
   (define-key cua--rectangle-keymap [remap end-of-buffer]       'cua-resize-rectangle-bot)
   (define-key cua--rectangle-keymap [remap beginning-of-buffer] 'cua-resize-rectangle-top)
   (define-key cua--rectangle-keymap [remap scroll-down]         'cua-resize-rectangle-page-up)
@@ -1522,7 +1537,7 @@ cua--init-rectangles
   (define-key cua--rectangle-keymap "\r"     'cua-rotate-rectangle)
   (define-key cua--rectangle-keymap "\t"     'cua-indent-rectangle)
 
-  (define-key cua--rectangle-keymap [(control ??)] 'cua-help-for-rectangle)
+  (define-key cua--rectangle-keymap (kbd "M-?") 'cua-help-for-rectangle)
 
   (define-key cua--rectangle-keymap [mouse-1]	   'cua-mouse-set-rectangle-mark)
   (define-key cua--rectangle-keymap [down-mouse-1] 'cua--mouse-ignore)
@@ -1547,6 +1562,9 @@ cua--init-rectangles
   (cua--rect-M/H-key ?k	'cua-cut-rectangle-as-text)
   (cua--rect-M/H-key ?l	'cua-downcase-rectangle)
   (cua--rect-M/H-key ?m	'cua-copy-rectangle-as-text)
+; (cua--rect-M/H-key ?m	'cua-copy-rectangle-as-text) ;; TBD
+  (define-key cua--rectangle-keymap [remap back-to-indentation] 'cua-resize-rectangle-back-to-indentation)
+
   (cua--rect-M/H-key ?n	'cua-sequence-rectangle)
   (cua--rect-M/H-key ?o	'cua-open-rectangle)
   (cua--rect-M/H-key ?p	'cua-toggle-rectangle-virtual-edges)

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

[Boruch Baum]

Wow. This is what? Two years old? My vague memory was that this mode
seemed very feature-rich and desirable but slightly overlapping the more
common rectangle editing functions. When the thread went dead due to
lack of response, I stopped investigating and using it.

The desirable and unique feature that most stands out in my memory was
the mode's ability toggle POINT amongst the four corners of a selected
rectangle in order to resize it in any possible direction.

I remember the mode had other cool features, but don't remember what
they were. One of the deficiencies that I had wanted to address was the
mode's lack of documentation, but with the discouraging (lack of)
feedback, I just moved on.

Following is some feedback:

On 2020-10-26 18:50, Stefan Kangas wrote:
> Boruch Baum <boruch_baum@gmx.com> writes:
>
> > 3. I noticed that `M-m' was bound to `cua-copy-rectangle-as-text'
> >    instead of `back-to-indentation', so I took the liberty of writing a
> >    function `cua-resize-rectangle-back-to-indentation' and binding it to
> >    `M-m', which is what most users would expect. If this approved, to
> >    what should be bound `cua-copy-rectangle-as-text'
> >
> > 4. Function `cua-resize-rectangle-bot' had a bug in that it always
> >    placed point at the actual (point-max) even though the rectangle
> >    corner would not be there. This would occur when (point-max) was at a
> >    column number smaller than the left edge of the rectangle. The patch
> >    file includes the fix.
> >
> > 5. Two commonly used navigation functions, normally bound to `C-a' and
> >    `C-e' were not remapped. (DONE)
>
> Could you please provide instructions for how to test the above parts?
> I don't use this mode and it's not clear to me what to do.

I don't remember how to use the mode and its features (as I mentioned
above, it's been two years of non-response), but I see that the
notes.txt file that I included along with the patch that there are some
tips.

I *DO* remember that the remapped functions were to apply operations on
the selected rectangle instead of upon the buffer. What I mean is that
C-a would go the beginning of the line with the selected rectangle
instead of the buffer's beginning of line. And likewise for C-e, M-m.

You would need anyway to learn the basics of using the mode before
patching it. Once you've figured that out, try C-a, C-e, M-m before and
after the patch.

Again, some tips are in the notes.txt file accompanying the patch.

>  Also, could you perhaps split the patch up and make it clear which
> parts of your code belong to which of the above points?

Nope. At least not anytime reasonably soon. I have a full plate of other
FOSS stuff in my inbox just now and other life 'stuff'.

> Ideally, if possible, you would also add ChangeLog entries as per
> etc/CONTRIBUTE.
>
> > 6. The help message is remapped from `C-?' to `M-?' for the sanity of
> >    people like me who use emacs-nox and can only perform a `C-?' by
> >    typing `C-x @ c ?'.
>
> I don't understand which part of your patch this refers to, or how to
> test it.  Could you please clarify?

That's easy. It's a single line in the patch...

--8<--cut here-(start)------------------------------------------- >8
+  (define-key cua--rectangle-keymap (kbd "M-?") 'cua-help-for-rectangle)
--8<--cut here-(end)--------------------------------------------- >8

> > 7. The current keybindings are made using an old method of keystroke
> >    definition that I find a bit scary. Is it OK / desirable to change
> >    the method uniformly to use `kbd'?
>
> I have no strong opinion on this, but it seems relatively minor.  Perhaps
> it's not worth the code churn.

> > First slow steps.
>
> I've attached a diff with the parts of your patch that I didn't yet push
> to master.
>
> Thanks.

Thank you.

Word of caution: In the bigger picture, there ought to be a consensus on
whether to have two parallel packages that perform basically the same
functions in two different ways with two different code-bases. IMO, only
one should exist in emacs-core, and if that package can't incorporate
the unique features of the other by merging code, the other package
should be spun-off to ELPA/MELPA with a note that it has become
abandon-ware but retains value. In that spirit, I remember that
cua-rectangle mode was clearly *better*, but the development team might
shrink from foisting something different on users. In any case, without
clear documentation on how to even use the mode, I don't see a chance
for the development team to adopt it that way.

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

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

[Boruch Baum]

This issue has foundered due to our lack of expertise and detailed
knowledge of the mode. Here's a link to someone promoting the mode,
along with two videos.

https://karthinks.com/software/more-batteries-included-with-emacs/#easier-rectangle-editing--m-x-cua-selection-mode


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

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 <boruch_baum@gmx.com>
>>
>> File `cua-rect.el' list its author as Kim F. Storm <storm@cua.dk>, 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.

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

[Stefan Kangas]

Boruch Baum <boruch_baum@gmx.com> writes:

> I had some time to look at the pacakge, and produced some notes and a
> patch file, before realizing that it would be a good idea to consult
> with you both before continuing and possibly wasting a lot of my
> volunteer time-budget.

That was in March 2018, but it seems like you unfortunately never got a
reply here.  Are you still working on this?  Could you send the patch
you wrote?

> @Eli: In many places in the code, there exist in-line documentation that
> would be appropriate as a doc-string; however, those cases are mostly
> internal functions of the form `cua--foo', so the question arose for me:
> is there emacs policy NOT to produce doc-strings for such functions.

It's better if they have a doc string even if they are internal
functions.  It could make sense to rework comments into doc strings,
but I don't know the specifics in this case.

> @Kim & @ELi: My initial notes and patch file are attached, for feedback
> if I got anything wrong, and for approval of the proposed changes:
>
> 1. The docstring issue, until I realized I should ask.
>
> 2. @Kim: At the end of the first diff block, I noted an issue about the
>   `cua--last-killed-rectangle' data structure. Could you set me right
>    about it?
>
> 3. I noticed that `M-m' was bound to `cua-copy-rectangle-as-text'
>    instead of `back-to-indentation', so I took the liberty of writing a
>    function `cua-resize-rectangle-back-to-indentation' and binding it to
>    `M-m', which is what most users would expect. If this approved, to
>    what should be bound `cua-copy-rectangle-as-text'
>
> 4. Function `cua-resize-rectangle-bot' had a bug in that it always
>    placed point at the actual (point-max) even though the rectangle
>    corner would not be there. This would occur when (point-max) was at a
>    column number smaller than the left edge of the rectangle. The patch
>    file includes the fix.
>
> 5. Two commonly used navigation functions, normally bound to `C-a' and
>    `C-e' were not remapped. (DONE)
>
> 6. The help message is remapped from `C-?' to `M-?' for the sanity of
>    people like me who use emacs-nox and can only perform a `C-?' by
>    typing `C-x @ c ?'.
>
> 7. The current keybindings are made using an old method of keystroke
>    definition that I find a bit scary. Is it OK / desirable to change
>    the method uniformly to use `kbd'?
>
> First slow steps.

Best regards,
Stefan Kangas

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 19 Oct 2019 03:21:52 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, 30085@debbugs.gnu.org, Kim Storm <storm@cua.dk>
> 
> Boruch Baum <boruch_baum@gmx.com> writes:
> 
> > I had some time to look at the pacakge, and produced some notes and a
> > patch file, before realizing that it would be a good idea to consult
> > with you both before continuing and possibly wasting a lot of my
> > volunteer time-budget.
> 
> That was in March 2018, but it seems like you unfortunately never got a
> reply here.  Are you still working on this?  Could you send the patch
> you wrote?

If Kim doesn't respond, as he didn't back then, I suggest you use your
best judgment to retain whatever seems useful from this patch.

Internal functions indeed don't need to be documented, but if the doc
string makes a significant difference in how easy it is to understand
what the function does, including a doc string can only help future
maintenance.

I know very little about cua-rectangle-mode, mainly around the tricks
it plays with the display code (and the special support these tricks
have in the display engine), so I cannot answer the questions that
Boruch asked.

Thanks.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> If Kim doesn't respond, as he didn't back then, I suggest you use your
> best judgment to retain whatever seems useful from this patch.
>
> Internal functions indeed don't need to be documented, but if the doc
> string makes a significant difference in how easy it is to understand
> what the function does, including a doc string can only help future
> maintenance.

So I finally had a look and pushed the relevant documentation changes.
In effect large parts of the patch was converting existing comments into
docstrings.  They aren't the most beautiful in all cases, but definitely
better than nothing.

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

[Boruch Baum]

Hi Stefan. Thanks for re-visiting this.

On 2019-10-19 03:21, Stefan Kangas wrote:
> Boruch Baum <boruch_baum@gmx.com> writes:
>
> > I had some time to look at the pacakge, and produced some notes and a
> > patch file, before realizing that it would be a good idea to consult
> > with you both before continuing and possibly wasting a lot of my
> > volunteer time-budget.
>
> That was in March 2018, but it seems like you unfortunately never got a
> reply here.

Bummer that, but people mostly contribute on a volunteer-basis and have
lives outside of emacs, so I didn't take it personally.

>  Are you still working on this?

No. I was discouraged from continuing by the silence and lack of
response to my submitted patch and notes.

>  Could you send the patch you wrote?

It's been hiding on the bug report thread since 21 Mar 2018:

  https://debbugs.gnu.org/cgi/bugreport.cgi?filename=cua-rect.patch;msg=23;bug=30085;att=1
  https://debbugs.gnu.org/cgi/bugreport.cgi?msg=23;filename=cua-rect-notes.txt;att=2;bug=30085

There may be other useful data in the thread; I don't remember. I've
just returned from holiday and had a backlog of work before I left, so I
can't commit to continuing this anytime soon, but I remember that the
patch did fix some issues, so if you want to carry the ball, then the
patch and accompanying notes could be useful.


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

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

[Stefan Kangas]

Hi Boruch,

Boruch Baum <boruch_baum@gmx.com> writes:

> >  Are you still working on this?
>
> No. I was discouraged from continuing by the silence and lack of
> response to my submitted patch and notes.

FWIW, I think these looks like useful changes.  Thanks for working on it.

> >  Could you send the patch you wrote?
>
> It's been hiding on the bug report thread since 21 Mar 2018:

Oh, I must've missed it.  Thanks.

> There may be other useful data in the thread; I don't remember. I've
> just returned from holiday and had a backlog of work before I left, so I
> can't commit to continuing this anytime soon, but I remember that the
> patch did fix some issues, so if you want to carry the ball, then the
> patch and accompanying notes could be useful.

I'm not sure I can be of much help, since I've never used cua-mode and
know nothing about it.

I'm mostly here to nudge along the work of improving the
documentation.  I think this is important work, if somewhat thankless.
I therefore suggest that you revisit this when you find some time, and
in the meanwhile we can see if someone more knowledgeable than me
picks up the ball.

Thanks again for the update.

Best regards,
Stefan Kangas

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> I'm mostly here to nudge along the work of improving the
> documentation.  I think this is important work, if somewhat thankless.

There may not be many thanks, but it's really appreciated.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 28 Oct 2019 11:41:27 +0100
> Cc: 30085@debbugs.gnu.org, Boruch Baum <boruch_baum@gmx.com>,
>  Kim Storm <storm@cua.dk>
> 
> Stefan Kangas <stefan@marxist.se> writes:
> 
> > I'm mostly here to nudge along the work of improving the
> > documentation.  I think this is important work, if somewhat thankless.
> 
> There may not be many thanks, but it's really appreciated.  :-)

Certainly.

Thanks!