Re: Makeinfo --html produces broken external refs

[Sergey Poznyakoff]

Eli Zaretskii <address@hidden> ha escrit:

> It is hard to comment on the assertion that ${base_url}/manual is
> incorrect, because it is unclear what does ``manual'' stand for.

I was referring to the current layout of http://www.gnu.org/software.
In two words it is as follows:

1. Each project has a subdirectory (software/PROJECT) named after its
   official name.
2. Within that directory the .html pages forming its `home site' are
   hosted
3. Within that directory there is also a subdirectory named `manual',
   which contains the documentation for that project.
4. In particular, the monolithic html version is stored in file
   software/PROJECT/manual/PROJECT.html and the split html version
   is stored in the subdirectory software/PROJECT/manual/html_node   

This is a general outline, some minor differences may occur, e.g.   
those projects that generate their html docs using texi2html quite
often have also subdirectories html_mono/ and html_chapter/ for
monolithic and split by chapter versions. But in general it is pretty
standard by now, in particular because it is promoted by `gendocs.sh'
script, which is part of Texinfo.
   
> I think that's your problem, right there: this organization of the

I dare say that's rather the problem of GNU, not mine. Among the
documentation for various projects hosted on www.gnu.org/software, I
have found several dozens of broken references similar to the one I've
shown in my previous posting. I doubt they improve quality of GNU
documentation.

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

This may have been the case in the early days of GNU, but it is not now.

> IOW, for your example, makeinfo assumes that the www.gnu.org/software/
> directory has the files xref.html and tar.html.
[...] 
> 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.

Yet it was a surprise to me, because another part of Texinfo (gendocs),
seems to encourage the use of quite another layout, as I described above.
 
> (It is, of course, an embarrassment that www.gnu.org doesn't follow
> the guidelines of its own documenting system,

I'd rather call this `evolution'. The simple, `flat' layout you described
was OK when there were 10-20 components in GNU. It is hardly usable for
170+ projects that it has now.

> 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

In that case I guess there are two solutions: either ask all project
developers (or www.gnu.org admins?) to change the existing directory
layout, or to fix makeinfo to handle it properly. 
 
> I think Texinfo currently doesn't support such a feature.

Partially, it does. I mean @uref and the like.

> The idea is that one generates a set of manuals for a single site.

Agreed. But the problem is there are several such sites. And it is
sometimes desirable (or even necessary) for the docs from one such site
to refer to those located on another one. In particular, the docs of the
projects hosted on gnu.org.ua do contain such references.

> I'm not sure is a good idea to hard-code hosts into a document.

Perhaps so... But we are already hardcoding many similar things in the
docs. The printed document names and even HTTP references (using @uref),
to name a few. So I don't see why that differs. 

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

Such a feature might be useful. Nevertheless, I believe that the
documentation system should provide a mechanism for specifying base URLs
in the document. For example, if any piece of documentation refers, say,
to GNU tar, it is quite natural to point to the tar's documentation on
www.gnu.org and not elsewhere. Besides, the same document can refer to
documentation for two projects hosted on different sites. In that case a
command line option would hardly help, because it would supply only one
URL. With the @setxrefurl commands, the base url for any following @xref
can be reset any place in the document.

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

Ah, that's exactly what I described above :^)
 
> 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.

No problem:) Discussion is always a good thing, as it helps both parties
to better understand the problem.

Regards,
Sergey