From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Undocumented hyperlinks in doc strings. Date: 10 Oct 2003 13:23:28 -0400 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <200310090050.h990oIa15681@raven.dms.auburn.edu> <200310100327.h9A3REl20310@raven.dms.auburn.edu> <200310101531.h9AFVnX22383@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1065806847 29642 80.91.224.253 (10 Oct 2003 17:27:27 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 10 Oct 2003 17:27:27 +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 19:27:25 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 1A812z-0005Tm-00 for ; Fri, 10 Oct 2003 19:27:25 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A812z-0002Gv-00 for ; Fri, 10 Oct 2003 19:27:25 +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 1A810a-0005RZ-An for emacs-devel@quimby.gnus.org; Fri, 10 Oct 2003 13:24:56 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1A810V-0005Ob-98 for emacs-devel@gnu.org; Fri, 10 Oct 2003 13:24:51 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1A80zy-0004fl-Lr for emacs-devel@gnu.org; Fri, 10 Oct 2003 13:24:49 -0400 Original-Received: from [132.204.24.67] (helo=mercure.iro.umontreal.ca) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A80zK-0003MR-2z; Fri, 10 Oct 2003 13:23:38 -0400 Original-Received: from vor.iro.umontreal.ca (vor.iro.umontreal.ca [132.204.24.42]) by mercure.iro.umontreal.ca (8.12.9/8.12.9) with ESMTP id h9AHNTKS019653; Fri, 10 Oct 2003 13:23:29 -0400 Original-Received: by vor.iro.umontreal.ca (Postfix, from userid 20848) id 0BEA73C549; Fri, 10 Oct 2003 13:23:28 -0400 (EDT) Original-To: Luc Teirlinck In-Reply-To: <200310101531.h9AFVnX22383@raven.dms.auburn.edu> Original-Lines: 76 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3.50 X-MailScanner-DIRO: Found to be clean 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:17020 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:17020 >> 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. I don't understand what you mean here. My recommendation is to use two semi-colons instead of three. The indentation of those semi-colons is the same as normal code and works just fine for commented-out code (this style is of commenting-out is already used at many places). One problem is that comment-region by default puts the comment markers in column 0. But setting comment-style to any value other than `plain' addresses this issue. > in (elisp)Coding Conventions, as well as change (probably plenty of) > existing code. Some of the code uses the documented convention while other uses the convention that I propose. I don't know which is more common, but neither is "marginal". We've lived with this "inconsistency" without even thinking about it for many years, so I see no reason to go and "fix" it all at once for the sake of it. But I do turn the three-semi to two-semi when I come across them with outline-minor-mode. > 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_. I know, and the difficulty to tell one case from the radically different other is the reason why I think the doc is broken. > The fact that we would get trouble with C-M-q if we follow your > suggestion seems to be a real nuisance. I have no idea what trouble you're referring to. I use M-C-q on a regular basis without any trouble whatsoever. > Can outline-minor-mode not "see" that the commented out code is inside > a function or other Lisp form? It's pretty difficult and costly to do so (need to extend outline.el so as to allow more than just regexps to specify headings). Furthermore it won't work right in the case where three-semi commented-out code code is outside of a lisp form (pretty common) and it won't work right either when a heading is inside a lisp form (not a real concern, but possible and meaningful). > commented out code outside functions (so using two semicolons _there_ > would not seem that bad) and, on the other, if one gets "really Outside of functions, two-semi and three-semi behave just the same, indentationwise, so it's really a non-issue. > then _both_ outline-minor-mode and C-M-q will have problems and we get > the "worst of both worlds". C-M-q doesn't need to differentiate between major headings and other comments, so as far as I know, it is completely unaffected by the issue discussed here. Unless I missed something, of course. Stefan