Ideas about default HTML output?

[Patrice Dumas]

Hello all,

The info backend of texi2html is finished, and, though there are some
other things to do for perfect compatibility with makeinfo, I'd like to
have some feedback about what the default html should be when called
as makeinfo --html. Currently the makeinfo --html and texi2html outputs
are quite differents, and I think this is a good opportunity to try
to have the best output that takes what is better in both.

So, what would you like as default html output? More precisely, do you
think that the texi2html headers are great or bad, what about the footer,
do you like the letters in indices, the menu formatting?

A typical manual split by nodes may be found here:
http://maxima.sourceforge.net/docs/xmaxima/xmaxima.html

and unsplit:
http://home.gna.org/guile-dbi/guile-dbi.html

Manuals formatted with makeinfo can be more easily found, notably below
http://www.gnu.org/manual/

Also I'd like to have, if possible, some feedback on the CSS classes
that should be added or modified, how they should relate with @-commands
and whether more <div> or other elements should be added for CSS.

--
Pat

[Karl Berry]

    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.

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

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

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

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

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

    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.

    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.

    the menu formatting?

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

    A typical manual split by nodes may be found here:
    http://maxima.sourceforge.net/docs/xmaxima/xmaxima.html

    and unsplit:
    http://home.gna.org/guile-dbi/guile-dbi.html

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.

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


Thanks,
Karl

[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

[Karl Berry]

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

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
http://www.environnement.ens.fr/perso/dumas/comp_html/makeinfo/hello.html#Sample-output:

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
http://www.environnement.ens.fr/perso/dumas/comp_html/texi2html/texinfo/Sample-Function-Definition.html.)

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

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.

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

One thing I notice in the texi2html output is that it just has "A", "B",
etc., for the appendix nodes, such as
http://www.environnement.ens.fr/perso/dumas/comp_html/texi2html/texinfo/Tips.html

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


Thanks,
karl

[Patrice Dumas]

On Mon, May 25, 2009 at 07:51:00PM -0500, Karl Berry wrote:
>
> In the alternative, with texi2html's graphics, I'd find it more
> comprehensible if they were in the order
> << < Up > >>.

Indeed, I implemented it.

There is also a variable that determines if headers in table (texi2html)
are used or simple headers (like makeinfo). It is only set if called as
texi2html.

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

It is not output when simple headers are output.

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

I kept a big rule for the top element, and between the elements and
the misc elements (footnotes, contents...) when simple headers are not used.

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

It is now controlled by a variable that is set only when called as
texi2html. I don't like this advertizing footer either, but it is very
usefull to find out manuals generated by texi2html.

>     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 added an invisible unbreakable space.

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

I removed the underlining, and I italicized the type, such that both
are not in the same 'font'.

--
Pat

[Patrice Dumas]

On Thu, May 28, 2009 at 07:30:08PM -0500, Karl Berry wrote:
>
> 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.

There isn't really a "texi2html style" and a "makeinfo style", all the
differences are customizable through variables. There are currently
about 12 variables corresponding with the differences between texi2html and
makeinfo, some are for style customization, other for more important
stuff (like honor @setfilename or not).

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

I did that + I added the indice.
The name of the current node isn't output, is it on purpose?

> It puzzles me to have the contents be at the end.  Granted having it be

They are at end only if they are not output inline. When not called as
texi2html they are output inline.

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

Maybe there should be a comand like @insertitlepage, that could be
in @ifhtml for the texinfo manual? It seems to me that makeinfo C inserts
what is in @settitle, but I am not sure that it is the best.

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

I have reverted to the bullets, but it can easily be changed once more.

>     There are, in fact more differences. The menu-headers are in
>     th/thead in texi2html, (so, bold) and formatted in preformatted
>     environment.
>
> What are "menu-headers"?  I'm not seeing this, sorry.

It is text between menu entries. In the texinfo manual, you have,
for example:

 — The Detailed Node Listing —

Overview of Texinfo


> It looks like you also change the xref targets to use section names?

Indeed, it is one possibility. But there is a variable (and even
a command line option) that changes the behaviour, I set it in the
default case.

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

In texinfo.tex both are used, unless I am wrong (and I think that it is
quite ugly).

> One thing I notice in the texi2html output is that it just has "A", "B",
> etc., for the appendix nodes,
>
> And, I don't think there should be periods after the appendix numbers,
> since there aren't after chapter numbers.

Agreed to both issues, and fixed.


I have regenerated the output in the default case, it is still at

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

It now looks very similar with what produces makeinfo C, in my opinion.
Still not exactly the same, for instance one visible difference is that
there is a title output only in makeinfo C -- and there are certainly
many others.

--
Pat

[Oleg Katsitadze]

On Mon, Aug 10, 2009 at 11:50:37AM +0200, Patrice Dumas wrote:

> >     There are, in fact more differences. The menu-headers are in
> >     th/thead in texi2html, (so, bold) and formatted in preformatted
> >     environment.
> >
> > What are "menu-headers"?  I'm not seeing this, sorry.
>
> It is text between menu entries. In the texinfo manual, you have,
> for example:
>
>  — The Detailed Node Listing —
>
> Overview of Texinfo

Am I the only one seeing this?  In

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

the menu-headers are attached to a preceding menu, it looks like this:

    Overview of Texinfo


    1.1 Reporting Bugs
    1.2 Using Texinfo
    1.3 Info files
    1.4 Printed Books
    1.5 @-commands
    1.6 General Syntactic Conventions
    1.7 Comments
    1.8 What a Texinfo File Must Have
    1.9 Six Parts of a Texinfo File
    1.10 A Short Sample Texinfo File
    1.11 History
    Using Texinfo Mode


    • Texinfo Mode Overview
    2.1 The Usual GNU Emacs Editing Commands
    2.2 Inserting Frequently Used Commands
    2.3 Showing the Section Structure of a File
    2.4 Updating Nodes and Menus
    2.5 Formatting for Info
    2.6 Formatting and Printing
    2.7 Texinfo Mode Summary

And BTW, why are there bullets for first items of several detailed
menus (e.g., "Texinfo Mode Overview" above)?

Oleg

[Patrice Dumas]

On Wed, Aug 12, 2009 at 07:23:14AM +0300, Oleg Katsitadze wrote:
> Am I the only one seeing this?  In
>
>     http://www.environnement.ens.fr/perso/dumas/comp_html/texi2html/texinfo.html
>
> the menu-headers are attached to a preceding menu, it looks like this:

This should have changed. Now (unless called as texi2html) the menu has
the node names only on
http://www.environnement.ens.fr/perso/dumas/comp_html/texi2html/texinfo.html 


However there is still the equivalent of:

>     Overview of Texinfo
>
>
>     1.1 Reporting Bugs
>     1.2 Using Texinfo
>     1.3 Info files
>     1.4 Printed Books
>     1.5 @-commands
>     1.6 General Syntactic Conventions
>     1.7 Comments
>     1.8 What a Texinfo File Must Have
>     1.9 Six Parts of a Texinfo File
>     1.10 A Short Sample Texinfo File
>     1.11 History

Since it is how the @detailmenu is written in the texinfo manual
(an old texinfo manual version, but good enough).

I have reposted what is obtained when called as texi2html:
http://www.environnement.ens.fr/perso/dumas/comp_html/texi2html-style/texinfo.html

>     • Texinfo Mode Overview
>     2.1 The Usual GNU Emacs Editing Commands
>
> And BTW, why are there bullets for first items of several detailed
> menus (e.g., "Texinfo Mode Overview" above)?

It is because, in the default case, texi2html uses section names for
menu entry, but when there is no section name, it uses the node name.

--
Pat