bug#73308: [PATCH] Add file-to-register and buffer-to-register.

[Eli Zaretskii <eliz@gnu.org>]

> List-Unsubscribe-Post: List-Unsubscribe=One-Click
> Date: Tue, 17 Sep 2024 00:32:40 +0100
> From:  Barra Ó Catháin via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> This patch adds two new functions and keybindings for them,
> file-to-register and buffer-to-register.
> 
> These functions make it simpler to put a file/buffer into a register,
> which I have personally found to be useful when working with projects
> where I don't wish to disturb the point or to pull up notes files.
> 
> (Previously submitted, but I was unfortunately unable to follow it up at
> the time due to life getting busy!)
> 
> Questions and comments appreciated, previously assigned copyright.

Thierry, any comments to these additions?

> * lisp/bindings.el (ctl-x-r-map):
> Add bindings to the register keymap for the two new
> functions. 'F' for file-to-register and 'B' for
> buffer-to-register.
> 
> * lisp/register.el (register-command-info): Registers the two
> new functions, file-to-register and buffer-to-register as
> commands.
> 
> (file-to-register):
> New function, stores a file into a register. Used interactively,
> prompts for REGISTER using `register-read-with-preview'. With a
> prefix-argument, prompts for FILE-NAME using `read-file-name',
> otherwise, uses the currently visited file or directory for
> FILE-NAME.
> 
> (buffer-to-register):
> New function, stores a buffer into a register. Used
> interactively, prompts for REGISTER using
> `register-read-with-preview'. With a prefix-argument, prompts
> for BUFFER-NAME using `read-buffer', otherwise, uses the current
> buffer.

This is not exactly the format of log entries which we prefer.  See
"git log" for examples and CONTRIBUTE for explanations.

> +@table @kbd
> +@item C-x r F @var{r}
> +@kindex C-x r F
> +@findex file-to-register
> +Store the currently visited file or directory into register @var{r} (@code{file-to-register}).
> +@item C-u C-x r F @var{r}
> +@kindex C-x r F
> +@findex file-to-register
> +Prompt for a file, and store into register @var{r} (@code{file-to-register}).

First, @*index index entries should appear _before_ the @item lines,
so that Info-index places you on the line created from @item, not
after it.

And second, the above defines two identical @kindex entries "C-x r F"
that both point to the same page, and that is not useful.  We should
keep only one of them.  The same about the 2 identical @findex
entries.  (Actually, you have 3 identical @kindex entries.)

More importantly, we usually index the detailed descriptions of the
commands in the body of the section, not the abstract at its
beginning.  E.g., look at how this is done in a node "Position
Registers".

> +  Similarly, if there are certain buffers you visit frequently, you can
> +put their names in registers. You can use the following command to put a
> +buffer into a register.     ^^

Our conventions are to leave two spaces between sentences, per US
English.

> -@smallexample
> -(set-register ?m '(buffer . "*Messages*"))
> -@end smallexample
> +@table @kbd
> +@item C-x r B @var{r}
> +@kindex C-x r B
> +@findex buffer-to-register
> +Store the current buffer into register @var{r} (@code{buffer-to-register}).
> +@item C-u C-x r B @var{r}
> +@kindex C-x r B
> +@findex buffer-to-register
> +Prompt for a buffer, and store into register @var{r} (@code{buffer-to-register}).
> +@end table

It is best to have at the beginning of a node a single @table with the
abstract of all the commands described by the node.  So please make
one @table out of these two.

> +(defun file-to-register (file-name register)
> +  "Inserts FILE-NAME in REGISTER.
> +To visit the file, use \\[jump-to-register].
> +
> +Interactively, prompts for REGISTER using `register-read-with-preview'.
> +With a prefix-argument, prompts for FILE-NAME using `read-file-name',
> +otherwise, uses the currently visited file or directory for FILE-NAME."

Our style in doc string is to use "Insert", "prompt", "use", etc., at
least in the first sentence of the doc string, which gives the summary
of what the function does.

> +(defun buffer-to-register (buffer register)
> +  "Inserts BUFFER in REGISTER.
> +To visit the buffer, use \\[jump-to-register].
> +
> +Interactively, prompts for REGISTER using `register-read-with-preview'.
> +With a prefix-argument, prompts for BUFFER-NAME using `read-buffer',
> +otherwise, uses the current buffer."

Likewise here.

Finally, this warrants a NEWS entry to announce the new commands.

Thanks.