Subject: Re: bug#52558: Option for easier typing of regexps

From: Eli Zaretskii <[email-masked]>
Date: Tue, 28 Dec 2021 22:35:19 +0200

> From: Juri Linkov <[email-masked]>
> Cc: [email-masked],  [email-masked]
> Date: Tue, 28 Dec 2021 22:25:56 +0200
> 
> >> +(defvar replace-regexp-function nil
> >> +  "Function to convert a search string to a regexp to replace.
> >> +It's bound to `isearch-regexp-function' when searching
> >> +for a string to replace.")
> >
> > The first sentence is unclear: what do you mean by "convert a search
> > string to a regexp to replace"?  What "search string" is being
> > converted to regexp, and how does "replace" enter this picture?
> 
> It has a reference to `isearch-regexp-function' that has
> a complete explanation to avoid duplication of the docstring.

I don't think this is enough.  First, the first sentence of the above
doc string doesn't have any such reference, so Apropos commands, which
show only the first sentence, will not have that reference.  And
second, the doc string of isearch-regexp-function says nothing about
replacements.

There's no need to repeat the whole story you have in
isearch-regexp-function, just to say enough for the reader to
understand what is this function about and what it is used for.

> >   It's bound to `isearch-regexp-function' when searching
> >
> > seems to be incorrect: it's isearch-regexp-function that's bound to
> > replace-regexp-function, not the other way around.
> 
> Maybe this is better:
> 
>   `isearch-regexp-function' is bound to it when searching

Yes, definitely better.