emacs-devel
[Top][All Lists]
Advanced

[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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]