[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Ideas about default HTML output?

From: Karl Berry
Subject: Re: Ideas about default HTML output?
Date: Thu, 28 May 2009 19:30:08 -0500

    The issue I see with the node names is that it is not easy to also
    have >> which leads to the next chapter. And also the header may be
    quite long.

Yes, those are problems.  I don't see a reasonable way to include that
info with the names, either.  Nor do I think two lines of header is

This is the kind of the thing where there is no one right way.
Different authors might prefer different things, different manuals might
call for different things.  (For example, the next/prev chapter links
are redundant in the hello manual, since there is nothing but chapters.)

So I think this is the case where we make the default one way or the
other, and then say how to change the default (you probably already do),
If we have to, we could have "makeinfo style" and "texi2html style" to
bundle various choices, although I'm not sure authors care that much.

    Can you please tell more precisely what would look like the header, for 
    an example?
I'm thinking to just add the [Contents].  E.g, for

Next: Invoking hello, Previous: Overview, Up: Top  [Contents]

    Maybe the link to Top shouldn't be needed instead, and only the link
    to Content would be there?

Yes, that sounds better to me.

It puzzles me to have the contents be at the end.  Granted having it be
the first thing in the output (as makeinfo does) is not great either,
the toc as an object simply does not conventionally go at the end.

    Bold is already used for the function name. But I agree that underline 
    is not optimal. Maybe use italics (also used for argument?).

Italics would be better than underline.
Or maybe just roman.  That's what is done in TeX and makeinfo.
The indentation seems enough.  I can agree with not having the em-dash,
by the way.
(Looking at

    > Here I kind of like makeinfo's list formatting with the bullets.

Today I like texi2html's output better in the examples you made.

    There are, in fact more differences. The menu-headers are in
    th/thead in texi2html, (so, bold) and formatted in preformatted

What are "menu-headers"?  I'm not seeing this, sorry.

    The sections are used and not the node names. 

It looks like you also change the xref targets to use section names?
That's consistent, but I don't see a strong reason to deviate from the
default.  We use the node names in texinfo.tex and all other output.
Granted that it is a useful option, since some people like to do it.
(And there is a silent option for it in texinfo.tex.  Anyway.)

    There is a formatting as table, separatng the menu-description apart
    from the node name.

That looks nice.


One thing I notice in the texi2html output is that it just has "A", "B",
etc., for the appendix nodes, such as

The makeinfo (also TeX, etc.) output has the word "Appendix" there,
although not in the subnodes.  I think that's desirable, because it's a
strong convention in English books.  (Interestingly, your makeinfo
output has "Annexe" instead of "Appendix"; obviously the current instead
of document locale information was being used.  I thought that had been
fixed.  Oh well.)

And, I don't think there should be periods after the appendix numbers,
since there aren't after chapter numbers.  Like this:

Appendix A  Top-level Appendix
A.1 First appendix section
A.1.1 First appendix subsection
A.2 Second appendix section


reply via email to

[Prev in Thread] Current Thread [Next in Thread]