GNU bug report logs - #58071
28.2; [PATCH] jumprel: A tool to find/create related files

Previous Next

To reply to this bug, email your comments to 58071 AT debbugs.gnu.org.

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

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

From: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.2; [PATCH] jumprel: A tool to find/create related files
Date: Sun, 25 Sep 2022 13:20:28 +0200

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

Please find attached jumprel, a tool to find/create related files. This
tool has been described (and compared with `find-file.el' and
`find-sibling-file') in emacs-devel's thread "Comparison of tools to
search for related files".

You will find a few files attached to this email:

- jumprel.el: The core of the library. This is where you will find an
  introductory documentation.
- tests/jumprel-test.el: Corresponding tests.

- jumprel-recipe.el: Support for recipe-based jumpers. This makes it
  easy to define powerful jumpers.
- tests/jumprel-recipe-test.el: Corresponding tests.

- jumprel-regexp.el: A proof-of-concept way to define regexp-based
  jumpers. This files provides the same kind of support as
  `find-sibling-file' and `find-file.el'. This file is heavily based on
  previous work from Lars Ingebrigtsen <larsi <at> gnus.org> and others.

- 0001-.dir-locals.el-Configure-jumprel-jumpers.patch: A patch for
  Emacs' .dir-locals.el making use of jumprel for .el and .c/.h files.

Because there are already 2 mechanisms to find related files in Emacs
(see above-mentioned thread), I think we should only consider
integrating jumprel into Emacs core if the other 2 are somewhat
deprecated (find-sibling-file hasn't been part of any release yet).

Even if you don't want to include this package in Emacs core, I would
really welcome feedback.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[0001-.dir-locals.el-Configure-jumprel-jumpers.patch (text/x-patch, attachment)]

[jumprel.el (text/plain, attachment)]

[jumprel-recipe.el (text/plain, attachment)]

[jumprel-regexp.el (text/plain, attachment)]

[jumprel-recipe-test.el (text/plain, attachment)]

[jumprel-test.el (text/plain, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2;
 [PATCH] jumprel: A tool to find/create related files
Date: Mon, 26 Sep 2022 10:42:15 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Date: Sun, 25 Sep 2022 13:20:28 +0200
> 
> Please find attached jumprel, a tool to find/create related files. This
> tool has been described (and compared with `find-file.el' and
> `find-sibling-file') in emacs-devel's thread "Comparison of tools to
> search for related files".

Thanks.  A few high-level comments I have are:

 . "jumprel" is not the best name, IMO; something like "related-files"
   would be better
 . what you call "recipes", i.e. descriptors of how to generate the
   name of related files from a given file name, should be documented
   in a single doc string, and the other places that use recipes
   should reference the symbol whose doc string documents them
   (currently, it looks like the documentation is scattered all over
   the code and comments, and mainly as examples; there's no single
   exhaustive list with descriptions)
 . I find no documentation of how to describe alternatives -- several
   alternative file names produced from a single original file name
 . I wonder whether "recipes" like these are a convenient method of
   customizing this facility: do people really find it easy to write
   "ordered" property lists for this purpose?

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Mon, 26 Sep 2022 13:05:18 +0200

Damien Cassou <damien <at> cassou.me> writes:

> - jumprel.el: The core of the library. This is where you will find an
>   introductory documentation.

I think jumprel would probably be better suited as an ELPA package.
Like completion frameworks, there's no one size fits all in this area --
the DWIM for one person isn't the DWIM for another person.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Damien Cassou <damien <at> cassou.me>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2;
 [PATCH] jumprel: A tool to find/create related files
Date: Mon, 26 Sep 2022 09:37:40 -0400

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> I think jumprel would probably be better suited as an ELPA package.
> Like completion frameworks, there's no one size fits all in this area --
> the DWIM for one person isn't the DWIM for another person.

I'd think we want such basic functionality built-in and working OOTB.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: Damien Cassou <damien <at> cassou.me>, 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Tue, 27 Sep 2022 13:34:41 +0200

Stefan Kangas <stefankangas <at> gmail.com> writes:

>> I think jumprel would probably be better suited as an ELPA package.
>> Like completion frameworks, there's no one size fits all in this area --
>> the DWIM for one person isn't the DWIM for another person.
>
> I'd think we want such basic functionality built-in and working OOTB.

We already have this basic functionality built-in.  jumprel is a
different take on what find-file does, just like Helm is a different
take how completion should look.

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

From: Damien Cassou <damien <at> cassou.me>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Wed, 28 Sep 2022 21:26:51 +0200

Thank you very much Eli for your review. I appreciate the time you took
to have a look at my code. I imagine how busy you are and my package
isn't small.

Eli Zaretskii <eliz <at> gnu.org> writes:
> - "jumprel" is not the best name, IMO; something like "related-files"
> would be better

sure

> - what you call "recipes", i.e. descriptors of how to generate the
> name of related files from a given file name, should be documented in
> a single doc string, and the other places that use recipes should
> reference the symbol whose doc string documents them

do you have any suggestion for this? The only place I can find is
`jumprel-recipe--apply-filename-jumper' which is private. I could also
add it to the override of `jumprel-apply' but I'm not sure how to
reference an override from a docstring.

> - I find no documentation of how to describe alternatives -- several
> alternative file names produced from a single original file name

several alternatives can be produced with:

1. several jumpers produce several alternatives: all jumpers are
executed on the current file name and their results are merged into a
single list of candidates (see `jumprel--collect-existing-places' and
`jumprel--call-jumpers').

2. a function-based jumper returning a list (this is described in the
   docstring of `jumprel-apply')

3. a regexp-based jumper may also return a list of candidates if the
globs match several existing filenames

4. a recipe-based jumper may also return a list of candidates if
:add-directory is used and several matching directories exist

Does that answer your question or did I miss the point?

> - I wonder whether "recipes" like these are a convenient method of
>    customizing this facility: do people really find it easy to write
>    "ordered" property lists for this purpose?

I find the resulting syntax very easy to read:

(recipe :remove-suffix ".js" :add-suffix "-tests.js" :add-directory "tests" :case-transformer uncapitalize)
(recipe :remove-suffix ".js" :add-suffix ".spec.component.js" :filler (yasnippet :name "componentSpec"))
(recipe :remove-suffix ".js" :add-suffix ".less")
(recipe :remove-suffix ".js" :add-suffix ".stories.js" :filler (yasnippet :name "stories")))

I think this is much clearer than using regular expressions but this is
maybe only me? If you don't like the recipe syntax, we can leave this
one out of the patch and only include regexp-based jumpers.

What do you expect from me now? Send a new patch with the new package
name? Or do you plan to give more feedback first?

Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> I think jumprel would probably be better suited as an ELPA
> package. Like completion frameworks, there's no one size fits all in
> this area -- the DWIM for one person isn't the DWIM for another
> person.

Thank you very much Lars for giving feedback on this package! I
appreciate your point of view because you've already written a similar
feature which probably means you are using it.

> jumprel is a different take on what find-file does, just like Helm is
> a different take how completion should look.

I'm not sure I understand what you mean. I agree that there is no point
in having 10 many different completion frameworks in Emacs core (even
though we might be close to this number already 😊).

Similarly, I wouldn't like to have 3 find-related-files packages. But I
think that, contrary to completion frameworks, these 3 packages provide
the same feature: namely "a command to find file(s) related to the
current one". Said differently, the user-visible behavior is the
same. As soon as the setup is done, there shouldn't any difference
between `find-sibling-file' and `jumprel'.

Is there anything in your process that would change if you would switch
from `find-sibling-file' to `jumprel'?

In my opinion, what differs between these packages is the extensibility
of the implementation. If regexps are a good solution to configure
relations between files, both packages support that thanks to your
work. But if users want something else, they could only get it in
`jumprel': either with functions, with recipes or with something else of
their creation.

Also, jumprel supports creation of related files and automatic filling
of new files through an extensible mechanism I called a "filler".

Best

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Thu, 29 Sep 2022 11:54:56 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 58071 <at> debbugs.gnu.org
> Date: Wed, 28 Sep 2022 21:26:51 +0200
> 
> > - what you call "recipes", i.e. descriptors of how to generate the
> > name of related files from a given file name, should be documented in
> > a single doc string, and the other places that use recipes should
> > reference the symbol whose doc string documents them
> 
> do you have any suggestion for this? The only place I can find is
> `jumprel-recipe--apply-filename-jumper' which is private. I could also
> add it to the override of `jumprel-apply' but I'm not sure how to
> reference an override from a docstring.

I guess the doc string of jumprel-jumpers would be a possibility.

> 
> > - I find no documentation of how to describe alternatives -- several
> > alternative file names produced from a single original file name
> 
> several alternatives can be produced with:
> 
> 1. several jumpers produce several alternatives: all jumpers are
> executed on the current file name and their results are merged into a
> single list of candidates (see `jumprel--collect-existing-places' and
> `jumprel--call-jumpers').
> 
> 2. a function-based jumper returning a list (this is described in the
>    docstring of `jumprel-apply')
> 
> 3. a regexp-based jumper may also return a list of candidates if the
> globs match several existing filenames
> 
> 4. a recipe-based jumper may also return a list of candidates if
> :add-directory is used and several matching directories exist
> 
> Does that answer your question or did I miss the point?

It does answer, but this should be documented.

> What do you expect from me now? Send a new patch with the new package
> name? Or do you plan to give more feedback first?

A new patch, I guess.  With a better name and with the
documentation-related issues mentioned above fixed.

We should then discuss whether to have this in core or on ELPA.  Such
a discussion would perhaps need to be on emacs-devel, not here, to
catch a wider audience.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Thu, 29 Sep 2022 12:46:24 +0200

Damien Cassou <damien <at> cassou.me> writes:

> I'm not sure I understand what you mean. I agree that there is no point
> in having 10 many different completion frameworks in Emacs core (even
> though we might be close to this number already 😊).
>
> Similarly, I wouldn't like to have 3 find-related-files packages. But I
> think that, contrary to completion frameworks, these 3 packages provide
> the same feature: namely "a command to find file(s) related to the
> current one". Said differently, the user-visible behavior is the
> same. As soon as the setup is done, there shouldn't any difference
> between `find-sibling-file' and `jumprel'.

The similarity between completion frameworks and "jumping to files" is
that people have different needs.  Some would prefer something that
guesses for you, while others prefer to make the rules explicit.

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

From: Damien Cassou <damien <at> cassou.me>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Fri, 30 Sep 2022 10:43:48 +0200

>> Eli Zaretskii <eliz <at> gnu.org> writes:
>>> what you call "recipes", […] should be documented in a single doc
>>> string, and the other places that use recipes should reference the
>>> symbol whose doc string documents them

> From: Damien Cassou <damien <at> cassou.me>
>> do you have any suggestion for this?

Eli Zaretskii <eliz <at> gnu.org> writes:
> I guess the doc string of jumprel-jumpers would be a possibility.


`jumprel-jumpers' is in jumprel.el which is independent of
jumprel-recipe.el. I would like to keep the responsibility clean if
possible.



-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

From: Damien Cassou <damien <at> cassou.me>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Fri, 30 Sep 2022 10:44:56 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> The similarity between completion frameworks and "jumping to files" is
> that people have different needs.  Some would prefer something that
> guesses for you, while others prefer to make the rules explicit.


Why not having both with a reasonable default values that people can
populate? That being said, for now, jumprel and find-sibling-file both
provide no rule by default.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Fri, 30 Sep 2022 13:38:05 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 58071 <at> debbugs.gnu.org
> Date: Fri, 30 Sep 2022 10:43:48 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> > I guess the doc string of jumprel-jumpers would be a possibility.
> 
> `jumprel-jumpers' is in jumprel.el which is independent of
> jumprel-recipe.el. I would like to keep the responsibility clean if
> possible.

jumprel-recipe.el is AFAICT devoid of any recipe-related public APIs,
so I don't see how such a separation can be possible.  I also question
the motivation: is jumprel.el really independent of the inner workings
of the recipes as implemented in jumprel-recipe.el?  The interface
doesn't seem to me abstract enough to justify the separation.  Even if
I did agree that documentation must always be in the same place as the
code.  Which I don't necessarily agree with: there are many examples
when documentation and implementation are physically on different
files.

Anyway, you asked for suggestions, and I gave you one.  I still think
there's nothing wrong with it, but feel free to add the documentation
in some other place which looks more correct to you.

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

From: Damien Cassou <damien <at> cassou.me>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 58071 <at> debbugs.gnu.org
Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related
 files
Date: Thu, 06 Oct 2022 08:09:07 +0200

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

Please find a new version of the files attached and my answers to your
feedback below.

Eli Zaretskii <eliz <at> gnu.org> writes:
> "jumprel" is not the best name, IMO; something like
> "related-files" would be better

Renamed to related-files.

> what you call "recipes", i.e. descriptors of how to generate the
> name of related files from a given file name, should be documented
> in a single doc string

Agree.  Doc strings and file headers have been rewritten.  The doc
string of `related-files-jumpers' quickly describes all known kinds of
jumpers and refer to the customization interface and the manual (to be
written) for the details. I refrained from describing the full syntax of
every kind of jumper in `related-files-jumpers' to keep it
understandable.

The customization interface of `related-file-jumpers' has received a lot
of love with default values, clearer tags, documentation, and better
overall presentation.

> I find no documentation of how to describe alternatives -- several
> alternative file names produced from a single original file name

I fixed that by improving the doc strings of `related-files-jumpers',
`related-files-jump', `related-files-make',
`related-files-jump-or-make' and `related-files-apply'.

> jumprel-recipe.el is AFAICT devoid of any recipe-related public
> APIs, so I don't see how such a separation can be possible.

related-files-recipe.el overrides the `related-files-apply' method. So
loading this file introduces a new kind of jumper. This is the same for
related-files-regexp.el. Both files are completely optional and serve as
examples to implement more kinds of jumpers.

> I also question the motivation: is jumprel.el really independent of
> the inner workings of the recipes as implemented in
> jumprel-recipe.el?

I think it is and it has been designed with this in mind. As far as I
know, related-files.el works perfectly with 3 kinds of jumpers whose
implementation is really different:

- function-based jumpers are implemented in related-files.el as a
  default in cl-defgeneric methods.

- recipe-based jumpers are optional and implemented in
  related-files-recipe.el.

- regexp-based jumpers are optional and implemented in
  related-files-regexp.el.

> The interface doesn't seem to me abstract enough to justify the
> separation.

Would you mind explaining this part?

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[related-files.el (text/plain, attachment)]

[related-files-recipe.el (text/plain, attachment)]

[related-files-regexp.el (text/plain, attachment)]

[related-files-recipe-test.el (text/plain, attachment)]

[related-files-test.el (text/plain, attachment)]

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

From: hugo <at> heagren.com
To: bug-gnu-emacs <at> gnu.org
Subject: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related files
Date: Fri, 28 Oct 2022 23:08:26 +0100

Hi Damien,

I've been looking for a package just like this for a while now. I was
close to getting round to writing one, but now you have, so thank you!

I've had a look through it, and so far I really like it. I think its
probably a pretty common problem for lots of Emacs users (jumping to
related files easily), so I think including it in the core would make
sense, but I can also see the points others have made and wouldn't
mind downloading from somewhere else either.

Some comments:
- The package doesn't work for non-file based buffers, which in
  particular means it doesn't work in org (roam) capture buffers (for
  jumping to the pdf I'm making notes on). I appreciate that you need
  some sort of reference to get off the ground, and that /normally/
  that will be a file name, but for my use case it would be great to
  be able to use other things as well (org roam node id, or a citation
  ref). This would make a big difference to me. Of course, the package
  doesn't have to do all the work of handling these different cases,
  so long as the user can write their own functions for everything
  (and it is well documented how these interact/what types of inputs
  and outputs everything needs).
- Conversely, the package hard-codes /how/ to jump to a file---with
  `find-file'. This means I can't go the other way, from a pdf file to
  an org-roam-capture buffer on its notes (which is what I would like
  to do). Another way of saying this is the package assumes all places
  will be files, and that the best way to get to them is `find-file'.
  It would be nice to be able to specify (perhaps customisable,
  arbitrary?) types of places and functions actually used to /do/ the
  jumping. (though I agree that `find-file' is a very sensible
  default).
- At the moment, the presented list of places (files) to jump to is
  just a list of strings (as in, there is no file metadata, so things
  like Marginalia don't work properly). I think this should be fixed.
  This might also make it easier to implement different kinds of
  jumpers; have an alist of ~(CATEGORY . JUMP-FUNCTION)~ function
  pairs. Whenever the user selects something from the jump list, get
  its category, look that up, and then ~(funcall JUMP-FUNCTION
  SELECTION)~. Ideally, any such system should also support
  pretty-printing functions for non-string (e.g. org-roam nodes)
  places. Just a thought, I don't know how easy this would be to
  implement.
- Documentation could be improved, but you knew that already, and
  there isn't much point until the package reaches a more stable
  state. Once it is, I would be happy to write some if you want help.
- I can see myself using something like `:filler' a lot, but not
  necessarily for altering the buffer, and which runs every time I
  jump (or maybe every time I jump, /and/ the buffer I end up is newly
  created---even if the file already existed). I'm thinking about
  things like setting local variables which I might use later for
  establishing targets to jump /back/ to from that buffer. Perhaps
  something like this could be included in a a separate `:hook' or
  `:final' keyword, which would be run /last/ in the jumping process.

Hope some of that is useful, or finds its way into some code. I'd be
happy to make patch contributions, but at this stage I'd like to hear
what you think about how I want to use the package and what you want
to include before I start hacking.

Hugo

Previous Next

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