From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kenichi Handa Newsgroups: gmane.emacs.devel Subject: Re: new *Help* argument highlighting Date: Wed, 12 May 2004 22:01:41 +0900 (JST) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200405121301.WAA11314@etlken.m17n.org> References: <20040512130729.FB5D.JMBARRANQUERO@wke.es> <200405121125.UAA11097@etlken.m17n.org> <20040512133037.FB60.JMBARRANQUERO@wke.es> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 (generated by SEMI 1.14.3 - "Ushinoya") Content-Type: text/plain; charset=US-ASCII X-Trace: sea.gmane.org 1084371689 13570 80.91.224.253 (12 May 2004 14:21:29 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 12 May 2004 14:21:29 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed May 12 16:21:01 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 1BNubV-0005WE-00 for ; Wed, 12 May 2004 16:21:01 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BNubV-0008HB-00 for ; Wed, 12 May 2004 16:21:01 +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 1BNuBI-0007Fw-RV for emacs-devel@quimby.gnus.org; Wed, 12 May 2004 09:53:56 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.34) id 1BNuBC-0007FE-KG for emacs-devel@gnu.org; Wed, 12 May 2004 09:53:50 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.34) id 1BNuAg-0007AV-2D for emacs-devel@gnu.org; Wed, 12 May 2004 09:53:49 -0400 Original-Received: from [192.47.44.130] (helo=tsukuba.m17n.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1BNtMo-0007Lh-Qg for emacs-devel@gnu.org; Wed, 12 May 2004 09:01:47 -0400 Original-Received: from fs.m17n.org (fs.m17n.org [192.47.44.2]) by tsukuba.m17n.org (8.11.6p2/8.11.6) with ESMTP id i4CD1fP15919; Wed, 12 May 2004 22:01:41 +0900 (JST) Original-Received: from etlken.m17n.org (etlken.m17n.org [192.47.44.125]) by fs.m17n.org (8.11.6p2/8.11.6) with ESMTP id i4CD1f926103; Wed, 12 May 2004 22:01:41 +0900 (JST) Original-Received: (from handa@localhost) by etlken.m17n.org (8.8.8+Sun/3.7W-2001040620) id WAA11314; Wed, 12 May 2004 22:01:41 +0900 (JST) Original-To: jmbarranquero@wke.es Sent-via: jmbarranquero@wke.es Sent-via: emacs-devel@gnu.org In-reply-to: <20040512133037.FB60.JMBARRANQUERO@wke.es> (message from Juanma Barranquero on Wed, 12 May 2004 13:47:07 +0200) User-Agent: SEMI/1.14.3 (Ushinoya) FLIM/1.14.2 (Yagi-Nishiguchi) APEL/10.2 Emacs/21.3 (sparc-sun-solaris2.6) MULE/5.0 (SAKAKI) 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:23246 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:23246 In article <20040512133037.FB60.JMBARRANQUERO@wke.es>, Juanma Barranquero writes: > 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. I see your point. The above discussion depends on that @var{NAME} much much rarely appears in a docstring than $NAME. But, with another grep ('\( \|^\)$[a-z-][a-z-]*\( \|$\)'), I found only this docstring contains $NAME that will be treated as an arg unless we prescan usage. ------------------------------------------------------------ copyright is an interactive autoloaded Lisp function in `copyright'. (copyright &optional STR ARG) Insert a copyright by $ORGANIZATION notice at cursor. ------------------------------------------------------------ We can change it to: Insert a copyright by `$ORGANIZATION' notice at cursor. Then we can use scan-doc-then-usage method even with $NAME convention. >> 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 Ah, I meant that I found none that results in mis-highlighting. >> 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. At least, $NAME convention is easier for keeping the first line in 80 column even without eliminating `$'s. > On the other hand, we could "fix" filling for emacs-lisp docstrings so > it recognizes @var{NAME} and acts accordingly. What do you mean? The first `sentence' should never be broken into multiple lines. So only the meaningful "fix" for fill is to make it recognize the emacs-lisp docstrings and keep the first line untouched. --- Ken'ichi HANDA handa@m17n.org