Subject: bug#10451: 24.0.92; Bad cross reference in Info manual

From: "Drew Adams" <[email-masked]>
Date: Sun, 8 Jan 2012 07:29:11 -0800

> > There are a few cross references such as this in the `Info' 
> > manual: "see Overview of Texinfo(texinfo)".  The Texinfo
> > manual is not included with
> > Emacs.  These links are thus broken.
> 
> We also have links to other manuals provided by other projects:...

In the `Info' manual?  Where many readers are new to Info?  In the section where
we introduce readers to the notion, appearance, and behavior of an external
link?

> There's nothing we can do about this;

Sure there is - what I suggested: point instead to a manual that is included
with Emacs - the Emacs manual, for instance.

The cross references I am referring to are *not* there to point you to info
about Texinfo.  They are there to show you what a cross ref to another manual
(a) looks like, and (b) acts like.

For (b), the `Info' text in fact tells you to follow the link and then come back
- something you are unlikely to be able to do with many Emacs installations:

 "Sometimes a cross reference (or a node) can lead to another file (in
  other words another "manual"), or, on occasion, even a file on a remote
  machine (although Info files distributed with Emacs or the stand-alone
  Info avoid using remote links).  Such a cross reference looks like
  this: *Note Overview of Texinfo: (texinfo)Top.  (After following this
  link, type `l' to get back to this node.)

Good luck following that link you are told to follow, in an MS Windows Emacs
release, at least.

> avoiding such links would make the manual less useful.

What is "such links"?  The point is that these demo links have the wrong
demo-link choice.  It is fine to say that we sometimes need to cross-ref another
manual - that's in fact the whole point of this section: to teach readers about
external cross-refs.  It is not fine to conclude that this link must point to
the Texinfo manual.

Please note that the links I am talking about are in node `Help Xref', not in
node `Expert Info'.  Sorry that wasn't clear.  In the latter node the point is
indeed to send expert users to the Texinfo manual, and they will indeed need to
go there for the info in question.  (And few `Info' manual readers will even
bother with section `Expert Info'.)

My point is about the text where we introduce users to external links.  Show
them a workable link, if possible.  Have them follow a workable link, if
possible.

The `Expert Info' section is not something that a reader new to Info (or even
most readers) needs to worry about.  Readers of that section are in a different
category, with different needs from the average reader of the `Info' manual.

> A reader does not _have_ to follow every hyperlink she sees, only
> those she is really interested in.  A reader who really is interested
> in the details of how Info files are generated, will need to install
> the Texinfo package which brings the manual with it.

You're missing the point.  The reader is _directed_, _invited_ to follow these
this-is-what-an-external-link-is-like links (in `Help Xref'), for tutorial
purposes.  Not for the reason of getting any info about Texinfo, but just to see
what an external like is like.  `Help Xref' is a demo/tutorial section.
 
> > While it is not absolutely necessary that the links actually work,
> > it would be far better if the manual used only links that work.
> > In this case, a different manual could be used - one that is
> > included with Emacs.
> 
> Are you suggesting to have some version of Texinfo manual as part of
> the Emacs package?

Certainly not.  I am suggesting what I said: let's try to cross-ref to a
different manual, in particular one that is included with Emacs.  The Emacs
manual, for instance.

> That sounds like a strange proposal: it would lead
> to massive duplication of effort or to excessive interdependencies
> between largely independent projects.  Cf. the (still on-going)
> discussion about "GnuTLS and W32".

At least you and I agree about something. ;-)

> What could be useful is to enhance info.el to give some indication
> that a given hyperlink points to a manual that is not available.

If that is easy to do, it sounds like a good suggestion to me.  It is unrelated
to this bug report, but I encourage you to file a separate enhancement request
for it.

> If this is what your report is about,

Clearly not.

> or if it could be satisfied by such a change,

Nope.  This report is about changing those couple of links in the Info manual
that are trying to teach readers about external links.  Point them not to the
Texinfo manual but to, for example, the Emacs manual.

> then I agree; otherwise I think we should close this report
> with no further action.

You wouldn't surprise me there.  GC Lars will no doubt sweep it up in his
nightly rounds...