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: Tue, 14 Oct 2003 20:38:32 -0500 (CDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200310150138.h9F1cWg10456@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 1066191806 14272 80.91.224.253 (15 Oct 2003 04:23:26 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 15 Oct 2003 04:23:26 +0000 (UTC) Cc: rms@gnu.org, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed Oct 15 06:23:24 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 1A9dC0-00070v-00 for ; Wed, 15 Oct 2003 06:23:24 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A9dC0-00069i-00 for ; Wed, 15 Oct 2003 06:23:24 +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 1A9dA8-00043G-4s for emacs-devel@quimby.gnus.org; Wed, 15 Oct 2003 00:21:28 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1A9ch2-00022W-8Q for emacs-devel@gnu.org; Tue, 14 Oct 2003 23:51:24 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1A9cSQ-0006LI-8H for emacs-devel@gnu.org; Tue, 14 Oct 2003 23:36:49 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A9agp-0003Sd-Pf; Tue, 14 Oct 2003 21:43:04 -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 h9F1guAJ011987; Tue, 14 Oct 2003 20:42:56 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id h9F1cWg10456; Tue, 14 Oct 2003 20:38:32 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: monnier@IRO.UMontreal.CA In-reply-to: (message from Stefan Monnier on 14 Oct 2003 17:03:45 -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:17101 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:17101 Stefan Monnier wrote: It's a fundamental problem that the convention leads to ambiguities that only a human being can resolve. That could be mended by a slight change in the current standard (which, to me, means: "as recommended in the Elisp manual") way of commenting out code, which I proposed in an earlier message: follow the semicolons by a single space if the line is meant to be a heading line and by at least two spaces otherwise. Anyway, in as far as I am concerned, one could stay with the current standard as is, or add my proposed modification, or change to your proposed convention, I do not mind either way, as long as the actual chosen standard is accurately and clearly documented in the Elisp manual. I want to concentrate on the commented out code in `help-make-xrefs' which according to me is should simply be deleted: ((match-string 7) ! ;;; this used: ! ;;; #'(lambda (arg) ! ;;; (let ((location ! ;;; (find-function-noselect arg))) ! ;;; (pop-to-buffer (car location)) ! ;;; (goto-char (cdr location)))) (help-xref-button 8 'help-function-def sym)) The "commented out code" is actually not code "commented out in place", but the old second argument to `help-xref-button', which, at the time, also required an extra fourth argument. This got replaced in revision 1.232 to help.el by the current second argument 'help-function-def. I believe the "commented out code" has been obsolete for more than two years by now. Why keep it? If we systematically kept old code around like this and never deleted it, source files would quickly become bloated and hard to read. Sincerely, Luc.