bug#65605: [PATCH] Command and option to make Edmacro better for long sequences

[Okamsn]

Eli Zaretskii wrote:
>> Date: Sun, 03 Sep 2023 16:05:03 +0000
>> From: Okamsn <okamsn@protonmail.com>
>> Cc: 65605@debbugs.gnu.org
>>
>>>> +If BEG is not at the beginning of a line, it is moved to the
>>>> +beginning of the line.  If END is at the beginning of a line,
>>>> +that line is excluded.  Otherwise, if END is not at the
>>>> +end of a line, it is moved to the end of the line."
>>>
>>> This describes the implementation, whereas this is a command, so the
>>> doc string should have users, not programmer's in mind.  Try to
>>> describe BEG and END in user-level terms, for example:
>>>
>>>     Macro text will start and the beginning of line containing buffer
>>>     position BEG.
>>>
>>> Also, the doc string should tell how BEG and END are determined in
>>> interactive invocations.
>>>
>>
>> I have changed it. How does it look now?
> 
> See some comments below.
> 
>> +@findex edmacro-insert-key
>> +@findex edmacro-set-macro-to-region-lines
>> +  The mode provides commands for more easily editing the formatted
> 
> You say "The mode", but it is not clear what is "the mode" to which
> you allude.
> 
>> +macro.  Use @kbd{C-c C-q} (@code{edmacro-insert-key}) to insert the
>> +next key sequence that you type into the buffer using the correct
>> +format, similar to @kbd{C-q} (@code{quoted-insert}).  Use @kbd{C-c
>> +C-r} (@code{edmacro-set-macro-to-region-lines}) to replace the macro's
>> +formatted text with the lines overlapping the region of text between
>> +point and mark.
> 
> Here, "the lines overlapping the region of text between point and
> mark" is IMO not clear enough.  I think you mean to say "text in the
> region", and the "overlapping" part is just to allude to the fact that
> the region might begin and/or end in the middle of a line?  If so, I
> would suggest
> 
>    Use @kbd{C-c C-r} (@code{edmacro-set-macro-to-region-lines}) to
>    replace the macro's formatted text with the text in the region.  If
>    the region begins not and beginning of a line or ends not at end of
>    line, it is extended to include complete lines.
> 
> Also, is the "formatted" in "macro's formatted text" really needed?
> What does "formatted" signify?

I wasn't sure what to call the lines of formatted text showing the 
macro's contents. I have changed it to just "text".

>> +(defcustom edmacro-reverse-key-order nil
>> +  "Non-nil if `edit-kbd-macro' should show the most recent line of keys 
>> first.
>                                                                        ^^^^
> "Keys" or "key sequence"?

I have changed it to "key sequences".

>> +(defun edmacro-set-macro-to-region-lines (beg end)
>> +  "Set the macro text to the lines overlapping the buffer text from BEG to 
>> END.
> 
> I would suggest
> 
>    Set macro text to lines of text in current buffer between BEG and END.
> 
>> +When called interactively, this command uses the beginning and
>> +end of the selected region as the buffer positions.
> 
>    Interactively, BEG and END are the beginning and end of the region.
> 

I have changed it to:

"Set the macro text to lines of text in the buffer between BEG and END.

Interactively, BEG and END are the beginning and end of the
region.  If the region does not begin at the start of a line or
if it does not end at the end of a line, the region is extended
to include complete lines.  If the region ends at the beginning
of a line, that final line is excluded."

I have also added the new command and user option to "NEWS" as requested 
by Stefan Kangas, and have described the new user option in the manual.

I have also changed the name of the user option to 
"edmacro-reverse-macro-lines", which is a bit clearer.

v4-0001-Make-using-Edmacro-better-for-long-sequences-of-k.patch
Description: Text Data