Re: Texinfo -> HTML issues

[Eli Zaretskii]

> From: Aubrey Jaffer <address@hidden>
> Date: Tue, 27 Jul 2004 21:06:49 -0400 (EDT)
> 
>  | One problem with symbolic links is that they are not portable to
>  | non-Posix platforms.
> 
> The only filename which will be in (nearly) every HTML directory is
> "index.html".  This fact makes overwriting index.html a dangerous
> policy.  It may be that dissatisfaction with the HTML produced will be
> widespread and unavoidable.  If most users will be scripting
> customizations, then setting up index.html should be left to them to
> do explicitly.

Sorry, I Don't understand how this relates to the problems with
symlinks.  Could you please explain?

As for user dissatisfaction, the HTML mode exists for quite some time,
and I don't think anybody complained along these lines.

>  | > * The tag NAME= names all unique numbers appended to them.  This makes
>  | >   it impossible to refer to index points like function names which
>  | >   remain stable.  Again, someone's zeal for rigidly complete solutions
>  | >   has torpedoed a valuable feature.
>  | 
>  | The reason was not rigidity, but solution of specific practical
>  | problems; one of them was that references should work regardless of
>  | whether the HTML file is produce with or without the --no-split
>  | option.
> 
> But the filename is different in those cases.  Linking every node name
> to index.html is an ugly solution, and doesn't work on systems without
> links (unless the whole file is copied for each node name).

I have a feeling that we miscommunicate.  Could you please give an
example of the problematic tag and explain why it gives you trouble?

> But lets think a minute.  Document systems with lots of interfile
> references will usually be large.  Large aggregated HTML files are a
> poor policy for many reasons: they waste bandwidth, they have high
> latency, their formatting consumes lots of CPU.

Texinfo is not an HTML authoring system; it's a documentation system.
If the author of a manual used lots of cross-references, makeinfo has
no choice but to generate the same links in HTML.

> I think a choice should be made to support interfile references only
> when splitting.  A less radical solution is to assume that files being
> referenced have the same splitting policy of the texinfo file being
> processed.

The former is IMHO unacceptable, while the latter is an invalid
assumption (we have no real control on how the files were split; a
random collection of GNU Makefile's will show you that some are while
others aren't).

>  | > * For a large manual like SLIB, makeinfo generates a single 1840-line
>  | >   "Index.html" file which is slow to load, even on a fast computer.
>  | >   Those indexes should be split, at the minimum, into the three
>  | >   individual index tables.
>  | 
>  | Please suggest how to split them without producing invalid HTML or
>  | failing the most important requirement: that references from other
>  | documents predictably produce correct links, even when the target
>  | document is not available to makeinfo at the time it produces HTML
>  | output.
> 
> There should be no references from other files into an index!

Why not?  An index is just a node, so it can be referenced.

In addition, the Top node is normally in the same file, so any
reference from another manual will frequently land there.

>  | >   The full table of contents should be put in its own file.
>  | 
>  | Makeinfo cannot produce node names where there aren't any in the
>  | Texinfo source.
> 
> Sure it can!  Just call fopen("Table of Contents", "w");

I was being serious.  If you have suggestions how to do that, please
spell them out.

The reason that a separate file would be a problem is that the TOC is
not a separate node.

>  | >   I am not asking you to cater to my practices, but there should be
>  | >   some method to let users support such per page headers.
>  | 
>  | How about @html?
> 
> It is not feasible to maintain an unique absolute URL in every node.
> These should be automatically generated.

Sorry, once again we have a misunderstanding, I think.  An example and
a few more explanations might help.