bug#52558: Option for easier typing of regexps

[Juri Linkov]

>> >> >> +(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?

query-replace uses isearch functions to search the next occurrence to replace.
The new variable replace-regexp-function is intended just to set
the value of isearch-regexp-function that is used by isearch functions.
And isearch-regexp-function already has 18 lines of its docstring
that explains all details.  This is why it's important to have a link
to isearch-regexp-function in the docstring of replace-regexp-function.