Re: new *Help* argument highlighting

[Juanma Barranquero <jmbarranquero@wke.es>]

On Wed, 12 May 2004 20:25:38 +0900 (JST)
Kenichi Handa <handa@m17n.org> 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