From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "S+*n_Pe*rm*n" Newsgroups: gmane.emacs.devel Subject: URL refs in docstrings when bolp Date: Fri, 13 Feb 2009 13:47:18 -0500 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1234550855 26029 80.91.229.12 (13 Feb 2009 18:47:35 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 13 Feb 2009 18:47:35 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Feb 13 19:48:51 2009 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1LY35l-0001Sz-Lh for ged-emacs-devel@m.gmane.org; Fri, 13 Feb 2009 19:48:49 +0100 Original-Received: from localhost ([127.0.0.1]:41311 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LY34R-0005lY-M4 for ged-emacs-devel@m.gmane.org; Fri, 13 Feb 2009 13:47:27 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1LY34M-0005l1-Fx for emacs-devel@gnu.org; Fri, 13 Feb 2009 13:47:22 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1LY34L-0005kp-QF for emacs-devel@gnu.org; Fri, 13 Feb 2009 13:47:22 -0500 Original-Received: from [199.232.76.173] (port=56059 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LY34L-0005km-Nd for emacs-devel@gnu.org; Fri, 13 Feb 2009 13:47:21 -0500 Original-Received: from mail-gx0-f208.google.com ([209.85.217.208]:46829) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1LY34L-0004ej-Bw for emacs-devel@gnu.org; Fri, 13 Feb 2009 13:47:21 -0500 Original-Received: by gxk4 with SMTP id 4so1054692gxk.18 for ; Fri, 13 Feb 2009 10:47:19 -0800 (PST) Original-Received: by 10.142.214.5 with SMTP id m5mr1052384wfg.266.1234550838707; Fri, 13 Feb 2009 10:47:18 -0800 (PST) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 2) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:109048 Archived-At: 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)))