GNU bug report logs - #73308
[PATCH] Add file-to-register and buffer-to-register.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 73308 in the body.
You can then email your comments to 73308 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Barra Ó Catháin <barra <at> ocathain.ie>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add file-to-register and buffer-to-register.
Date: Tue, 17 Sep 2024 00:32:40 +0100

[Message part 1 (text/plain, inline)]

Tags: patch

Tags: patch

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.

In GNU Emacs 29.4 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.43,
cairo version 1.18.0)
Windowing system distributor 'The X.Org Foundation', version 11.0.12101013
System Description: Arch Linux

Configured using:
 'configure --sysconfdir=/etc --prefix=/usr --libexecdir=/usr/lib
 --with-tree-sitter --localstatedir=/var --with-cairo
 --disable-build-details --with-harfbuzz --with-libsystemd
 --with-modules --with-x-toolkit=gtk3 'CFLAGS=-march=x86-64
 -mtune=generic -O2 -pipe -fno-plt -fexceptions -Wp,-D_FORTIFY_SOURCE=3
 -Wformat -Werror=format-security -fstack-clash-protection
 -fcf-protection -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -g
 -ffile-prefix-map=/build/emacs/src=/usr/src/debug/emacs -flto=auto'
 'LDFLAGS=-Wl,-O1 -Wl,--sort-common -Wl,--as-needed -Wl,-z,relro
 -Wl,-z,now -Wl,-z,pack-relative-relocs -flto=auto''

[0001-Add-file-to-register-and-buffer-to-register.patch (text/patch, attachment)]

Message #8 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Barra Ó Catháin <barra <at> ocathain.ie>, Thierry
 Volpiatto <thievol <at> posteo.net>
Cc: 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Tue, 17 Sep 2024 15:20:25 +0300

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

Message #11 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thievol <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Thierry Volpiatto <thievol <at> posteo.net>,
 Barra Ó Catháin <barra <at> ocathain.ie>, 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Tue, 17 Sep 2024 14:10:41 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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 <at> 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

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Thierry Volpiatto <thievol <at> posteo.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>,
 Barra Ó Catháin <barra <at> ocathain.ie>, 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Tue, 17 Sep 2024 21:18:49 +0200

Thierry Volpiatto <thievol <at> posteo.net> writes:

> 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

I'm worrying a bit: with this patch we would have 3 different types of
registers that would really be very similar.  The user would have to
think about which is appropriate when setting the register.  Or - if the
question doesn't matter - why have 3 different types?


Michael.

Message #17 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Barra Ó Catháin <barra <at> ocathain.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Wed, 18 Sep 2024 03:19:02 +0100

Thank you, Eli, will look at this either tommorrow or the day after and
clean up the patch.

For my own sake:
- Clean up the git log entries.
- Place index entries before the item, and fix the duplication for
kindex (I don't even honestly know how I managed to get it into that
state, I remember writing the two commands but clearly I'm
misremembering)
- Bring descriptions more in line with the style, see position registers
- Two spaces, US english
- One table, not two.
- Verb at start of doc string
- News entry.

Thanks for your time.
-----
Barra

Message #20 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Barra Ó Catháin <barra <at> ocathain.ie>
To: Thierry Volpiatto <thievol <at> posteo.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Wed, 18 Sep 2024 03:26:58 +0100

Thanks, Thierry. I'll look into how point-to-register does things and
see if I can improve things alongside. 

Thanks for your time!
-----
Barra

Thierry Volpiatto <thievol <at> posteo.net> writes:

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

Message #23 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Barra Ó Catháin <barra <at> ocathain.ie>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: Thierry Volpiatto <thievol <at> posteo.net>, Eli Zaretskii <eliz <at> gnu.org>,
 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Wed, 18 Sep 2024 03:51:47 +0100

Perhaps the easiest way to demonstrate the differences I saw in their
usage is to explain why I chose to wrote them and not use
point-to-register:

I use buffer-to-register when I'm working with lots of different buffers
but I don't wish to disturb the point when switching back to them. For
example, running long commands in a shell window or even just different
files that I'm bouncing between, rather than dancing with switching
buffers through one of the other means. 

I use file-to-register to pre-load notes files into registers on
startup. It visually makes more sense to read in an init-file. Frankly,
in interactive use I haven't found a real use for file-to-register, but
I also saw no reason not to bind it. I think the main benefit to this is
discoverability. 

Let me know if I can clarify anything for you further with this.
-----
Barra

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> Thierry Volpiatto <thievol <at> posteo.net> writes:
>
>> 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
>
> I'm worrying a bit: with this patch we would have 3 different types of
> registers that would really be very similar.  The user would have to
> think about which is appropriate when setting the register.  Or - if the
> question doesn't matter - why have 3 different types?
>
>
> Michael.

Message #26 received at 73308 <at> debbugs.gnu.org (full text, mbox):

From: Barra Ó Catháin <barra <at> ocathain.ie>
To: 73308 <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Tue, 24 Sep 2024 15:09:31 +0100

[Message part 1 (text/plain, inline)]

I've updated the patch to include the feedback given previously; as
always, further comments/feedback are appreciated!

-----
Barra

[0001-Add-file-buffer-to-register-Bug-73308.patch (text/x-patch, attachment)]

Message #33 received at 73308-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Barra Ó Catháin <barra <at> ocathain.ie>
Cc: 73308-done <at> debbugs.gnu.org
Subject: Re: bug#73308: [PATCH] Add file-to-register and buffer-to-register.
Date: Sat, 05 Oct 2024 13:08:13 +0300

> List-Unsubscribe-Post: List-Unsubscribe=One-Click
> Date: Tue, 24 Sep 2024 15:09:31 +0100
> From:  Barra Ó Catháin via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> I've updated the patch to include the feedback given previously; as
> always, further comments/feedback are appreciated!

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.