bug#17862: 24.3; regexp-opt docstring is incorrect

[npostavs@users.sourceforge.net]

immerrr again <immerrr@gmail.com> writes:
>>> +non-@code{nil}
>>
>> Should be just non-nil, I believe.
>>
>
> I was following the precedent set by other documentation in
> searching.texi.

Oh, hmm, you're right, most uses are non-@code{nil}.  Somehow I had the
impression that nil should be undecorated (maybe I mixed up with
docstring quoting rules).

>
> I agree that adding "impenetrable definitions" might be unclear, but I'd argue
> that it's still an improvement because the equivalence statement is
> plain false now:
>
> - "words" and "symbol" keywords add special backslash characters
> around the result
>
> - if PAREN is nil, the result is still grouped (unless the strings can be
>   represented as a character set, but that's not handled in the
> simplified version)
>
> I doubt we can put all the logic behind PAREN into the simplified version.

Hah, sounds like a challenge :) How about

    (defun simplified-regexp-opt (strings &optional paren)
      (let ((parens (cond ((eq paren 'words)    '("\\<\\(" . "\\)\\>"))
                          ((eq paren 'symbols) '("\\_<\\(" . "\\)\\_>"))
                          ((null paren)          '("\\(?:" . "\\)"))
                          (t                       '("\\(" . "\\)")))))
        (concat (car paren)
                (mapconcat 'regexp-quote strings "\\|")
                (cdr paren))))

> +@code{nil}
> +    if all @var{strings} are single-character, the resulting regexp is
> +    not surrounded, otherwise it is surrounded by @samp{\(?:} and
> +    @samp{\)}.

Zero character strings also:

    (regexp-opt '("a" "")) ;=> "a?"

How about saying "the regexp may be surrounded with \?(: ) to ensure that
it constitutes a single expression (such that appending a postfix
operator like '+' will apply to the whole expression)."