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

[Eli Zaretskii]

> Date: Sat, 09 Sep 2023 00:45:05 +0000
> From: Okamsn <okamsn@protonmail.com>
> Cc: 65605@debbugs.gnu.org, stefankangas@gmail.com
> 
> 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.

Thanks, installed on the master branch, and closing the bug.