automatic anchors for definition commands.

[Luc Teirlinck]

I now have made 22 anchors in the Elisp manual in addition to the four
that were already there.  This seems about the time to start thinking
about whether I should continue to do things exactly like I have been
busy doing, or whether at least _some_ things could be done more
automatically and systematically.

A larger and larger percentage of these anchors is starting to refer
to function and variable definitions.  There are _many_ nodes (or
parts of nodes), say `(elisp)Related Topics', section 12.11 in the
printed manual, that are index-like lists of references to function
and variable definitions.  Unlike the "real" indices, they do not
refer to the page numbers _of the definitions_ in the printed manual.
(They refer to the beginning of the section, which can be several
pages off.)  I have not yet started to make @anchors for these types
of nodes.  If I do, then I believe that a _very large_ percentage of
function and variable definitions in the Elisp manual would have @anchors.

Take the reference to `mapatoms' in `(elisp)Related Topics' as an
example.  The definition of `mapatoms' is on line 143 of Info node
`(elisp)Creating Symbols' and (using the CVS version of texinfo.tex),
on page 114 of the printed manual.  The current reference in 12.11
refers to page 111, the beginning of the section, three pages off.  (I
am sure this is by no means a record, I did definitely not search for
the worst example).  The index gets page 114 correct.
 
So would it not be possible to make "automatic anchors" for the
definition commands, that is to have _some_ special semantics for the
arguments (probably for the first argument) of @xref and friends that
would refer to the definition commands (using Ref:'s in the .info
files) and get the page number right in printed output?  I have been
using "Definition of VAR" as first argument, which might not be too
good as a general automatic semantic, since one symbol can have
several definitions and since it could conflict with a node name.
What about something like "defun of mapatoms" or "defvr of myvr" as
special first argument?  These are unlikely to conflict with
nodenames.  Anyway, if we decide that automatic anchors for definition
commands are a good and feasible idea, then we could start thinking
about the best naming convention.

I have trouble with Juri's Emacs Info emulation of anchors for two
reasons:

1.  It only applies to Emacs Info, not to the printed manual.

2.  It is not necessarily the place intended by the author.  It is a
    guess.  So is the current standalone equivalent feature.

But a makeinfo-texi2dvi solution could take care of both objections.

Sincerely,

Luc.