[COMMIT] Fix confusing and incorrect docstring for regexp-opt

[Aidan Kehoe]

SUPERSEDES 18306.7206.428781.245956 at parhasard.net

 Ar an t-ochtú lá de mí Eanair, scríobh Stephen J. Turnbull: 

 > APPROVE
 > 
 > but as usual I have my personal preferences. ;-)
 > 
 > Aidan Kehoe writes:
 >  > 
 >  > Yes, my version is a bit long-winded. I think it’s clearer than the old
 >  > version, though; in a strict sense the old version was incorrect, too,
 >  > because every string that doesn’t use regexp special characters is a regexp.
 >  > 
 >  > 2008-01-07  Aidan Kehoe  <kehoea at parhasard.net>
 >  > 
 >  > 	* regexp-opt.el (regexp-opt): 
 >  > 	Clarify the treatment of regexp special characters in STRINGS.
 >  > 
 >  > XEmacs Packages source patch:
 >  > Diff command:   cvs -q diff -u
 >  > Files affected: xemacs-packages/xemacs-base/regexp-opt.el
 >  > ===================================================================
 >  > RCS
 >  > 
 >  > Index: xemacs-packages/xemacs-base/regexp-opt.el
 >  > ===================================================================
 >  > RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/xemacs-base/regexp-opt.el,v
 >  > retrieving revision 1.3
 >  > diff -u -r1.3 regexp-opt.el
 >  > --- xemacs-packages/xemacs-base/regexp-opt.el	2003/10/29 16:31:46	1.3
 >  > +++ xemacs-packages/xemacs-base/regexp-opt.el	2008/01/07 12:27:44
 >  > @@ -94,8 +94,12 @@
 >  >  ;;;###autoload
 >  >  (defun regexp-opt (strings &optional paren)
 >  >    "Return a regexp to match a string in STRINGS.
 >  > -Each string should be unique in STRINGS and should not contain any regexps,
 >  > -quoted or not.  If optional PAREN is non-nil, ensure that the returned regexp
 >  > +Each string should be unique in STRINGS.  Regexp special characters in the
 >  > +elements of STRINGS will not be treated as special characters; that is to
 >  > +say, `regexp-opt' will call `regexp-quote' on the elements of STRINGS before
 >  > +constructing the regexp.
 > 
 > I would write
 > 
 >     "Return a regexp which matches exactly those strings in STRINGS.
 > 
 >     Each string in STRINGS should be unique.  Regexp special characters in
 >     the elements of STRINGS will not be treated specially in matching;
 >     they will be escaped as necessary in constructing the regexp."

Okay, done. Thank you. 

NOTE: This patch has been committed.

xemacs-packages/xemacs-base/ChangeLog addition:

2008-01-12  Aidan Kehoe  <kehoea at parhasard.net>

	* regexp-opt.el (regexp-opt): 
	Clarify the treatment of regexp special characters in STRINGS,
	taking on board input from Stephen. Thank you Stephen!


XEmacs Packages source patch:
Diff command:   cvs -q diff -Nu
Files affected: xemacs-packages/xemacs-base/regexp-opt.el
===================================================================
RCS

Index: xemacs-packages/xemacs-base/regexp-opt.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/xemacs-base/regexp-opt.el,v
retrieving revision 1.4
diff -u -u -r1.4 regexp-opt.el
--- xemacs-packages/xemacs-base/regexp-opt.el	2008/01/11 23:12:50	1.4
+++ xemacs-packages/xemacs-base/regexp-opt.el	2008/01/12 17:55:30
@@ -88,14 +88,19 @@
 
 ;;; Code:
 
+;; XEmacs; correct the docstring, make it clearer.
 ;;;###autoload
 (defun regexp-opt (strings &optional paren)
-  "Return a regexp to match a string in the list STRINGS.
-Each string should be unique in STRINGS and should not contain any regexps,
-quoted or not.  If optional PAREN is non-nil, ensure that the returned regexp
-is enclosed by at least one regexp grouping construct.
-The returned regexp is typically more efficient than the equivalent regexp:
+  "Return a regexp which matches exactly those strings in STRINGS.
 
+Each string in STRINGS should be unique.  Regexp special characters in
+the elements of STRINGS will not be treated specially in matching;
+they will be escaped as necessary in constructing the regexp.
+
+If optional PAREN is non-nil, ensure that the returned regexp is enclosed by
+at least one regexp grouping construct.  The returned regexp is typically
+more efficient than the equivalent regexp:
+
  (let ((open (if PAREN \"\\\\(\" \"\")) (close (if PAREN \"\\\\)\" \"\")))
    (concat open (mapconcat 'regexp-quote STRINGS \"\\\\|\") close))
 
@@ -117,7 +122,8 @@
 	   (re (regexp-opt-group sorted-strings open)))
       (if words (concat "\\<" re "\\>") re))))
 
-;; XEmacs; added here. This is in subr.el in GNU. 
+;; XEmacs; added here. This is in subr.el in GNU; this implementation is
+;; from their revision 1.541 of 2007-01-04, under GPL 2. 
 (defun-when-void subregexp-context-p (regexp pos &optional start)
   "Return non-nil if POS is in a normal subregexp context in REGEXP. 
 A subregexp context is one where a sub-regexp can appear. 

-- 
¿Dónde estará ahora mi sobrino Yoghurtu Nghé, que tuvo que huir
precipitadamente de la aldea por culpa de la escasez de rinocerontes?