* bug#10451: 24.0.92; Bad cross reference in Info manual @ 2012-01-08 6:40 Drew Adams 2012-01-08 8:56 ` Eli Zaretskii 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2012-01-08 6:40 UTC (permalink / raw) To: 10451 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' ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 6:40 bug#10451: 24.0.92; Bad cross reference in Info manual Drew Adams @ 2012-01-08 8:56 ` Eli Zaretskii 2012-01-08 15:29 ` Drew Adams 2012-01-08 22:34 ` Richard Stallman 0 siblings, 2 replies; 10+ messages in thread From: Eli Zaretskii @ 2012-01-08 8:56 UTC (permalink / raw) To: Drew Adams; +Cc: 10451 > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 8:56 ` Eli Zaretskii @ 2012-01-08 15:29 ` Drew Adams 2012-01-08 18:12 ` Eli Zaretskii 2012-01-08 22:34 ` Richard Stallman 1 sibling, 1 reply; 10+ messages in thread From: Drew Adams @ 2012-01-08 15:29 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 10451 > > 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... ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 15:29 ` Drew Adams @ 2012-01-08 18:12 ` Eli Zaretskii 2012-01-08 18:56 ` Drew Adams 0 siblings, 1 reply; 10+ messages in thread From: Eli Zaretskii @ 2012-01-08 18:12 UTC (permalink / raw) To: Drew Adams; +Cc: 10451 > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 18:12 ` Eli Zaretskii @ 2012-01-08 18:56 ` Drew Adams 2012-01-08 19:06 ` Eli Zaretskii 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2012-01-08 18:56 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 10451 > > 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? ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 18:56 ` Drew Adams @ 2012-01-08 19:06 ` Eli Zaretskii 2012-01-08 19:19 ` Drew Adams 0 siblings, 1 reply; 10+ messages in thread From: Eli Zaretskii @ 2012-01-08 19:06 UTC (permalink / raw) To: Drew Adams; +Cc: 10451 > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 19:06 ` Eli Zaretskii @ 2012-01-08 19:19 ` Drew Adams 0 siblings, 0 replies; 10+ messages in thread From: Drew Adams @ 2012-01-08 19:19 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 10451 > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 8:56 ` Eli Zaretskii 2012-01-08 15:29 ` Drew Adams @ 2012-01-08 22:34 ` Richard Stallman 2013-02-08 21:09 ` Drew Adams 1 sibling, 1 reply; 10+ messages in thread From: Richard Stallman @ 2012-01-08 22:34 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 10451 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/ ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2012-01-08 22:34 ` Richard Stallman @ 2013-02-08 21:09 ` Drew Adams 2014-02-09 5:25 ` Lars Ingebrigtsen 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2013-02-08 21:09 UTC (permalink / raw) To: rms, 'Eli Zaretskii'; +Cc: 10451 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10451: 24.0.92; Bad cross reference in Info manual 2013-02-08 21:09 ` Drew Adams @ 2014-02-09 5:25 ` Lars Ingebrigtsen 0 siblings, 0 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2014-02-09 5:25 UTC (permalink / raw) To: Drew Adams; +Cc: 10451, rms "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/ ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2014-02-09 5:25 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2012-01-08 6:40 bug#10451: 24.0.92; Bad cross reference in Info manual Drew Adams 2012-01-08 8:56 ` Eli Zaretskii 2012-01-08 15:29 ` Drew Adams 2012-01-08 18:12 ` Eli Zaretskii 2012-01-08 18:56 ` Drew Adams 2012-01-08 19:06 ` Eli Zaretskii 2012-01-08 19:19 ` Drew Adams 2012-01-08 22:34 ` Richard Stallman 2013-02-08 21:09 ` Drew Adams 2014-02-09 5:25 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.