Re: Texinfo -> HTML issues

[Aubrey Jaffer]

 | Date: Tue, 27 Jul 2004 22:18:41 +0300
 | From: Alper Ersoy <address@hidden>
 | 
 | 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.

Writing to index.html takes away my choice of whether to use the Top
node or the "table-of-contents" or a title page as my index.html; or
at least forces me to makefile or script file renaming.

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

Recoding every "-" as _002d is hideous; and totally unnecessary on a
file-system supporting spaces or "-" in filenames.  Please make this
recoding an option to makeinfo.

Certain characters like "/" or "\" are bad for filesystems.  But they
need not be ASCII coded; just convert them to "-".  The only time this
will lose is if someone has nodes named "File I/O" and "File I-O" --
not a common occurence.

 | >           o The filename index.html should only be used as a symbolic 
link. 
 | 
 | What is the rationale behind this?

In this case it is so the author can control the presentation of the
HTML tree.

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

There was an @ifinfo around the text; the tops of my texinfo files
were copied from texinfo documentation circa 1996.

 | I just tried writing a few lines below the @settitle line in
 | texinfo.txi, and they appeared in the top of the index.html.

Yes -- but now it doesn't appear in the info file, and appears on the
dvi cover page instead of the title page.

I would put a copy of that text before the first menu if I could
condition it on not being @iftex.  But there seems to be no negative
conditionals in texinfo:

  makeinfo slib.texi --no-warn --no-split -o slib.info
  slib.texi:108: Unknown command `ifnotex'.

So instead, I must put two copies of the text; one with @ifinfo; one
with @ifhtml.  This is in addition to another copy in the @titlepage.
Needing three copies of the same paragraph indicates profound
brokenness.

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

How many years will makeinfo continue to produce nonconforming HTML in
support of this rumored browser bug?  Maybe it could be a flag, say
@nohtmldtd

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

Here are function definitions for "distribute/" as produced by
makeinfo --html 4.7 and texi2html 1.52 circa 1998:

  <div class="defun">
  &mdash; Constant: <b>distribute/</b><var><a 
name="index-distribute_002f-910"></a></var><br>
  <blockquote><p>Contains the ruleset to distribute division over addition and
  subtraction.
         <p>Take care when using both <var>distribute*</var> and 
<var>distribute/</var>
  simultaneously.  It is possible to put <code>/</code> into an infinite loop. 
  </p></blockquote></div>


  <P>
  <DL>
  <DT><U>Constant:</U> <B>distribute/</B>
  <DD><A NAME="IDX910"></A>
  Contains the ruleset to distribute division over addition and
  subtraction.
  <P>
  Take care when using both <VAR>distribute*</VAR> and <VAR>distribute/</VAR>
  simultaneously.  It is possible to put <CODE>/</CODE> into an infinite loop.
  </DL>

They produce similar output; but the lower one is HTML-3.2 conforming
while the top one is not (class is not an argument to div).  HTML-3.2
is very widely supported and can produce fine manuals.

Using HTML-4 when its extra features are not required needlessly
breaks rendering on older browsers.

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

Yes it can!  validator.w3.org does not flag that as a violation.

It previously was the case that the info reader and Emacs found only
the first instance of an index.  Has that changed?  We lived with it
that way for years.  I would gladly accept first-index-only in trade
for straightforward anchor translation.

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

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  <HEAD>
  <TITLE>Nano-Cellular Automata</TITLE>
  <META NAME="keywords" CONTENT="Cellular Automata, nanoscale circuits, 
Universal Automaton">
  <META NAME="description" CONTENT="Nano-Cellular Automata.">
  </HEAD>

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  <HEAD>
  <TITLE>copyright!</TITLE>
  <META NAME="keywords" CONTENT="copyright, digital image, Histocomputability">
  <META NAME="description" CONTENT="Brand images with copyright notice.">
  </HEAD>

 | Does @direntry come close?

@direntry contents might be good for the index.html keywords or
description fields.  But I want each individual file to have its
indexes listed (comma-separated) in its keywords slot.

A file having the anchors:

  <a name="Commutative-Rings">
  <a name="index-commutative_002dring-897">
  <a name="index-careful-899">
  <a name="index-self_002dset-900">
  <a name="index-self_002dset-901">
  <a name="index-Unique-Factorization-902">
  <a name="index-_002aruleset_002a-904">
  <a name="index-make_002druleset-905">
  <a name="index-make_002druleset-906">
  <a name="index-combined_002drulesets-907">
  <a name="index-combined_002drulesets-908">
  <a name="index-distribute_002a-909">
  <a name="index-cring_003adefine_002drule-911">
  <a name="index-cring_003adefine_002drule-912">

should have in its <head> section:

 <META NAME="keywords"
       CONTENT="Commutative Rings, commutative-ring, careful,
                self-set, Unique Factorization, *ruleset*,
                make-ruleset, combined-rulesets, distribute*,
                cring:define-rule">

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

  @xref{Time, current-time, , slib, SLIB}

currently translates to:
  
  See <a href="../slib/Time.html#Time">current-time (SLIB)</a>.

I would have it be:

  See <a href="../slib/Time.html#current-time">current-time (SLIB)</a>.

 | Maybe makeinfo should split at first character boundaries?

Never mind.  I had forgotten about indexes-not-having-nodes kludge.

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

Although I had to add a fourth copy of that accursed paragraph, the
following commands seem to work in producing a separate table of
contents with the preamble in "SLIB.html" while continuing to work
with tex and info!

  @ifinfo
  @node Indexes,  , About SLIB, Top
  @unnumbered Indexes
  @end ifinfo

  @ifhtml
  @node Indexes, Procedure and Macro Index, About SLIB, Top
  @unnumbered Indexes
  @end ifhtml

  @menu
  * Procedure and Macro Index::
  * Variable Index::
  * Concept Index::
  @ifhtml
  * SLIB::  Full Table of Contents
  @end ifhtml
  @end menu

  @node Procedure and Macro Index, Variable Index, Indexes, Indexes
  @unnumbered Procedure and Macro Index

  This is an alphabetical list of all the procedures and macros in SLIB.

  @printindex fn

  @node Variable Index, Concept Index, Procedure and Macro Index, Indexes
  @unnumbered Variable Index

  This is an alphabetical list of all the global variables in SLIB.

  @printindex vr

  @node Concept Index, , Variable Index, Indexes
  @unnumbered Concept and Feature Index

  @printindex cp

  @ifhtml
  @node SLIB, , , Indexes
  @unnumbered SLIB
  @noindent
  @dfn{SLIB} is a portable library for the programming language
  @dfn{Scheme}.  It provides a platform independent framework for using
  @dfn{packages} of Scheme procedures and syntax.  As distributed, SLIB
  contains useful packages for all Scheme implementations.  Its catalog
  can be transparently extended to accomodate packages specific to a site,
  implementation, user, or directory.
  @end ifhtml

  @contents
  @bye

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

I used @node; thanks for the suggestion!

 | Then you won't have to use @unnumbered.

How do I get rid of @unnumbered -- aren't those needed for the printed
copy?  Using @unnumberedsec caused the indexes to start mid-page and
have funny breaks in printed output.

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

Embedding is needed when we don't have hooks for headers and footers.

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

Having the names of the next and previous nodes in the navigation bar
is useful, but the frequent shifting of the navigation buttons because
of different name lengths makes it difficult to skim through pages
quickly.

A way to stabilize the bar would be to use TABLE with width=100%:

  <TABLE WIDTH="100%">
  <TR><TH><a name="Commutative-Rings"></a>Next:&nbsp;<a rel="next" 
accesskey="n" href="Matrix-Algebra.html#Matrix-Algebra">Matrix Algebra</a>,
  <TH>Previous:&nbsp;<a rel="previous" accesskey="p" 
href="Minimizing.html#Minimizing">Minimizing</a>,
  <TH>Up:&nbsp;<a rel="up" accesskey="u" 
href="Mathematical-Packages.html#Mathematical-Packages">Mathematical 
Packages</a>
  </TABLE>

When I am reading through documentation, then a "next" button at the
bottom would save me the effort of uppaging to the top in order to
advance to the next page.