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

[Thierry Volpiatto <thievol@posteo.net>]

[-- Attachment #1: Type: text/plain, Size: 5808 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

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

One comment about buffer-to-register:

More or less you can have the same with point-to-register, the advantage
is that when you kill the buffer, the register-alist entry is turned in
a file-query entry (when buffer is representing a file of course), for
example from register.el buffer:

C-x r <SPC> RET

register-alist entry:
(115 . #<marker at 27354 in register.el>)

Now kill the the buffer, the register-alist entry is turned in:
(115 file-query "/home/thierry/work/emacs/lisp/register.el" 27354)

This is why I guess such functions where never added to register.el.

OTOH they provide an alternative which is easier to find as most users
don't know about this feature (buffer => file-qurey).

BTW I suggest you use for buffer-to-register an entry something like
(buffer-name . marker), this way register-swap-out will be able
to transform it like point-to-register does. Need also to add a add-hook
call like point-to-register does.

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

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]