Texinfo -> HTML issues

[Aubrey Jaffer]

                              Motivation

I develop and maintain 5 free software projects (JACAL, SLIB, SCM, WB,
and SIMSYNCH) having roughly 35,000 lines of texinfo documentation.

Long before makeinfo could produce HTML, I started using the texi2html
Perl script to web publish these manuals.  There are many things
texi2html did wrong, but I developed workarounds, scripts, and
forbearance enough to use it.

Now that makeinfo can produce HTML, it would be nice to escape my
1996-syntax straight-jacket maintaining compatibility with texi2html.
But the makeinfo generated HTML has many problems of its own.  It may
be too much to hope that texinfo developers would bend on so many
issues, but here they are.

                       Issues with texinfo 4.7

* Why isn't the top node named Top.html?  Having it named index.html
  would seem to conflict with FSF recommendations on HTML
  (fsf-html-style-sheet).

    * To make it easier to edit many files at once in Emacs:
          o Try and give each html file a unique name.
          o The filename index.html should only be used as a symbolic link. 
    * 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.

* Why doesn't my text appear on the Top page.  A single level menu
  without text is quite unwelcoming.

* makeinfo HTML pages don't pass validator.w3.org because they lack a
  DTD.  Why isn't one generated?

* Makinfo's goal of HTML being somewhere between HTML-2.0 and HTML-4
  makes little sense.  I am unaware of anything that manuals should
  have that isn't supported by HTML-3.2.  Is this an
  internationalization issue?  What problem does this agnosticism
  solve?

* The extreme lengths that the node-to-filename translation undergoes
  seriously limits its usefulness.  We should make it easy to know
  what HTML pages will be named; one should not need to lookup ASCII
  codes.  There are node names like "Top" which are unavailable; not
  being able to have distinct nodes named "silly name" and
  "silly-name" is hardly a burden.  It is better to have predictable
  node names than to have obscure ones which never-ever conflict.

* 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 indexes into the each HTML file should be listed in that page's
  META NAME="keywords" header record.  For lack of these keywords,
  many of my official manuals are eclipsed in Google indexing priority
  by out-of-date versions generated by other programs.

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

* Further burdening Index.html is the full "Table of Contents".  What
  were you thinking??  Putting it at the end of the indexes doesn't
  let me use it as an alternative to the unfriendly top node discussed
  earlier.  The full table of contents should be put in its own file.
  Stuck for a name?  How about "Table-of-Contents.html".

* All of my (non-manual) web pages have the full URL and link to the
  original page.  This helps prevent users from being trapped on
  out-of-date mirror sites and generating out-of-date bug reports.

  I am not asking you to cater to my practices, but there should be
  some method to let users support such per page headers.  That is
  what extension languages are for.  Texinfo or makeinfo should make
  Guile callbacks for HTML page headers and footers.

If anyone is interested in more detail, I can provide more explicit
suggestions.

PS.

http://lists.gnu.org/archive/html/bug-texinfo/ does not have enough
traffic for monthly archiving.  It would be easier to follow if
archives were quarterly or yearly.