inforef

inforef

[Luc Teirlinck]

The documentation of @inforef in `(texinfo)inforef' is somewhat
unclear.  I personally interpret it as meaning that @inforef is meant
to be used when no _published_ manual is available, even though the
user can produce printed output himself using texi2dvi.  Others
interpret it as meaning that no printed output can be produced
because, for instance, the info file was not produced from Texinfo
source.

(texinfo)inforef' itself uses info.texi as an example, which is, of
course, Texinfo source and for which a printed manual can be printed
out by the user.  In the HTML output, @inforef produces a hyperlink to
an HTML manual, which could not be produced (or so I believe) if the
Info file was not produced from Texinfo source.  I believe that this
supports my interpretation of @inforef as applying to situations where
no published manual is available.  But could you please clarify this?

Sincerely,

Luc.

Re: inforef

[Eli Zaretskii]

> Date: Mon, 13 Dec 2004 21:45:58 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: Dave Love <fx@gnu.org>, emacs-devel@gnu.org
> 
> The documentation of @inforef in `(texinfo)inforef' is somewhat
> unclear.  I personally interpret it as meaning that @inforef is meant
> to be used when no _published_ manual is available, even though the
> user can produce printed output himself using texi2dvi.  Others
> interpret it as meaning that no printed output can be produced
> because, for instance, the info file was not produced from Texinfo
> source.

It's neither of these two, actually.  @inforef exists for those
situations where you, for some reason, want to point to the Info
manual even in the printed version of the manual.  For example, it's
possible that only an Info version contains some text that you want to
point to (e.g., text that was in @ifinfo..@end ifinfo in the manual to
which you point.

So the documentation of @inforef does not need to be as clear-cut as
you are asking for, because the circumstances of its use can vary.

Re: inforef

[Dave Love]

"Eli Zaretskii" <eliz@gnu.org> writes:

> It's neither of these two, actually.  @inforef exists for those
> situations where you, for some reason, want to point to the Info
> manual even in the printed version of the manual.

Then I think the Texinfo manual should be fixed to say so.

Re: inforef

[Karl Berry]

    I personally interpret it as meaning that @inforef is meant
    to be used when no _published_ manual is available, even though the
    user can produce printed output himself using texi2dvi.  

I don't think this was ever the intent.  Whether a manual was ever
published, i.e., available in a bookstore somewhere, seems unimportant
to me as far as cross references go.

    Others interpret it as meaning that no printed output can be
    produced because, for instance, the info file was not produced from
    Texinfo source.

That was its original purpose.  Eli's example of citing conditional text
is another good possibility.

    (texinfo)inforef' itself uses info.texi as an example, 

Originally, the Info manual was written directly in Info, and no Texinfo
source existed.  I expect that's where the example (and perhaps the
command) came from.

    In the HTML output, @inforef produces a hyperlink to an HTML manual,
    which could not be produced (or so I believe) if the
    Info file was not produced from Texinfo source.  

There's no particular reason why an HTML file could not be produced by
other means.

I agree that it's not completely logical for the HTML output to have a
link for @inforef, but it could be useful, and it's been that way since
the HTML support was written, so I'm loath to change it now.

    But could you please clarify this?

I fiddled with the inforef node in texinfo.txi to try to explain a
little better.

Thanks,
karl

Re: inforef

[Luc Teirlinck]

Karl Berry wrote:

   I don't think this was ever the intent.  Whether a manual was ever
   published, i.e., available in a bookstore somewhere, seems unimportant
   to me as far as cross references go.

Except that a reference is useless if you give the user no indication
whatsoever on how to find that reference.

The reason Info files refer to Info files and HTML files to HTML
files, is that clicking on a link leads you to a file of that type, so
they are (if present) the most easily accessible forms of the file.
The problem with hardcopy is that you can not click on a link to
produce the printed manual referred to.

