From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: Undocumented hyperlinks in doc strings. Date: Sat, 11 Oct 2003 22:34:42 -0500 (CDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200310120334.h9C3Ygk26986@raven.dms.auburn.edu> References: <200310090050.h990oIa15681@raven.dms.auburn.edu> <200310100327.h9A3REl20310@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1065930075 20680 80.91.224.253 (12 Oct 2003 03:41:15 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 12 Oct 2003 03:41:15 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sun Oct 12 05:41:13 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1A8X6X-00036S-00 for ; Sun, 12 Oct 2003 05:41:13 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A8X6X-0008K4-00 for ; Sun, 12 Oct 2003 05:41:13 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A8X5d-0007pm-44 for emacs-devel@quimby.gnus.org; Sat, 11 Oct 2003 23:40:17 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1A8X5V-0007oE-Cj for emacs-devel@gnu.org; Sat, 11 Oct 2003 23:40:09 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1A8X4z-0007ak-Ep for emacs-devel@gnu.org; Sat, 11 Oct 2003 23:40:08 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A8X4O-0006v1-VY; Sat, 11 Oct 2003 23:39:01 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id h9C3cvAJ029182; Sat, 11 Oct 2003 22:38:58 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id h9C3Ygk26986; Sat, 11 Oct 2003 22:34:42 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Sat, 11 Oct 2003 01:36:48 -0400) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:17036 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:17036 Richard Stallman wrote: This means that a simple M-q can easily enable or disable several hyperlinks. This does not seem good. The change in `help-xref-symbol-regexp' treats newlines as any other whitespace. Thanks for noticing and fixing this bug. Please install your change. Meanwhile, it might be another bug to allow more than one whitespace character between words like `function' and the function name. Multiple spaces never happen in normal text, only when there is a sort of deliberate paragraph breaking or tabular structure. In those cases, going across paragraphs or fields would probably be a mistake. and: Three or more semicolons are the convention for comments that should start at the margin, and that is our standard way of commenting out code. Like anything, it could be changed, but that is a rather heavy change to make and I would hesitate to do it on account of outline-minor-mode. That leaves two questions to be addressed before I install my change. In as far as the first one goes, one could replace the occurrences of [ \t\n]+ and [ \t\n]* (the latter probably would have to be changed to [ \t\n]+ anyway, for consistency) in my patch by [ \n]. (If one does not allow multiple spaces, it seems consistent not to allow tab either.) That would mean that the author would have to be careful about "space related sloppiness" like trailing whitespace or an inadvertent inappropriate double space inside a sentence. _As long as_ the author is careful to check his documentation strings with a C-h v or C-h f (I always do, but I do not know about other people) that would be an advantage, because the lack of hyperlink would immediately point out the problem. In as far as the second goes, I infer from your response that you prefer the three semi-colon solution of my original patch over the two semi-colon re-indentation I proposed in a reply to Stefan. (I do not believe that the _current_ two semi-colon indentation makes sense, since it is "C-M-q instable".) Just in case, what about a convention to follow ;;; by a single space if one wants the line two be considered a "heading line" by outline-minor-mode and by at least two spaces if one wants it to be considered a "body line". The three semi-colons are mostly important for commented out code _inside_ a function and apart from an initial comment (;;; this used: , in the code at issue) and possibly commented out parts of the documentation string, at least two spaces usually follow the semi-colons anyway. So, in the code in question, one just would have to replace: ;;; this used: with: ;;; this used: without any other change to the original three semi-colon solution. With: ";;;;* [^ \t\n]\\|(" instead of the current ";;;;* \\|(" as outline-regexp in emacs-lisp-mode, none of the commented out code would be considered a heading line by outline-minor-mode. Sincerely, Luc.