automatic anchors for definition commands.

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.

Re: automatic anchors for definition commands.

[Eli Zaretskii]

> Date: Tue, 6 Jan 2004 20:50:19 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> 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.)

Note that in some case, this might be actually a good idea: reading
from the section beginning might give you a broader perspective on the
subject.

I don't have a firm opinion on the automatic anchoring you suggest; at
first glance, it sounds like a lot of work for a relatively small
benefit.

Re: automatic anchors for definition commands.

[Karl Berry]

Like Eli, I'm not entirely sure what I think of the proposal.  I
recognize the annoyance factor in adding anchors.

On the one hand, the @def commands already generate automatic index
entries, so it doesn't seem too unreasonable to generate automatic
anchors as well.

Your initial thought of "defcmd of identifier" for the naming convention
doesn't seem too bad to me.  At least, I can't immediately think of
anything I like better.


On the other hand, are those long lists of xref's with no explanation
really all that useful?  I'm not sure.  And as Eli says, sometimes
reading from the beginning of the node is better.

Hmm.

Re: automatic anchors for definition commands.

[Luc Teirlinck]

   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.

Re: automatic anchors for definition commands.

[Karl Berry]

    (C) for all index entries.

I don't think we should make implicit anchors for all index entries, and
don't really care to go into that discussion again.

However, I'm now somewhat convinced that adding implicit anchors for
definition commands, as we add index entries now, would be reasonable.

Did you have any further thoughts on a naming convention?

Re: automatic anchors for definition commands.

[Luc Teirlinck]

Karl Berry wrote:

   Did you have any further thoughts on a naming convention?

Maybe "defcmd of identifier" would be good.  It might at first seem
cryptic to people who do not know Texinfo, but one would quickly get
used to it.  "Function (or Variable, or Type) Definition of
identifier" would be less cryptic, but is longer.

Sincerely,

Luc.

Re: automatic anchors for definition commands.

[Richard Stallman]

    However, I'm now somewhat convinced that adding implicit anchors for
    definition commands, as we add index entries now, would be reasonable.

This would mean a tremendous increase in the number of names defined
for cross-referencing.  That could cause a slowdown in TeX, or even
cause TeX to run out of memory.  I think we should not do this.

    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

I prefer (D): continue handling this the way we do it now.

Re: automatic anchors for definition commands.

[Eli Zaretskii]

> Date: Wed, 7 Jan 2004 18:01:59 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    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.

The point is, the author of the manual does not always know what's
best; it depends on the reader.

> 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.

I think such cases are relatively rare, even in the Emacs manuals,
where we use that to keep the sheer size of the manuals at bay.  It's
not clear to me whether we should draw too general conclusions from
these cases.  Again, this my opinion is not very strong.

Re: automatic anchors for definition commands.

[Karl Berry]

    This would mean a tremendous increase in the number of names defined
    for cross-referencing.  That could cause a slowdown in TeX, or even
    cause TeX to run out of memory.  

A test with 2000 randomly-generated @anchors (the Elisp manual has about
1800 @def... cmds) ran fine, both for speed and space.

However, 5000 anchors overflows the string space in last year's TeX Live
distribution.  (This year's has bigger maximums, as do a few other
distributions I tried.)  None of the other various TeX capacities are a
problem, and speed isn't a problem either.

I think I could play with texinfo.tex and eliminate perhaps 1/3 of the
string space in common cases (by getting rid of empty -snt xrdef
values), if we want to pursue it.

Re: automatic anchors for definition commands.

[Richard Stallman]

    A test with 2000 randomly-generated @anchors (the Elisp manual has about
    1800 @def... cmds) ran fine, both for speed and space.

    However, 5000 anchors overflows the string space in last year's TeX Live
    distribution.  (This year's has bigger maximums, as do a few other
    distributions I tried.)  None of the other various TeX capacities are a
    problem, and speed isn't a problem either.

It might be ok...but still, is this change really necessary?
It is not hard to define teh anchors we actually want to use.

Re: automatic anchors for definition commands.

[Luc Teirlinck]

Richard Stallman wrote:

   I prefer (D): continue handling this the way we do it now.

That means using essentially no anchors.  Prior to me making
additional anchors, there were a total of six anchors in all .texi
files included with the Emacs contribution: 4 in the Elisp manual, one
in the Emacs manual and one in gnus.texi.  (Result of grepping.)
I have currently made 20 anchors and if I keep doing what I am doing
now, that is about to explode into the hundreds.

   It is not hard to define teh anchors we actually want to use.

There is a difference between what is hard if one makes two or three
anchors and what is hard if one makes hundreds of anchors

   It might be ok...but still, is this change really necessary?

The conclusion is not _necessarily_ that one should make automatic
anchors for all definition commands.  The conclusion may be to
essentially make _no_ anchors to definition commands, maybe unless
they are referred to from docstrings.  That would reduce the number of
new anchors to be made by _well_ over ninety percent,

I am not convinced By Eli's reasons for not making anchors to
definition commands.  Essentially the reasons for that are empirical.
I have twenty concrete examples in mind and Eli's arguments do not
apply to them.  However, to me. a more relevant argument, is the one I
already mentioned before: definition commands are easy to find,
because they stand out clearly, _especially_ in the printed manual.
On the other hand, if you refer to the beginning of a paragraph that
looks like all other paragraphs, providing the reader with the _exact_
page number in the printed manual and the exact spot in Info becomes
more important.

So maybe that is what I will start to do: not just see how many lines
down the node the reference is in Info or how many pages off it is in
the printed manual, but how difficult to actually _find_ it really is.
That difference appears to be more important in the printed manual
than in Info.

If that is what we decide to do, then there is obviously no need for
automatic anchors for definition commands.  I would probably not
revert most anchors to definition commands I already made, although I
might revert some, because they might look just _too_ inconsistent
with other similar cases.

Sincerely,

Luc.

Re: automatic anchors for definition commands.

[Richard Stallman]

    That means using essentially no anchors.

No, it means we make one when we want one.
As you've discovered, it is not hard to make an anchor.
Any time you think the manual will be better
if we use an anchor, please do!  Don't feel
reluctant to add any anchors you find useful.