Subject: Re: bug#58071: 28.2; [PATCH] jumprel: A tool to find/create related files

From: Damien Cassou <[email-masked]>
Date: Thu, 06 Oct 2022 08:09:07 +0200

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

Eli Zaretskii <[email-masked]> 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