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

classic Classic list List threaded Threaded
7 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.



Reply | Threaded
Open this post in threaded view
|

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



Reply | Threaded
Open this post in threaded view
|

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

Boruch Baum
In reply to this post by Eli Zaretskii
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

cua-rect.patch (7K) Download Attachment
cua-rect-notes.txt (1K) Download Attachment