[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: doc string for face-attribute-relative-p doesn't help

From: Drew Adams
Subject: RE: doc string for face-attribute-relative-p doesn't help
Date: Mon, 26 Jun 2006 21:27:39 -0700

    > I agree, too, that each function's doc string need not try to explain
    > everything. If the doc defines the terms it uses (e.g. "underlying",
    > "relative") and explains them clearly, then that lessens the burden of
    > explanation for doc strings.

    I've always wondered if there should be more attempts to link from
    docstrings into the elisp manual.  It would reduce the burden
    of trying to make docstrings too all-encompassing.

    Consider, for instance, if there were automatically added "See
    (elisp)FUNCTION-NAME" and/or "See (elisp)faces" links at the bottom of
    _every_ face function's docstring.

    [I seem to recall that this was discussed in some manner before??
    Anybody remember?]

[I don't remember such a discussion. Perhaps you are thinking of my request
that we add a source-code link to the Customize section for an object (e.g.
a variable) - see subject line "Getting more info on a variable in Customize
buffers" from 2005/1/1.]

Wrt your suggestion for *Help*: I support the idea.

"See (elisp)<node name>" might not be clear to some users, and doesn't
really help. The link just needs to take you to the right manual node; it
need not be named after the node. It could simply say "More...", since
*Help* is already providing doc on the function (or variable, or...).

If the function or variable is discussed in both manuals, Emacs and Emacs
Lisp, then the links could be called "Emacs Manual" and "Emacs-Lisp manual".
Alternatively, we could just use "Emacs Manual" and "Emacs-Lisp manual"
always (not "More.."), whichever applied. Some objects are not discussed in
either manual, so they would have no manual link.

Together with a) the link to the source code on the object (e.g. function)
name itself, and b) the link to customize the object, users would have
everything on the object in one place.

reply via email to

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