Consider a beginning user reading the published version of the Emacs
manual and seeing a reference to the "Emacs MIME Manual".  How is that
user to know that this refers to a .texi file to be found and printed
off by the user himself?  There is not the slightest indication of
that.  The Emacs manual explains how to read Info files using `C-h i',
but is silent about .texi files, where to find them and how to print
them off.  It never mentions texi2dvi.  The fact that the user has
access to the .info files does not even imply that he has access to
the .texi files.  So that user might first look at the last page to
see whether he can order the manual from the FSF, but it is not on
there.  His local bookstore can not help him either.  Thus, an
@inforef seems much less confusing and much more helpful to the user.

In as far as the example we started from (in the emacs-devel thread
leading up to this one), url.texi, I have no problem whatsoever
replacing the @inforef with an @xref.  There is no "published" version
of the URL manual, so the person who got the printed version either
knows himself how to find .texi files and print them off, or got them
from somebody who knows and could explain it to him.  The situation is
not as simple for the @inforef's in the Emacs manual.

Sincerely,

Luc.

Re: inforef

[Eli Zaretskii]

> Date: Tue, 14 Dec 2004 23:15:00 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: fx@gnu.org, bug-texinfo@gnu.org, emacs-devel@gnu.org
> 
> Except that a reference is useless if you give the user no indication
> whatsoever on how to find that reference.

The assumption is that a user who prints a manual likes his/her
manuals in print, so he/she probably prints them all.

Alternatively, he/she can grep for the manual's title (under
@titlepage), if the Texinfo sources are available, or simply guess
that the Info file `emacs-mime' might be the manual whose title is
"Emacs MIME Manual".

> The problem with hardcopy is that you can not click on a link to
> produce the printed manual referred to.

Well, we cannot help that, can we?  Referring to an Info manual won't
help, as a user who holds a printed manual might have no idea how to
get hold of Info manuals, or can even be far away of any computer.

Yes, the situation isn't perfect, but it's been like that for eons,
and as far as I can remember, you are the first one to complain.

> I have no problem whatsoever replacing the @inforef with an @xref.

Yes, please do.  That is how GNU documentation is written since about
forever.  I see no reason to change that now.


_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
bug-texinfo@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-texinfo

Re: inforef

[Dave Love]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> The problem with hardcopy is that you can not click on a link to
> produce the printed manual referred to.

Regardless, TeX output from Texinfo may not be destined for hardcopy,
and DVI and PDF viewers support hyperlinks.  texi2pdf yields external
links to URLs or other PDF files.  (That's not just a theoretical or
recent possibility -- I was using it for online doc probably before
HTML had escaped from CERN.)

> Consider a beginning user reading the published version of the Emacs
> manual and seeing a reference to the "Emacs MIME Manual".  How is that
> user to know that this refers to a .texi file to be found and printed
> off by the user himself?  There is not the slightest indication of
> that.

If that's a significant problem you could, for instance, explain it in
the introduction, make a texinfo.tex option for setting an alternative
Info reference as a footnote/endnote.  I'd guess that would only be
relevant when actually producing copy for publication.

Re: inforef

[Luc Teirlinck]

Karl Berry wrote:

   > Consider a beginning user reading the published version of the Emacs
   > manual and seeing a reference to the "Emacs MIME Manual".  How is that
   > user to know that this refers to a .texi file to be found and printed
   > off by the user himself?  There is not the slightest indication of
   > that.

   If that's a significant problem you could, for instance, explain it in
   the introduction, make a texinfo.tex option for setting an alternative
   Info reference as a footnote/endnote.  I'd guess that would only be
   relevant when actually producing copy for publication.

I believe that it would at the very least be relevant when producing
copy for publication of the Emacs manual and maybe some other GNU
manuals.  Obviously, it would not be necessary for the Texinfo manual,
since that one explains the stuff anyway.

Sincerely,

Luc.



_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
bug-texinfo@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-texinfo

Re: inforef

[Luc Teirlinck]

>From my previous message:

   Karl Berry wrote:

Sorry, I managed to misquote somebody again.

I meant:

Dave Love wrote:

   If that's a significant problem you could, for instance, explain it in
   the introduction, make a texinfo.tex option for setting an alternative
   Info reference as a footnote/endnote.  I'd guess that would only be
   relevant when actually producing copy for publication.


Sincerely,

Luc.


_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
bug-texinfo@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-texinfo

Re: inforef

[Dave Love]

karl@freefriends.org (Karl Berry) writes:

> I agree that it's not completely logical for the HTML output to have a
> link for @inforef, but it could be useful, and it's been that way since
> the HTML support was written, so I'm loath to change it now.

For what it's worth, in case that means my original support, it would
definitely be a bug but may well not be worth worrying about.  I guess
I didn't know @inforef, and I modified the general Info hyperlinking
mechanism which @inforef must invoke.