From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Boruch Baum Newsgroups: gmane.emacs.bugs Subject: bug#30085: 25.2: Documentation for cua-rectangle-mark-mode Date: Wed, 21 Mar 2018 08:48:36 -0400 Message-ID: <20180321124836.puwmknqvo6zketnk@E15-2016.optimum.net> References: <20180112071426.uq2x3nlcs6jo57hm@E15-2016.optimum.net> <83mv1j2zz4.fsf@gnu.org> <0e8d20ba-84c9-1509-0f52-b8b4b649e00a@cua.dk> <834lnq3o4i.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="3x6qca6d252gla5u" X-Trace: blaine.gmane.org 1521636634 29583 195.159.176.226 (21 Mar 2018 12:50:34 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 21 Mar 2018 12:50:34 +0000 (UTC) User-Agent: NeoMutt/20180223 Cc: 30085@debbugs.gnu.org, Kim Storm To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Mar 21 13:50:29 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eydCG-0007WZ-0N for geb-bug-gnu-emacs@m.gmane.org; Wed, 21 Mar 2018 13:50:28 +0100 Original-Received: from localhost ([::1]:54796 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eydEJ-0004NM-Al for geb-bug-gnu-emacs@m.gmane.org; Wed, 21 Mar 2018 08:52:35 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35884) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eydAw-0000Al-9J for bug-gnu-emacs@gnu.org; Wed, 21 Mar 2018 08:49:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eydAt-0001G5-2X for bug-gnu-emacs@gnu.org; Wed, 21 Mar 2018 08:49:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:37075) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eydAs-0001Fq-T4 for bug-gnu-emacs@gnu.org; Wed, 21 Mar 2018 08:49:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eydAs-0004mf-Fs for bug-gnu-emacs@gnu.org; Wed, 21 Mar 2018 08:49:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Boruch Baum Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 21 Mar 2018 12:49:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30085 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 30085-submit@debbugs.gnu.org id=B30085.152163653418376 (code B ref 30085); Wed, 21 Mar 2018 12:49:02 +0000 Original-Received: (at 30085) by debbugs.gnu.org; 21 Mar 2018 12:48:54 +0000 Original-Received: from localhost ([127.0.0.1]:44972 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eydAj-0004mJ-Dj for submit@debbugs.gnu.org; Wed, 21 Mar 2018 08:48:53 -0400 Original-Received: from mout.gmx.net ([212.227.15.15]:48979) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eydAe-0004m3-Pp for 30085@debbugs.gnu.org; Wed, 21 Mar 2018 08:48:49 -0400 Original-Received: from E15-2016.optimum.net ([108.6.168.221]) by mail.gmx.com (mrgmx003 [212.227.17.184]) with ESMTPSA (Nemesis) id 0MAyVY-1eqxed344q-009v9Q; Wed, 21 Mar 2018 13:48:40 +0100 Content-Disposition: inline In-Reply-To: <834lnq3o4i.fsf@gnu.org> X-Provags-ID: V03:K0:C7mYdjIk/jsbdsEW3lizxSrBSCgb7CSRj92rCEUTMvenODYN8/D zDPuO4HxUzvArPWrIG9YDf07o0eWZlJRd9s5YYsy1R/oqFTe0PKmNhlqUjo4+s89HccJhik 3+bIHM1SigFYis5b3ItRHibGlDp316fet+COFlSU2zzVQBqiN8uBlIp/KHWpCB5548Td64A uGFaTZMFTh1Mw2d55BSMA== X-UI-Out-Filterresults: notjunk:1;V01:K0:7KUypmO4nAM=:nq0MHD9q5RYFO0B1CNqja5 qtK00DYNfSHrUf1y0koDoxflCxgaCUrT1090kWf3ncgkvIk8kK6sO+m5CA3UdV7MtjecTwYbL tczHibAs1KWq0JFOW3A+qu6o5p3j3PvWWWnekcvHXRSSsGSgJMcJMclj/PWeTBzmaOXdUrTtQ j/D9Rfiqdygev1QkvXYLpjXpdXP9VrkZH2pk/RgQRoQi0mrZ+COWez3Qhi3jKXpYKu/9mPPu9 JYvEsNIYezJg0sKOBva5VGBiezLewkyGjMQQGnuaFmplAaKim+6LfD8o40UZDxo6np+0ueVuf rKwvOAjJJ8bAYA3e7dgUq//78XHh9nN0cwTW7vr4RMdbXRRkE3QMmWOpVPfiUdNX2V7Xvwfrp fjfOkf18B3BD45ewxG2+d/UtrgnmVk7vRUgK67xdL8ejM1kLJ9V4BNricYrMOM0JjATZmW1e6 1GU1Mw4N4VLzqFs4nPb5Tk0NfSOTeiDSNIK4dZXS7bf7C4/EMA22wMFwbBZ4U/eoGU4qlv1c4 KTeiZ63sDTMZ2XtMVBZe0rXB+BqcuXqgowckVTHVcsNajMi4OVwHQMcRSq8LFrOuMg16y0EPL 4jdjjJmNfFG51qyj/yw3jY4e8HvadDgydr5yzBe8uxlgvPc3i+StyAUxfF8zSvYD4oR5fS/CX w89snia3FRc4KD3lxDCLFuxbb4uu1IzQYLiAki6XWkxJWfFgod4YsByDVBFtmTqmhUTEw2AVu tS8FVJjeOWRKcX9yAqBq42qrmAi+65f6l9TcWTTYqsG5W/cIsw6qdsAALalEPy6MQpL64EBy X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:144488 Archived-At: --3x6qca6d252gla5u Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 --3x6qca6d252gla5u Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="cua-rect.patch" --- - 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) --3x6qca6d252gla5u Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="cua-rect-notes.txt" 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) --3x6qca6d252gla5u--