Re: use directly section childs with sectiontoc, set USE_NODES 0 for HTML

[Patrice Dumas]

On Sun, Nov 01, 2020 at 11:40:56AM +0000, Gavin Smith wrote:
> On Sun, Nov 01, 2020 at 01:37:04AM +0100, Patrice Dumas wrote:
> > Hello,
> > 
> > Why is there no sectiontoc for the @top?
> 
> Because the index.html file usually has @contents or @shortcontents
> as well as the Top node.
> 
> At https://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html
> there are actually three tables of contents: @shortcontents, @contents,
> and the menu.  This is unnecessary.

Ok, but then this means that there should be a sectiontoc if there is no
@shortcontents nor @contents.

> > Wouldn'it be better to simply output the section toc of the section, and
> > not the 'current_node' associated section section toc?  For some manuals
> > it would make a difference and, in my opinion, an incorrect output, for
> > example when there is a construct like
> > 
> > @node mynode
> > @section sec1
> > 
> > @section sec2
> 
> You are probably right.

I'll implement that.

> > It also seems to me that FORMAT_MENU set to sectiontoc for HTML would be
> > more consistent with USE_NODES set to 0.  Otherwise nodes without
> > section would each be in their files, but not appear on section tocs,
> > and their subnodes would be completly unreachable.
> 
> I'm not sure how sensible it is to use @section without a @node or vice
> versa.  A @node without a section wouldn't be in the section toc anyway,
> if I understand correctly.

Indeed, but at least its content would be output as part of a section.

> I don't have a strong opinion about it, but I feel that the primary
> meaning of @node is to define a named unit of the manual, rather than
> define a cross-reference target.  This would mean that each node
> would be in a separate HTML file when output is split, which means
> that USE_NODES should be on.
> 
> A node without a section could be part of a manual with an irregular
> structure and it might be reachable by other means.

There is probably no general case when there are nodes without section.

>   In that case, 
> > _default_node_direction() should probably be changed, to give something 
> > reasonable when there is no node associated with the section.  Actually,
> > it would probably make more sense to use sections for directions if
> > USE_NODES is set to 0.
> 
> I haven't investigated what happens currently but this might make sense
> so that the section has "Next" and "Prev" links.

Ok.  I will probably try to do something for that case.

-- 
Pat