[Top][All Lists]

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

Undocumented hyperlinks in doc strings.

From: Luc Teirlinck
Subject: Undocumented hyperlinks in doc strings.
Date: Wed, 8 Oct 2003 19:50:18 -0500 (CDT)

Why does `default' get a hyperlink in the documentation string of
`fringe-mode'?  Is this a bug or a "feature"? `default' is not defined
as a variable nor as a function, nor is it preceded by `info node' or
`Info node', hence it is not covered by the list of possibilities
described in (elisp)Documentation Tips.  It is extremely important
that this list be completely exhaustive and accurate if we want
package authors to write good documentation strings.

If the reason would be that `default' is a face, then apart from the
lack of documentation (which could easily be fixed), I would also have
the less easily fixed objection that faces just tend to have extremely
common names such as `default', `mouse', `menu', `region', `button'
`border', `fringe', `bold', and countless equally common ones, that
are used for tons of other purposes.  Systematically having to write
`symbol' in front of them would be a lot more of a nuisance than for
variables or functions, simply because the situation occurs so much
more frequently.

"Fake" hyperlinks like the one for `default' in the documentation
string below are distracting and confusing.  It misleadingly suggests
that if you follow it, you will get more information about what the
value `default' means.  Instead you get to stare at completely
unrelated face documentation.

(defun fringe-mode (&optional mode)
  "Toggle appearance of fringes on all frames.
Valid values for MODE include `none', `default', `left-only',
`right-only', `minimal' and `half'.  MODE can also be a cons cell
where the integer in car will be used as left fringe width and the
integer in cdr will be used as right fringe width. If MODE is not
specified, the user is queried.
It applies to all frames that exist and frames to be created in the
If you want to set appearance of fringes on the selected frame only,
see `set-fringe-style'."



reply via email to

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