Re: Makeinfo --html produces broken external refs

[Eli Zaretskii]

> From: "Sergey Poznyakoff" <address@hidden>
> Date: Thu, 05 Jul 2007 16:35:48 +0300
> cc: 
> 
> Cross-references to external documents produced by makeinfo --html are
> almost always broken. This is because (1) the hostname part of a
> reference is always supposed to be localhost, and (2) the href is build
> using this approach (xref.c around line 270):
> 
>   else if (splitting)
>     execute_string ("\"../%s/", file_arg);
>   else
>     execute_string ("\"%s.html", file_arg);
> 
> which is wrong even when referencing to the document within the same
> host. Indeed, in split mode '../%s' would refer to
> `${base_url}/manual', which surely will not contain the document in
> question.

It is hard to comment on the assertion that ${base_url}/manual is
incorrect, because it is unclear what does ``manual'' stand for.
However, in view of what follows, I dare to say that you are wrong;
see below.

> Consider the following test document:
> 
> -- cut here --
> \input texinfo 
> @smallbook
> @setfilename xref.info
> @settitle External cross references
> 
> @node Top, , (dir), (dir)
> 
> @xref{tar invocation, Invoking GNU tar, Invoking GNU tar, tar,
> GNU tar: an archiver tool}, for the information about how to invoke GNU tar.
> 
> @bye
> -- -- cut here --
> 
> Assuming its html variants were installed at the usual locations
> www.gnu.org/software/xref/manual/xref.html and
> www.gnu.org/software/xref/manual/html_node/*

I think that's your problem, right there: this organization of the
``usual locations'' is not what makeinfo's code has in mind.  Makeinfo
produces HTML files assuming that there is a single directory where
all the manuals live.  A split-node manual is assumed to live in its
own subdirectory of that directory, and the name of that subdirectory
is assumed to be identical to the name of the monolithic HTML manual.

IOW, for your example, makeinfo assumes that the www.gnu.org/software/
directory has the files xref.html and tar.html.  Each one of those
files can be a regular file (in case it's a monolithic manual) or a
_directory_ where all the node HTML files of that manual live (in the
split-node case).  The node "HTML Splitting" in the Texinfo manual
attempts to describe this.

It is this organization that makeinfo expects, and what you describe
is radically different.  So it's not a big surprise that it doesn't
work.

(It is, of course, an embarrassment that www.gnu.org doesn't follow
the guidelines of its own documenting system, but that's a different
matter for a different discussion.)

> the xref in question would
> point to:
> 
> (in split page) www.gnu.org/software/xref/tar/tar-invocation.html
> (in monolithic page) www.gnu.org/software/xref/tar.html#tar-invocation
> 
> which both are far from what was intended.

Right.  But makeinfo expects this xref to point to

 (in split page) www.gnu.org/software/tar/tar-invocation.html
 (in monolithic page) www.gnu.org/software/tar.html#tar-invocation

from

 (in split page) www.gnu.org/software/xref/index.html
 (in monolithic page) www.gnu.org/software/xref.html

which does the job, right?

> But this approach has two drawbacks: first, it is impossible to refer to
> a document located on another host

I think Texinfo currently doesn't support such a feature.  The idea is
that one generates a set of manuals for a single site.

> Therefore, in addition to the above change, I propose to introduce two
> new commands:
> 
> @setxrefurl URL
>   Sets the base url for 5-argument xrefs in monolithic html mode.
>   
> @setxrefspliturl URL
>   Sets the base url for 5-argument xrefs in split html mode.

I'm not sure is a good idea to hard-code hosts into a document.  I'd
suggest to implement such a feature as command-line arguments, because
the same Texinfo document can be processed into HTML on several
different machines that want to reference different hosts.

It would be also nice to figure out a convenient way of specifying
different prefix URLs for different manuals referenced from the
document that is processed.  For example, a FOO manual could xref to a
BAR manual on host1 and to BAZ manual on host2.

Last, but not least: I'm _not_ the official Texinfo maintainer, and
although I originally wrote most of the HTML split code, it was a long
time since I last hacked Texinfo.  Therefore, it could be that what I
wrote above is no longer correct; apologies if that's the case.