Re: Texinfo -> HTML issues

[Alper Ersoy]

Hello,

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

But, makeinfo splits documents to their own directory.  You can choose
the node you want to link to, as the documentation start point.

Suppose we are using makeinfo --html --no-split texinfo.txi and make
the output available online.  The output document would be
texinfo.html.  When the document grows, we may decide to split the
output into chunks, and then the output goes to a texinfo.html/
directory.  In this case, existing links (especially off-site) will go
on working.

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

But there's a very good reason we are making things this way: to make
the nodenames predictable, and unique as much as possible.  If I want
to link to a node in an external document, makeinfo will be able to
pinpoint the exact chunk in the pile.  If makeinfo puts more than one
node in the same file (due to nodename to filename conversion
deficiencies), and you want to link to one of them from some else
document, how will the user understand which one you are referring to?

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

HTML tree will be overritten with the next makeinfo run, so the good
practice should be to keep HTML documentation in a separate directory,
and this is how makeinfo generates HTML output.

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

Documents are valid, even if they fail due to the missing document
type declaration.

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

[examples snipped]

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

But we have to match the looks of Info and DVI outputs in HTML.  We
get complaints when makeinfo fails to provide this similarity.

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

We allow custom CSS to be attached to files, so we have to classify
document divisions to allow authors to stylize specific portions.
Therefore we _need_ class attributes.

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

So validator.w3.org is wrong in this occasion.

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

Very good idea, IMHO.  If others agree, I'll be glad to implement
this.

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

You are referring to the Time node of SLIB document, right?  In that
case, the output is correct, and it points to the start of the node.

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

I think just the opposing.  We need hooks because we do not generate
embeddable documents.  Once we start outputting body parts alone, one
can use any scripting language they want.

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

Well, I am against using tables for layout in HTML documents, but I'll
see what I can do about this.

Thanks!

-- 
Alper Ersoy