emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

URL refs in docstrings when bolp


From: S+*n_Pe*rm*n
Subject: URL refs in docstrings when bolp
Date: Fri, 13 Feb 2009 13:47:18 -0500

When including URL references in docstrings of the form:
(URL `http://www.some-site.com')
It happens quite frequently that the URL is at or near 80 columns in
length. At the very least a properly formatted web URL will include at
least 9-13 chars, `http://', and `.com|gov|edu|org|net|fr'. Likewise
an additional 8 chars are needed to `wrap` the actual url; "`(URL "
and "')" for hyper-linked inclusion in the docstring.

This amounts to ~20 syntax/formatting chars i.e. 25% of the available
80 cols for the most vanilla of web addresses. Because it can be
difficult to split a URL across lines, I find that when a URL
reference is needed in a docstring on the current line should point be
at or beyond column 40 the URL generally winds up on a newline.
However, when this happens the opening paren will cause evaluation of
the symbol to throw an error. The solution of course is to escape the
paren. However, this just adds more length to the existing URL.

I propose the it should be possible to include a URL at BOL without
needing any additional indentation or escapes. I also propose that in
the absence of such a convenience Elisp programs are less apt to
provide hyperlinked URL refs in docstrings. Inclusion of URLs in
docstrings esp. when the function calls out to an external network
location uses the URL libraries is a most legitimate need. One should
not be required to open the elisp simply to examine how a given
function might invoke external processes which will then ping a remote
server. Equally, one should not be required to kill/yank a region
containing a url in a docstring to examine whether the refrenced URL
does indeed point to a legitimate/live destination.

Example of URL occurrences in docstrings:

(defun get-gnu-or-query (&optional gnu-q)
"Browse GNU Emacs webpage (URL `http://www.gnu.org/software/emacs/').
When non-nil GNU-Q prompts for term or phrase to query at:
(URL `http://www.gnu.org/cgi-bin/estseek.cgi?phrase=')."
(interactive "p")
(let
    ((gnurl
      (if (and gnu-q)
          (concat "http://www.gnu.org/cgi-bin/estseek.cgi?phrase=";
                  (replace-regexp-in-string " " "+" (read-string "Term to 
Query?: ")))
        "http://www.gnu.org/software/emacs/";)))
  (browse-url gnurl)))




reply via email to

[Prev in Thread] Current Thread [Next in Thread]