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

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

[Drew Adams]

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.
 
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.
 
I realize that the Info manual is not only for Emacs.  Still, many
readers will read it in Emacs, and this is borne out by some of the
manual text that says things like "If you are reading this in Emacs...".
 
It is likely that at least as many readers of the Info manual will have
the Emacs manual (and perhaps some other manuals that are provided with
Emacs) as will have the Texinfo manual installed.  And most Info users
will never be creating Info files and thus using Texinfo.
 

In GNU Emacs 24.0.92.1 (i386-mingw-nt5.1.2600) of 2012-01-05 on MARVIN
 Windowing system distributor `Microsoft Corp.', version 5.1.2600
 configured using `configure --with-gcc (4.6) --no-opt --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include --ldflags
 -LD:/devel/emacs/libs/gnutls-3.0.9/lib'
 

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 7 Jan 2012 22:40:25 -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: Make,
glibc, and Aspell, for example.  Manuals of other GNU projects do the
same; e.g. the Texinfo manuals include references to Emacs.  There's
nothing we can do about this; avoiding such links would make the
manual less useful.

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 can have it too, a Windows port is available.  Drop me a note if
you want a URL.)

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

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
this is what your report is about, or if it could be satisfied by such
a change, then I agree; otherwise I think we should close this report
with no further action.

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

[Drew Adams]

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

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <10451@debbugs.gnu.org>
> Date: Sun, 8 Jan 2012 07:29:11 -0800
> 
> 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.

We try to do that, but it's not always possible.

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

AFAIK, Texinfo cross-references are not explained in the Emacs
manual.  The real cross-reference to Texinfo, a few sentences below,
needs to go there.  Pointing it to another manual would do a
disservice to the reader.

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

[Drew Adams]

> > 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.
> 
> AFAIK, Texinfo cross-references are not explained in the Emacs
> manual.  The real cross-reference to Texinfo, a few sentences below,
> needs to go there.  Pointing it to another manual would do a
> disservice to the reader.

That is completely wrong.  That "real cross-reference to Texinfo, a few
sentences below" does **not at all** need to be a reference to Texinfo.  It is
simply an example of a cross ref to another manual - nothing more.

The purpose of that cross ref in this node, like the overall purpose of the
node, is to introduce cross references and demo following them.  The user is not
expected here to follow a link to another manual to learn about that manual's
subject matter, but simply to go there and come back, to see what following a
cross ref link is like.

This is that "real cross-reference to Texinfo", which you mention:

"However, Emacs normally hides some other text in cross-references.
 If you put your mouse over the cross reference, then the information
 appearing in a separate box (tool tip) or in the echo area will show
 the full cross-reference including the file name and the node name of
 the cross reference.  If you have a mouse, just leave it over the cross
 reference *Note Overview of Texinfo: (texinfo)Top, and watch what
 happens."

There is nothing special about referring to the Texinfo manual here.  Both this
cross ref and the one in the paragraph before it (see below) could just as well
be changed to a cross ref to another manual - a manual that is more likely to be
present in Emacs.  The Emacs manual is an obvious choice.

Of course, the text needs to be modified to replace "the name `texinfo'" by "the
name `emacs'", in addition to replacing the cross ref by a cross ref to the
Emacs manual:

"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 The Emacs Editor: (emacs)Top.  (After following this
 link, type `l' to get back to this node.)  Here the name `emacs'
 between parentheses refers to the file name.  This file name appears in
 cross references and node names if it differs from the current file, so
 you can always know that you are going to be switching to another
 manual and which one."

Is this really so hard for you to see?

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <10451@debbugs.gnu.org>
> Date: Sun, 8 Jan 2012 10:56:54 -0800
> 
> This is that "real cross-reference to Texinfo", which you mention:
> 
> "However, Emacs normally hides some other text in cross-references.
>  If you put your mouse over the cross reference, then the information
>  appearing in a separate box (tool tip) or in the echo area will show
>  the full cross-reference including the file name and the node name of
>  the cross reference.  If you have a mouse, just leave it over the cross
>  reference *Note Overview of Texinfo: (texinfo)Top, and watch what
>  happens."

