URL refs in docstrings when bolp

URL refs in docstrings when bolp

[S+*n_Pe*rm*n]

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)))

Re: URL refs in docstrings when bolp

[MON KEY]

Actually, I can't reproduce the behavior described earlier.  Was a
fontlock misinterp.
Sorry for the noise.

On Fri, Feb 13, 2009 at 1:47 PM, S+*n_Pe*rm*n <stan@derbycityprints.com> wrote:
> 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)))
>

Re: URL refs in docstrings when bolp

[Stefan Monnier]

> 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.

It only adds length in the source code, not in the actual string (and
hence not in the *Help* buffer).  So it's not a real problem.


        Stefan