Re: up, nodeup, directions

[Patrice Dumas]

On Tue, Nov 08, 2011 at 12:31:26AM +0000, Karl Berry wrote:
>     7. For the 'Up' direction which is normally associated with
>     sectioning command when there is no such direction, the node up
>     direction is used (the up node directions is always associated with
>     the 'NodeUp' direction).  Is it right (I guess this one is a bit
>     tricky...)
> 
> Tricky enough that I simply don't understand from this description.  Can
> you explain further, or show an example?  Sorry.

Indeed, my explanation just didn't make sense.  An example indeed is much
better.  This issue happen mostly when there is no @top, yet there is a 
Top node.  There are 2 examples in the texi2html test suite, the viper 
manual (though an old version, i guess the manual has changed), and the
singular manual.

For example the viper manual is roughly like

 @unnumbered Distribution

 @node Top, Overview,, (DIR)
 @unnumbered Viper

 @menu
 * Overview::                    Read for a smoother start
 ....
 @end menu

 @unnumbered Introduction

 @node Overview,Improvements over Vi,Top,Top
 @chapter Overview of Viper

The idea may be to have a structure like

   Distribution
 Viper
   Introduction
   1 Overview of Viper

although all the sectioning commands are at the same level.  That way,
the '@unnumbered Viper' is a kind of a @top, but with the possibility to
have something before on a level below.  The @node hierarchy add a level 
that cannot exist with the sectioning tree alone.


My current point of view is that it is wrong to bend the structure of
Texinfo documents like that.  So I have used a customization variable such
that the up node is used for the up section only if this variable is
set, and it is no set in the default case unless in texi2html compatibility
mode.

-- 
Pat