This is not the one I had in mind.  If you are talking about this one,
then there's another problem: this manual also comes with the Texinfo
package.  If that reference is changed to point to the Emacs manual,
it will be broken for someone who installs the Texinfo manual and
doesn't have the Emacs manual installed.

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

[Drew Adams]

> This is not the one I had in mind.

It's the one I pretty clearly cited:

>> Please note that the links I am talking about are in node 
>> `Help Xref', not in node `Expert Info'.

And in the same mail I quoted the same text from node `Help Xref' (twice now).

> If you are talking about this one,

Yes, I am talking about node `Help Xref'.

> then there's another problem: this manual also comes with the Texinfo
> package.  If that reference is changed to point to the Emacs manual,
> it will be broken for someone who installs the Texinfo manual and
> doesn't have the Emacs manual installed.

I addressed that in the original bug report:

>> I realize that the Info manual is not only for Emacs.  Still, many
>> readers will read it in Emacs, and this is borne out by some of the
>> manual text that says things like "If you are reading this in Emacs...".
>>  
>> It is likely that at least as many readers of the Info manual will have
>> the Emacs manual (and perhaps some other manuals that are provided with
>> Emacs) as will have the Texinfo manual installed.  And most Info users
>> will never be creating Info files and thus using Texinfo.

And no, it is not true that "this [Info] manual also comes with the Texinfo
package".  That might be true sometimes, but it is not true in general.

That's the point.  If the `Info' manual always came with the `Texinfo' manual
then I would not have filed this bug report - the links would just work.  Please
read what I wrote.

For an Emacs distribution (this is an _Emacs_ bug report), it is not always the
case that Emacs is distributed with Texinfo (and rightly so, IMHO).

If you can find a way to make the text be such that it works for Info with
Texinfo (and perhaps without Emacs) as well as working for Info with Emacs but
without Texinfo, fine.  Barring that, let's please fix this for Emacs users -
people who will read Info within Emacs, and who will not necessarily also have
the Texinfo manual installed.

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

[Richard Stallman]

    We also have links to other manuals provided by other projects: Make,
    glibc, and Aspell, for example.  Manuals of other GNU projects do the
    same; e.g. the Texinfo manuals include references to Emacs.  There's
    nothing we can do about this; avoiding such links would make the
    manual less useful.

We might be able to improve what happens when you follow a link to a
manual that is not installed.  At least on GNU/Linux.  Maybe the
attempt to follow that link could cause the pertinent package to get
installed.


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use free telephony http://directory.fsf.org/category/tel/

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

[Drew Adams]

I've reopened this bug.  It was closed with no explanation, and the bug is still
there.

This is about _Emacs_ users who are reading the Info manual, which is an
introduction to using Info to read manuals.

The text tries to teach you about links to other manuals, and tells you to
follow the given cross-book link.  That link is broken, because it links to a
manual that is not even included with Emacs.  We are sending readers down the
garden path, confusing them and making them wonder whether they might be doing
something wrong.

Such instructions (essentially tutorial text) should just plain work.

> people who will read Info within Emacs, and who will not
> necessarily also have the Texinfo manual installed.

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

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> I've reopened this bug.  It was closed with no explanation, and the bug is still
> there.
>
> This is about _Emacs_ users who are reading the Info manual, which is an
> introduction to using Info to read manuals.
>
> The text tries to teach you about links to other manuals, and tells you to
> follow the given cross-book link.  That link is broken, because it links to a
> manual that is not even included with Emacs.  We are sending readers down the
> garden path, confusing them and making them wonder whether they might be doing
> something wrong.
>
> Such instructions (essentially tutorial text) should just plain work.

When you hit that link "Info file texinfo does not exist", which I think
is a clear enough signal to the user that they might consider installing
the relevant info file.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/