Re: Ideas about default HTML output?

[Patrice Dumas]

On Mon, May 25, 2009 at 07:51:00PM -0500, Karl Berry wrote:
>     to have the best output that takes what is better in both.
> 
> Yes.
> 
>     So, what would you like as default html output? More precisely, do you
>     think that the texi2html headers are great or bad, 
> 
> Hmm.  I like seeing the node names, as makeinfo does.

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.

Can you please tell more precisely what would look like the header, for 
an example?

> In the alternative, with texi2html's graphics, I'd find it more
> comprehensible if they were in the order
> << < Up > >>.

Makes sense.

> I like having the explicit link to Top and Index, as texi2html does.
> (But what do you do when there's more than one index?)

It links to the first element having a @printindex in it.

> The link to Sec_About (and that whole section) does not appeal to me.
> The output should be self-explanatory.

Ok.

> Normally the Contents link will be essentially the same as Top,
> therefore I think it's not needed.

Top is formatted like a menu, Content is formatted like a tree. Maybe the
link to Top shouldn't be needed instead, and only the link to Content
would be there?

> Noticed in passing: I think texi2html's between-node rules are too big
> -- just a simple <hr> seems enough?

You are right.

>     what about the footer,
> 
> I've never been too fond of the texi2html footer.  It's very often
> irrelevant who generated the document and the generation date can be
> misleading (the sources might be ancient).  That information is not
> (visibly) written in any other output format.  Of course it's fine/good
> to have it all in comments in the source.

Agreed.

But the question is also about the footer directions.

>     do you like the letters in indices, 
> 
> Yes.  I like texi2html's index formatting better.  Except there should
> be more space between the index term and the "page" reference -- looks
> like it's just a single space in the xmaxima manual.

I guess adding a row with an invisible space would do the trick
portably.

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

There are, in fact more differences. The menu-headers are in 
th/thead in texi2html, (so, bold) and formatted in preformatted 
environment. The sections are used and not the node names. There 
is a formatting as  table, separatng the menu-description apart 
from the node name.

> Noticed in passing: I do not like the underlining of the defun words
> like "Function".  I'm not sure what should be done, bold maybe, but
> underlining has such a strong association with links on the web.

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

>     Manuals formatted with makeinfo can be more easily found, notably below
>     http://www.gnu.org/manual/
> 
> It might be helpful to format a couple of documents both ways, so we can
> compare directly.  E.g., the Hello manual (simple) and the Texinfo
> manual (complex).

Good idea, I'll do that. Ok, it is on

http://www.environnement.ens.fr/perso/dumas/comp_html/makeinfo/
http://www.environnement.ens.fr/perso/dumas/comp_html/texi2html/

--
Pat