Re: automatic anchors for definition commands.

[Luc Teirlinck <teirllm@dms.auburn.edu>]

   On the other hand, are those long lists of xref's with no explanation
   really all that useful?  I'm not sure.

I am not sure I understand.  Are you suggesting removing
`(elisp)Related Topics' and similar lists of references from the Elisp
manual?

The naming convention for such anchors should be chosen so that it is
_self_-explanatory.  This is particularly important for references to
such anchors from documentation strings.

   And as Eli says, sometimes reading from the beginning of the node
   is better.

In those cases I _do_ refer to the top of the node.  I do not
_automatically_ make anchor references because a function or variable
name is mentioned.  Of course, my decision to refer to the top of the
node is only relevant to the printed manual.  The standalone reader
overrides it and if Juri's new feature is implemented, Emacs Info will
override it too.  The only way to avoid that would be to make an
explicit anchor to the top of the node, which would seem pretty silly.

There are essentially three types of anchors:

1.  Refers to what essentially could be a separate section or subsection.

2.  Refers to a specific definition, with the surrounding node of the
    text being secondary.

3.  Refers to specific items in tables or particular examples.
    Surrounding text secondary or sometimes even unrelated.

Of the 4 pre-existing anchors and the 19 I have currently made, 19 are
of type (2), 3 refer to items in tables and 1 refers to a specific
example.  I encountered _one single_ 24th example (which I am still
thinking about) which is of type (1).  I might still recommend
splitting a section in that particular case.

The mapatoms example I gave is pretty typical of anchors of type (2).
The entire section `(elisp)Related Topics' consists of references to
definitions that are given in other chapters, but could quite as well
have been given in the functions chapter.  Instead of repeating the
definition, references are given.  The reader may want to follow these
references, but may not necessarily want to reread all these other
chapters, or not even the containing nodes.  There are other similar
sections.  I have not started to take care of _any_ of them.  If I
would, the number of anchors of type (2) would grow tremendously.

I believe there are only three conclusions to be made at the present
stage.  Either

(A) conclude that definitions stand out clearly enough anyway and
    _only_ make anchors of type (3), which ofen refer to unnamed
    pieces of text that do not stand out very clearly from the
    surrounding text (but could not possibly be made into separate
    nodes).

or make automatic anchors, either 

(B) only for definitions 

or 

(C) for all index entries.  If I remember well, Juri at one point
    suggested this and offered to implement an Emacs solution.  I
    guess such a solution would write _actual_ anchors in the .texi
    files.  Note that this would cover _both_ types (2) and (3) and
    make explicit anchors barely _ever_ necessary.

Sincerely,

Luc.