bug#5809: 23.1.94; cross-reference by anchor yields in accurate position

["Drew Adams" <drew.adams@oracle.com>]

> > > Keep in mind too that in some documentation systems, which 
> > > don't even have the fine-grained "node" size of Info (on
> > > average), cross references generally do not
> > > take you to an exact destination position. They just get 
> > > you to the appropriate section.
> > 
> > That Info does support this feature is one of its advantages, and we
> > should not lose it, IMO.  Without it, reading a large manual as a
> > reference is a PITA.
> > 
> > Besides, it simply feels as a bug (and actually is): you 
> > are placed in the middle of a sentence that, more often
> > than not, has nothing to do with the subject you are after.
> 
> I think everyone agrees that it is a desirable feature. If we 
> can have both exact cursor destination and breadcrumbs, that
> will be ideal. Both are useful features.
> 
> It is somewhat disorienting to not have point land only 
> nearby and not at exactly the right spot. And it is
> disorienting to not immediately see where you
> are in the document hierarchy (beyond just immediate up, 
> next, and prev nodes).
> 
> We should aim to get both working properly together.

Also, *in practice* this is a *rare* problem. You are making a mountain out of a
mole hill.

I wonder if people discussing this have actually tried following many links in
the manuals. Most of the discussion has been about how to implement a solution
and not about the problem. Think about the user and actual use, not just about
implementation.

Follow the actual cross references in the Emacs and Elisp manuals, and you will
see that there are only a very *small* number of them that do not simply point
to the beginning of a node. And only those small number are the potential
candidates for target imprecision.

And even in a reference manual such as Elisp, where you might expect many cross
references to specific function and variable descriptions that occur in the
middle of a node, there are relatively few such mid-node cross references.

The one exception: index links to specific keys, functions, variables, and keys.
They do target precise mid-node positions.

But in fact only a small minority of even those exceptional cases do not act as
well as one might hope. Following the link places you quite near the precise
location and generally at a location that can still be considered the intended
target (e.g. within the correct, targeted 1-3 line description or paragraph).

Why would that be? Because (a) most breadcrumbs are short and (b) most function,
variable, and key descriptions are more than one line long. So being off by the
length of one or more breadcrumbs still takes you to the right description.

Again, try it and see for yourself. Follow a representative sample of links of
your choice, and see what proportion are in fact problematic. I'm sure you'll
find that it is *very* small.

So in practice this is not a real problem. There are many more important UI
difficulties and annoyances that could be addressed before trying to achieve
perfection here.

Again, if you can find a clean, simple way to make *everything* work well, so
much the better, obviously. But we should not make the perfect into the enemy of
the good - do not throw out the baby with the bathwater.

Don't let your enthusiasm for trying some new UI technique (`after-string',
`cursor' properties, multi-line headers etc.) carry you away - creating a
sledgehammer to kill a fly. Think about where you're going with the
implementation vs what you're really trying accomplish. What's the problem and
how bad is it in practice?

In truth, Eli's dramatic characterization of this problem as "a PITA" and

  you are placed in the middle of a sentence that,
  more often than not, has nothing to do with the
  subject you are after.

is quite overblown and inaccurate. It is simply not the case, except in rare
cases.

More often than not - in fact in the overwhelming majority of cases - you are
NOT placed in the middle of a sentence that has nothing to do with the subject
you are after. That's a fact, AFAICT.

Try it, instead of just treating this academically. Follow real links and you
will soon see what I mean. You are taken directly to the precise info you need
in 99.9% of the cases (no, I didn't count - but try it and make your own
estimate).