Re: tags for functions

[Ted Zlatanov <tzz@lifelogs.com>]

On Fri, 30 Jan 2009 08:06:42 -0800 "Drew Adams" <drew.adams@oracle.com> wrote: 

DA> 1. When the thing documented in *Help* is also in the manual, then we have a
DA> link to the manual from the *Help* buffer.

DA> 2. The manual should have such a `See also' cross reference, if any place
DA> should.

Agreed on both counts.  The API I'm providing can be combined with the
manual generation to do this, and it will use the manual sections to get
the first keyword seeds.  I don't want the manual to be the primary
source of keywords, that's all.

DA> 3. When both the thing doc'd in *Help* and the thing xref'd are in the manual,
DA> #1 and #2 would take care of such cross-referencing. Admittedly, passing through
DA> the manual represents an indirection, but typically a fruitful one.

DA> Dunno if it's worth adding this for cases that are not covered by the manual. It
DA> sounds like a helpful feature. I can't speak to the implementation cost. (There
DA> is also a doc-maintenance cost to consider.)

There are many many packages and functions not covered in the manual
that are nevertheless used and useful.  They can and should have
keywords.  So the docstring should be the primary source of keywords,
and looking up the function with C-h f should be the primary way to
cross-reference functions by keyword.

The goal of this API is not to index Emacs' internal functions'
keywords.  It will cover everything that `mapatoms' returns; I'm
considering symbols in addition to functions but I want to get functions
working first.

Ted