[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: new *Help* argument highlighting
From: |
Kenichi Handa |
Subject: |
Re: new *Help* argument highlighting |
Date: |
Wed, 12 May 2004 22:01:41 +0900 (JST) |
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) |
In article <address@hidden>, Juanma Barranquero <address@hidden> 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
address@hidden
- Re: new *Help* argument highlighting, (continued)
- Re: new *Help* argument highlighting, Juanma Barranquero, 2004/05/12
- Re: new *Help* argument highlighting, Miles Bader, 2004/05/12
- Re: new *Help* argument highlighting, Juanma Barranquero, 2004/05/12
- Re: new *Help* argument highlighting, Richard Stallman, 2004/05/13
- Re: new *Help* argument highlighting, David Kastrup, 2004/05/13
- Re: new *Help* argument highlighting, Richard Stallman, 2004/05/13
- Re: new *Help* argument highlighting, Kenichi Handa, 2004/05/12
- Re: new *Help* argument highlighting, Juanma Barranquero, 2004/05/12
- Re: new *Help* argument highlighting, Kenichi Handa, 2004/05/12
- Re: new *Help* argument highlighting, Juanma Barranquero, 2004/05/12
- Re: new *Help* argument highlighting,
Kenichi Handa <=
- Re: new *Help* argument highlighting, Juanma Barranquero, 2004/05/12
- Re: new *Help* argument highlighting, Miles Bader, 2004/05/12
- Re: new *Help* argument highlighting, Kim F. Storm, 2004/05/12
- Re: new *Help* argument highlighting, Miles Bader, 2004/05/12
- Re: new *Help* argument highlighting, Kenichi Handa, 2004/05/16
- Re: new *Help* argument highlighting, Miles Bader, 2004/05/16
- Re: new *Help* argument highlighting, Kenichi Handa, 2004/05/18
- Re: new *Help* argument highlighting, Kim F. Storm, 2004/05/17
- Re: new *Help* argument highlighting, Miles Bader, 2004/05/17
- fill docstring (Re: new *Help* argument highlighting), Kenichi Handa, 2004/05/12