bug#52558: Option for easier typing of regexps

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: laszlomail@protonmail.com,  52558@debbugs.gnu.org
> Date: Tue, 28 Dec 2021 22:51:09 +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.
> 
> But "isearch-regexp-function" is too long for the first sentence.

Yes.  But I didn't mean to include that name in the first sentence, I
meant to say that we should say there something to better explain the
purpose.

> > And second, the doc string of isearch-regexp-function says nothing
> > about replacements.
> 
> It should say nothing about replacements.  This is explained
> in the second sentence:
> 
>   `isearch-regexp-function' is bound to it when searching
>   for a string to replace.

So we have now made a full circle, and came back to what I said
initially: "searching for a string to replace" doesn't explain itself,
because the relevance of this to some search of a string and to some
replacement is not clear.

How about if you try to explain it to me in your own words, without
paying attention to the constraints of a doc string, and I will then
try to propose a more formal wording?

Thanks.