Re: next in menu also below, error message?

[Patrice Dumas]

On Sat, Nov 05, 2011 at 10:25:16PM +0000, Karl Berry wrote:
> 
> Right, and it's for exactly that reason that I think there should be a
> warning.  When we are determining the pointers, by definition the manual
> is supposed to be "normally" structured, and deviations from that should
> assumed to be mistakes by the user, and hence we should give warnings to
> help him/her.
> 
> Whereas if explicit pointers are given, then no warning -- it's not our
> place to override the user's explicit choices.
> 
> Sound ok?

I have been trying to fix that and report a warning everytime there is
an inconsistency between the menu structure and the sectioning structure
in case of automatic directions.  It flags errors that are certainly 
errors, so it certainly has value.  For instance it shows for doc/texinfo.txi

texinfo.txi:22447: warning: Node `Info Format Indirect Tag Table' is next for 
`Info Format Preamble' in menu but not in sectioning

which is certainly right, since `Info Format Preamble' has an associated
@subsection, while it is a @subheading for `Info Format Indirect Tag Table'.
It should certainly be consistent, either only @subsection or only @subheading.


But it also flags situations incorrect, which are not clearly so.
Can you give an advice on which one are correct?

Here is the first: not @top associated with @node Top, like

 @node Top

 @menu
 * chapter::
 @end menu

 @node chapter
 @chapter A chapter

Should we accept the warning as a correct wanrning and mandate a @top in 
that case?

A second example is a manual with no @top, but the first @chapter 
associated with @node Top:

 @node Top,Second,,(dir)
 @chapter Chap

 @menu
 * Second::
 @end menu

 @node Second
 @chapter Chap2

The error is 
d.texi:9: warning: Node `Top' is up for `Second' in menu but not in sectioning


Then there is the 'intercalar' node, which existed for example in an old 
texinfo.txi, for example, `Useful Highlighting' is such an intercalar 
node, which is associated to @subheading and not to a sectioning command
like:

 @node Indicating, Emphasis, Marking Text, Marking Text
 @section Indicating Definitions, Commands, etc.

 @menu
 * Useful Highlighting::         Highlighting provides useful information.
 * code::                        Indicating program code.
 @end menu

 @node Useful Highlighting, code, Indicating, Indicating
 @subheading Highlighting Commands are Useful

 @node code
 @subsection @code{@@address@hidden@address@hidden

now leading to
e.texi:28: warning: Node `Useful Highlighting' is prev for `code' in menu but 
not in sectioning

makeinfo in C accepts such a construct.


If there are nodes associated to parts, it is also easy to get 
warnings as with

 @node Top
 @top top

 @menu
 * chapter node::
 * part chapter node::
 @end menu

 @node chapter node
 
 @chapter chapter node
 
 @node part chapter node
 @part part

 @chapter chapter with part node

f.texi:9: warning: Node `part chapter node' is next for `chapter node' in menu 
but not in sectioning
f.texi:13: warning: Node `chapter node' is prev for `part chapter node' in menu 
but not in sectioning
f.texi:13: warning: Node `Top' is up for `part chapter node' in menu but not in 
sectioning

In that case it seems to me to be clearly wrong...


So, do you have an idea on what should be reported as an error?

-- 
Pat