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

[Eli Zaretskii <eliz@gnu.org>]

> From: Damien Cassou <damien@cassou.me>
> Cc: 58071@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.