Re: The minibuffer vs. Dialog Boxes (Re: Making XEmacs be more up-to-date)

[Simon Josefsson]

On Mon, 22 Apr 2002, Per Abrahamsen wrote:

> Simon Josefsson <address@hidden> writes:
> 
> > Making all code that displays or parse docstrings somehow support
> > :link as well isn't the best approach.
> 
> How much code is that, apart from describe-variable and
> customize-variable (which should be one)?

I wasn't objecting to changing the code based on the amount of code (which
I'm sure is quite small) but because it means people handling docstrings
need to have a mental model that not all documentation for a symbol is
stored in the docstring, and that they may need to look elsewhere as well
to get the complete picture.  If all documentation (including references)
is stored within the docstring, people handling docstrings will get all of
the documentation without having to know or care about this at all.

In any case, I think we agree that the real problem is to get lisp
programmers to start to add references and having them end up as visible
to the user.  The way it is implemented isn't interesting or important
(but that hasn't stopped me from having an opinion before ;-)).

Suggestion: Add something to the Lisp manual on how to write
docstrings that have references when defining symbols.  I haven't seen the 
"See Info node" magic explained anywhere.