From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Juanma Barranquero Newsgroups: gmane.emacs.devel Subject: Re: new *Help* argument highlighting Date: Wed, 12 May 2004 13:47:07 +0200 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <20040512133037.FB60.JMBARRANQUERO@wke.es> References: <20040512130729.FB5D.JMBARRANQUERO@wke.es> <200405121125.UAA11097@etlken.m17n.org> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1084363026 22267 80.91.224.253 (12 May 2004 11:57:06 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 12 May 2004 11:57:06 +0000 (UTC) Cc: Kenichi Handa Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed May 12 13:56:57 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BNsM4-0003BS-00 for ; Wed, 12 May 2004 13:56:56 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BNsM3-0005ZO-00 for ; Wed, 12 May 2004 13:56:56 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1BNsGw-0007Mt-Pb for emacs-devel@quimby.gnus.org; Wed, 12 May 2004 07:51:38 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.34) id 1BNsFy-0007MN-3k for emacs-devel@gnu.org; Wed, 12 May 2004 07:50:38 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.34) id 1BNsFR-0007Iv-6P for emacs-devel@gnu.org; Wed, 12 May 2004 07:50:37 -0400 Original-Received: from [62.22.181.117] (helo=idefix.laley.net) by monty-python.gnu.org with esmtp (Exim 4.34) id 1BNsCa-00076A-DW for emacs-devel@gnu.org; Wed, 12 May 2004 07:47:08 -0400 Original-Received: from [172.17.221.23] (jsredondo.wk.org [172.17.221.23]) by idefix.laley.net with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2655.55) id K4TS1QX6; Wed, 12 May 2004 13:47:02 +0200 Original-To: emacs-devel@gnu.org In-Reply-To: <200405121125.UAA11097@etlken.m17n.org> X-Mailer: Becky! ver. 2.08.01 [en] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.4 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:23236 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:23236 On Wed, 12 May 2004 20:25:38 +0900 (JST) Kenichi Handa wrote: > Really? I think it's very rare that a docstring of a > funciton that has an argument NAME contains a reference to a > shell/perl variable NAME in the form $NAME? OK, but we're assuming different things. With @var{ARG}, it wouldn't be necessary to pre-scan the usage info to heuristically find the args, as it is done now. A simple walk through the "doc" part of the docstring would allow to find @var{ARG}s, highlight them and save them, so in fact the opposite is true: the information gathered processing the doc would allow to highlight the usage info, so arguments not referenced would *not* be highlighted in the usage info either (and, in this way, alerting the doc writer and the user that the argument is not described in the doc). That would also eliminate any need to recognize CL-style arglists, BTW. What you propose is as is done now: scan the usage, recognize the args, and then substitute the args in the doc. That is helpful, because it would prevent accidental highlighting, but that case is rare even now (defstruct, for example, mentions NAME-SLOT accessors, and the reference is not highlighted), so perhaps is not worth the change. To be fair, if implemented as I suggest, both the current scan-usage-then-doc and my proposed scan-doc-then-usage methods would have to coexist (we're not going to retroactively update thousands of docstrings), but at least we could do: scan-doc-then-usage; if it does not find any @{var}, fall back to old method. > I grepped "\$[a-z]" in etc/DOC but found none. Hu? C:\...\etc> grep "\$[A-Za-z]" DOC `$FOO' where FOO is an environment variable name means to substitute `$FOO' where FOO is an environment variable name means to substitute the entire variable name in braces. For instance, in `ab$cd-x', `$cd' is treated as an environment variable. For example, invoke "emacs -batch -f batch-byte-compile $emacs/ ~/*.el". Insert a copyright by $ORGANIZATION notice at cursor. $ type sys$input For example, invoke "emacs -batch -f batch-info-validate $info/ ~/*.info" nil means the default, which is ("/usr/spool/mail/$USER") And \@[A-Za-z] returns 33 hits. > The reason I prefer a shorter name is that I want to keep > the first line of a docstring in a source code short because > we can't fill it. Yes, I imagine as much. > And, if we use @var{NAME}, it's get a > little bit difficult to check if the first line fits in 80 > columns. On one hand, you're not sure $NAME (or @var{NAME}) is going to be substituted by a four-letter highlighted NAME (the user could make help-arg-highlighting-function to do something weird). I admit this is not likely. On the other hand, we could "fix" filling for emacs-lisp docstrings so it recognizes @var{NAME} and acts accordingly. Juanma