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

[Eli Zaretskii]

> 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?

> +(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"?

> +(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.