Re: new *Help* argument highlighting

[Juanma Barranquero <jmbarranquero@wke.es>]

On 09 May 2004 22:42:01 -0400
Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I know, but you were saying that there is some resistance against adding
> highlighting, and I think the resistance is more against colors.

Yes, I agree.

In this case, though, nobody's proposing to add color (except, perhaps,
a shade of gray, which could be understood as changing intensity).

> Well I find the highlighting attracts my eye to the arguments, but not to
> the text that surrounds it, whereas I don't care so much about the argument
> as I care about the text.
> 
> Basically, my reaction is "Hmm... the argument OVERLAY is used three times
> in the docstring; now, why should I care?".

I think it boils down to personal differences. My though is more like
"Ah, so OVERLAY is described here, here and... oh, here. Let's se what
does it say about it."

If we had very strict style requirements to writing docstrings, we could
put marking on an argument's description, so we would be able to
highlight (with whichever method is subtle enough) the doc's paragraph(s)
were the argument is described and used. You could then type 1, 2, 3...
on a *Help* buffer to switch highlighting between first, second, third
argument, etc. But nowadays a docstring is just a bunch of text that
satisfies a few loose guidelines: using args in uppercase, making the
first line stand-alone for apropos, etc. As it stands, there's not easy
way to show the Help information in a more useful make up.

                                                                Juanma