Re: Display of cross references to other manuals

[Luc Teirlinck]

Eli Zaretskii wrote:

   If you understand it differently, please explain what is so wrong
   with "See Overview".  Why is it important for the user to realize
   that it points to a different manual?  Why cannot we think about all
   the manuals as a single logical document, for that matter?

Because they are not.  Different manuals cover different topics, are
aimed at other audiences, have different levels of sophistication, are
written by different people and so on.

If I just come to read the Emacs manual and now I am reading the Elisp
manual, then the fact that a reference points to the Emacs manual
tells me that I do not have to follow the reference, unless I forgot,
because I already know the stuff.

   In other words, an xref like

     @xref{Syntax Tables,,Syntax Tables,elisp,The Emacs Lisp Reference Manual}

   we are forced say both "elisp" in the 4th argument and "The Emacs
   Lisp Reference Manual" in the 5th, although both of them say that
   another manual is being referenced.

Of course, because the Info file's name and the printed manual's name
can be different.  That is not duplicate information.  Systematically
mentioning them in any other argument would be duplicate information.

   FWIW, to me, "Overview(cl)" looks like a typo.  It certainly does not
   spell out that a different manual is referenced, unless I happen to
   know that there's an Info file called `cl' on my system.

We would mention it in info.texi, but people would quickly be able to
guess even without trying out the tutorial.  Anyway, if we would set
Info-hide-note-references to nil by default (which I am very much in
favor of), this is a moot point, because then the file name is mentioned
as part of the node name.

   "Overview (in the `cl' manual)" would be better, if we are pursuing
   this class of solutions.  Putting the 5th arg of @xref in the parens,
   prefixed with "in ", would be even better, but it will probably
   disrupt the line filling too much, as names of manuals tend to be
   longish.

Those are the kind of things I would expect from, say, an XML based
Info reader.  Trying to do it right now seems to me to be a variation
on Info-hide-note-references and would probably run in exactly the
same problems.  (Unless it were taken care of at the makeinfo level,
which would allow, for instance, to fill correctly, as would the XML
solution.)  If we decide to keep Info-hide-note-references t by
default, one could actually go for the `(in the `cl' manual)'
solution, since the problems are already there anyway, but I guess
that would lead to using the display property for editing purposes
again, which is even more confusing to the user than the invisibility
property.

   Maybe we should just turn this feature off by default.  It has already
   generated lots of discussions and controversy, which is a clear sign
   of something that quite a few users will dislike.  We shouldn't make
   such features be on by default, I think.

Personally, I agree completely with this.  Let us see what Richard
says.

Sincerely,

Luc.