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

From: Eli Zaretskii <[email-masked]>
Date: Wed, 30 Aug 2023 14:37:48 +0300

> Date: Wed, 30 Aug 2023 01:17:51 +0000
> From:  Okamsn via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> The attached patch adds the command `edmacro-set-macro-to-region-lines` 
> for quickly reducing the presented keys to those in the region, and adds 
> the user option `edmacro-reverse-key-order` for showing the most recent 
> keys first.

Thanks.

> These two changes are useful for `kmacro-edit-lossage`.  My use case is 
> that I would like to quickly create a keyboard macro from some of my 
> recent key presses, but Edmacro is slow to use when the lossage size is 
> large.  When it is large, I must jump to the bottom of the buffer, then 
> cut the desired lines, then jump back up, then delete the remaining 
> lines, then paste the cut lines, then press `C-c C-c`. If I use 
> `delete-selection-mode`, I can combine two of the steps.  With this new 
> change from the patch, I can move down a few lines, select a few lines, 
> then press `C-c C-r`, then press `C-c C-c`.

If these commands are indeed important conveniences, they should be in
the manual, I think.

> +(defcustom edmacro-reverse-key-order nil
> +  "Non-nil if `edit-kbd-macro' should show the most recent keys first.
> +
> +This is useful when dealing with long lists of key sequences, such as
> +from `kmacro-edit-lossage'."
> +  :type 'boolean
> +  :group 'kmacro)

Defcustoms should have the :version tag.

> +(defun edmacro-set-macro-to-region-lines (beg end)
> +  "Set the Macro text to the lines of the region.

We prefer to have the mandatory arguments mentioned in the first line
of a function's doc string.

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