Re: control over sectioning and splitting

[Patrice Dumas]

Hello,

I am probably missions something, but isn't what you want obtained with
--split=chapter and using sectioning commands like @section,
@subsection?

On Sat, Oct 09, 2021 at 06:42:11PM -0700, Per Bothner wrote:
> Compare
>     https://domterm.org/Wire-byte-protocol.html
> with
>     https://domterm.org/Frontends.html
> 
> The former is a section, it is divided into subsections,
> which appear in the sidebar (when the page is selected) and in the Contents.
> 
> The latter is a chapter.  It is divided into pseudo-subsections,
> using @subheading commands, none of which appear in the sidebar or Contents.
> 
> I'd like to have the subheadings appar in the sidebar and the Contents,
> but I haven't figured out a good way to do that.
> 
> Is there a way to divide a "chapter" into "sub-chapters" such that they 
> appear on the
> same web-page, but show up in the sidebar and the Contents?
> 
> It seems possible for info.js to add extra entries in the side-bar by scanning
> the page looking for <h4 class="subheading">.  However, that seems a bit 
> kludgy
> and does not add the "sub-chapter" to the ToC.
> 
> One idea is to allow the children of a @chapter to be @subsections, skipping 
> the
> @section elements - but texi2any doesn't allow that.

Indeed.  There is a tree transformation, however, that you could maybe
use, it may not be perfect, but it is what is used for automatically
generated texinfo that does not follow that rule.

texi2any --split=chapter --html -c TREE_TRANSFORMATIONS=fill_gaps_in_sectioning 
XXX.texi

It adds an empty @unnumbered.

> Another idea is some kind of @samepage annotation to could be added to a 
> @section,
> to prevent page-spliting.  (This might be also useful for printed manuals.)
> 
> Another idea is to use @part: Everything that should be a separate page 
> should be its
> own @chapter, but we use @part to group together characters that should not 
> show
> in the sidebar until the @part if expanded.  (It is desirable to avoid putting
> too much in the sidebar, to make it less overwhelming.)
> 
> Another idea is to allow special handling for "single-section chapters".
> In the source you could write @chapter immediately followed by @section, 
> which the
> same name and no separate @node command:
> 
> @node Frontends
> @chapter
> @section Frontends including browsers
> 
> This would be logically equivalent to:
> 
> @node Frontends
> @chapter Frontends including browsers
> @node Frontends-section-
> @section Frontends including browsers
> 
> However, in the output (assuming --split=section) the chapter and ection
> would be merged into a single page, and similar merging in the sidebar and 
> ToC.
> 
> Ideas?  Hacking info.js is something I could do, but it doesn't help for
> traditional info and it doesn't solve the missing entries in the ToC.
> -- 
>       --Per Bothner
> per@bothner.com   http://per.bothner.com/
>