Re: gendocs.sh and texi2html

[Patrice Dumas]

On Sun, May 06, 2007 at 01:48:12AM +0200, Bruno Haible wrote:
> 
> In the manual I maintain, the "Top" node contains only redundant information:
> a brief sentence what the manual documents (duplicates the manual's headline),
> and a big @address@hidden menu (ignored anyway since I use --no-menu).

Ok, with --no-menu it is likely to be better to avoid the Top node.

> > In general it avoids warnings about nodes that don't appear in menus. 
> 
> Yes. Good point. Why does
>    "perl texi2html-1.76 --no-menu --no-sec-nav -number -monolithic ..."
> give me warnings
>    ** node_prev `Top' for `Introduction' not found 
>    ** node_up `Top' for `Introduction' not found 
>    ** node_up `Top' for `Users' not found 
> although I've told texi2html to ignore the menu structure?

Because these warnings are for the node structure like
@node node, next, previous, up

Could you please send the manual you use?

> It's right for texi2html-1.76. But I'm using texi2html-1.52 since I don't
> see a way to overcome three problems with texi2html-1.76:

texi2html-1.52 seems very old to me, I guess there is no
documentencoding support (it appeared in 1.68).

>   1) Although in the .texi file, I have the @contents command before the
>      Top node, texi2html-1.76 puts the table of contents near the end of
>      the document. This is fine for books, but is against common conventions
>      for HTML documents - which is why I placed the @contents at the 
> beginning.

Currently the place of the @contents command is ignored. But it was also
like that in the past. Even in 1.52 (unless I didn't read the code
right). In 1.52 table of contents was always at the beginning, at some
point it changed to always be at the end. I'll think about that issue.
 
>   2) Is there a way to *not* generate the "About This Document" section?
>      IMO, a well-done HTML document shouldn't need explanations of the
>      navigation.

I'll look at that. It seemed to me that it was 'easily' done by setting
a variable to undef, but it doesn't appears to be that well explained in
the manual.

>   3) The HTML title of the document (generated with -monolithic, without a
>      Top node) is the title of the first chapter only.

I see. On the autogen manual it leads to:
<title>AutoGen - The Automated Program Generator: 1. Introduction</title>
Having ': 1. Introduction' seems indeed wrong. 

--
Pat