Re: Texinfo -> HTML issues

[Aubrey Jaffer]

 | Date: Tue, 27 Jul 2004 23:31:46 +0200
 | From: "Eli Zaretskii" <address@hidden>
 | 
 | > From: Aubrey Jaffer <address@hidden>
 | > Date: Tue, 27 Jul 2004 00:13:24 -0400 (EDT)
 | 
 | >     * Each directory, in the web server tree, should have an index.html
 | >       symbolic link to the top-level html file for that directory. Use
 | >       the |.symlinks| file to handle this.
 | 
 | 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.

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

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.

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.

 | > * 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!  The
name translation issue has no bearing on spliting indexes.

 | > * Further burdening Index.html is the full "Table of Contents".
 | 
 | If you don't like it, you can always condition @contents with
 | @ifnothtml, for example.

Thanks for mentioning @ifnothtml, I had not known of it before.

 | >   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 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.  If there were a Guile
callback, my code would look like this:

(require 'printf)
(define *url-base* "http://swiss.csail.mit.edu/~jaffer/";)

(define (texinfo:node-html-body-callback node-name oport)
  (define filename (texinfo:node->filename node-name))
  (fprintf oport "<A HREF=\"%s%s\">%s%s</A>\\n"
           *url-base* filename *url-base* filename))