Re: Texinfo -> HTML issues

[Alper Ersoy]

Hello,

Aubrey Jaffer:
> * 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:

makeinfo generated files are not supposed to be edited at once in
Emacs.  Ideally, authors should only have to the edit the Texinfo
source of their manuals.  So, I doubt this recommendation applies
to what makeinfo produces.

>           o Try and give each html file a unique name.

We try to comply with this one as much as possible, and fallback
to alternative methods that work, if not elegant filesystem-wise.

>           o The filename index.html should only be used as a symbolic link. 

What is the rationale behind this?

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

I cannot say anything without looking at the document source first.  I
just tried writing a few lines below the @settitle line in texinfo.txi,
and they appeared in the top of the index.html.

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

I was told older versions of some browsers had problems with DTD
lines.  Otherwise I would already have added one.

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

My guess is cross browser compatibility issues, mostly.  Please
show a few examples where you believe there's room for improvement
regarding this area.

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

An HTML document cannot contain two different anchors with the same
name.  However Texinfo allows creating index entries at different
locations (nodes) with the same name.  And once you start appending
unique numbers to anchor names, it doesn't matter if you add to all
or a selection.

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

Please provide a few examples and I'll see what I can do.  Does
@direntry come close?

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

Suppose we fixed the unique anchors issue some way, then how will
makeinfo refer to index entries in foreign documents?

Maybe makeinfo should split at first character boundaries?

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

Maybe what you are looking for is:

  @node Table Of Contents
  @unnumbered Table Of Contents
  @contents

I admit there's a problem with this though, you will have two headings
for before the table.  Of course, you can work it around with a little
script for the time being.  Your other choice is to use the full
syntax of the @node command, in which you provide parent, next and
previous node names.  Then you won't have to use @unnumbered.

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

You can strip headers of HTML pages, if scrtiping is already an
option.  Also I plan to make makeinfo produce bare-bones HTML pages in
the future, ie. no head, only body.  Then they will be more
"embeddable."

Also, if shameless plugs are ok, http://beast.gtk.org is generated
from Texinfo sources (except the dynamic pages of course.)  So, it
_is_ possible to get different output from makeinfo. :)

If you have concrete ideas on how the final HTML output should look,
I'd love to discuss.  Texinfo 4.7 is not final, and open to future
improvements. :)

Thanks,

-- 
Alper Ersoy