checkdoc: URLs in docstrings with lisp symbols

checkdoc: URLs in docstrings with lisp symbols

[Bill Wohler]

I have the following in a docstring:

  Use the \"make-face\" (http://quimby.gnus.org/circus/face/make-face)
  script

checkdoc ignores the make-face string but complains that the make-face
bit in the URL should be quoted `'. The Info node (elisp)Documentation
Tips doesn't say how URLs should be treated.

Should I be quoting URLs in docstrings? Given that I usually quote
filenames, that might not be a bad way to go.

  Use the \"make-face\" (\"http://quimby.gnus.org/circus/face/make-face\")
  script

The following patch to checkdoc-this-string-valid-engine in checkdoc.el
avoids symbol matches immediately after a / and fixes the error I saw.
Is this OK?

Index: checkdoc.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/emacs-lisp/checkdoc.el,v
retrieving revision 1.51
diff -u -u -r1.51 checkdoc.el
--- checkdoc.el	24 Sep 2005 13:43:59 -0000	1.51
+++ checkdoc.el	27 Oct 2005 22:44:49 -0000
@@ -1802,7 +1803,7 @@
        (let ((found nil) (start (point)) (msg nil) (ms nil))
 	 (while (and (not msg)
 		     (re-search-forward
-		      "[^-([`':a-zA-Z]\\(\\w+[:-]\\(\\w\\|\\s_\\)+\\)[^]']"
+		      "[^-([`':/a-zA-Z]\\(\\w+[:-]\\(\\w\\|\\s_\\)+\\)[^]']"
 		      e t))
 	   (setq ms (match-string 1))
 	   (save-match-data


-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: checkdoc: URLs in docstrings with lisp symbols

[Richard M. Stallman]

    checkdoc ignores the make-face string but complains that the make-face
    bit in the URL should be quoted `'. The Info node (elisp)Documentation
    Tips doesn't say how URLs should be treated.

The right way to treat them would be in a way that enables
the help facility to follow the link and display the URL.
I tend to think that `' quoting is the natural way to implement that.
Would you like to implement that?

Re: checkdoc: URLs in docstrings with lisp symbols

[Bill Wohler]

"Richard M. Stallman" <rms@gnu.org> writes:

>     checkdoc ignores the make-face string but complains that the make-face
>     bit in the URL should be quoted `'. The Info node (elisp)Documentation
>     Tips doesn't say how URLs should be treated.
>
> The right way to treat them would be in a way that enables
> the help facility to follow the link and display the URL.
> I tend to think that `' quoting is the natural way to implement that.
> Would you like to implement that?

That sounds like a good idea. Done.

I've updated help-mode.el based upon the code to follow Info
references. The code now recognizes strings like "URL
`http://www.gnu.org/'" and uses browse-url to view them.

I've updated etc/NEWS, man/help.texi, and lispref/tips.texi with this
new feature.

However, I haven't yet documented that this feature uses browse-url.
It seems that the user should know where to go to customize his
browsing experience. Should I mention this in (emacs)Help Mode. If
not, where?

p.s. Eli will notice that I documented the use of "URL" but the code
accepts "url" as well ;-). This is intentional. I'd prefer folks use
uppercase for acronyms, but I wanted the code to be liberal.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: checkdoc: URLs in docstrings with lisp symbols

[Richard M. Stallman]

    However, I haven't yet documented that this feature uses browse-url.
    It seems that the user should know where to go to customize his
    browsing experience. Should I mention this in (emacs)Help Mode. If
    not, where?

I guess there is the best place.

Re: checkdoc: URLs in docstrings with lisp symbols

[Bill Wohler]

"Richard M. Stallman" <rms@gnu.org> writes:

>     However, I haven't yet documented that this feature uses browse-url.
>     It seems that the user should know where to go to customize his
>     browsing experience. Should I mention this in (emacs)Help Mode. If
>     not, where?
>
> I guess there is the best place.

Thanks. Done.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.