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: Fri, 10 Oct 2003 10:31:49 -0500 (CDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200310101531.h9AFVnX22383@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 1065800462 15630 80.91.224.253 (10 Oct 2003 15:41:02 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 10 Oct 2003 15:41:02 +0000 (UTC) Cc: rms@gnu.org, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Fri Oct 10 17:40:59 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 1A7zNz-0006PA-00 for ; Fri, 10 Oct 2003 17:40:59 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A7zNz-0001oo-00 for ; Fri, 10 Oct 2003 17:40:59 +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 1A7zLr-0000Uh-IR for emacs-devel@quimby.gnus.org; Fri, 10 Oct 2003 11:38:47 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1A7zJm-0008MQ-Vy for emacs-devel@gnu.org; Fri, 10 Oct 2003 11:36:38 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1A7zJE-0008EC-B3 for emacs-devel@gnu.org; Fri, 10 Oct 2003 11:36:35 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A7zJC-0008DS-O7; Fri, 10 Oct 2003 11:36:03 -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 h9AFa0AJ023913; Fri, 10 Oct 2003 10:36:00 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id h9AFVnX22383; Fri, 10 Oct 2003 10:31:49 -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 10 Oct 2003 10:14:50 -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:17016 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:17016 Stefam Monnier wrote: > but I made the double semicolons in the commented out code into > triple semicolons myself, because that is how (elisp)Comment Tips > wants code commented out. Please don't. It might be documented that way, but outline-minor-mode behaves very poorly with them. And it's very hard to "fix" outline-minor-mode because it can't tell the difference between the case where the three-semi-comment is used for a major heading or for commented out code. I think the doc should be fixed. But then we should not only change (elisp)Comment Tips, but also quantify the assertion: * Indent each function with `C-M-q' (`indent-sexp') using the default indentation parameters. in (elisp)Coding Conventions, as well as change (probably plenty of) existing code. See for instance "describe-text.el", lines 222 and following. Note that three semicolons are currently recommended and used for _several_ purposes other than "major headings", see (elisp)Comment Tips. The most important ones are for use _within a function_. The fact that we would get trouble with C-M-q if we follow your suggestion seems to be a real nuisance. I would not immediately see how to fix that problem either. And it's very hard to "fix" outline-minor-mode because it can't tell the difference between the case where the three-semi-comment is used for a major heading or for commented out code. Can outline-minor-mode not "see" that the commented out code is inside a function or other Lisp form? I would guess that is pretty rare for a major heading to occur in the middle of a function. The commented out code in "describe-text.el" is _not_ inside a function. I do not know whether this code yields problems for outline-minor-mode. However, on the one hand, one is not going to call C-M-q easily on commented out code outside functions (so using two semicolons _there_ would not seem that bad) and, on the other, if one gets "really desperate" one can, in the worst case, place the commented out code inside a call to `ignore'. But one could also start (and maybe end) commented out code outside functions with some standard comment, so outline-minor-mode (and actually a person reading through the file) can easily recognize it for what it is. Anyway, whatever is decided on this, I believe that it is important that we all follow the _same_ conventions and that these conventions are clearly and accurately documented. If we all "do are own thing" then _both_ outline-minor-mode and C-M-q will have problems and we get the "worst of both worlds". Sincerely, Luc.