Re: control over sectioning and splitting

[Gavin Smith]

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.

As @section is the next level of section command below @chapter, and @heading
is the equivalent command to @section, it would make more sense to use
@heading instead of @subheading for this.

I think it would be okay to put @headings, @subheadings etc. in the
sidebar, if you wanted to implement this.  This might give a more
consistent experience for users, helping them to navigate within a
page and move between headings.

However, the document might not benefit from having these headings in the
table of contents.  For example, on
https://domterm.org/Frontends.html, the "Qt" section is very short
and not something worthy of the table of contents.

Maybe that is true generally: if you don't want to split a section, it's
possibly that the subsections of that section are insubstantial and not
something that you would want to read on their own, only as part of
the larger section.  So not much is lost if they are omitted from the
table of contents.

If you did want them in the ToC, then @section would be more
appropriate than @heading; however, there would be no way to customize
splitting, as this can't be customized on a node-by-node basis, as
you said in your other mail.  Something would be need to change in
the Texinfo language for this, and this wouldn't appear to be useful
for any output formats other than HTML.  "Splitting" is not a concern
in printed output, where one node follows the other in sequence,
or in Info, where each node is displayed separately.

I don't know how satisfactory this proposal is - how much you really
want all the headings to appear in the ToC - but that is the best idea
I have.

Another idea, which is not ideal: stick with --split=section and demote
the chapter to the level of a section, so that its subsections wouldn't
be output on their own pages.

Another idea: add an option to put @heading in the table of contents
for HTML.  Effectively, treat it the same as @section, except for
the purpose of node-splitting.  (I don't like this idea too much,
as not appearing in the ToC is the main meaning of @heading.)

Another idea is to have an extra splitting option in texi2any to
normally split by sections, but potentially to split at the chapter
level in case a chapter contain sections, but no subsections within
those sections.  (I doubt that this is a good idea, though, as these
sections within a chapter could be both long and short and the author
might still have different preferences within the same manual.)

> 
> 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.
> 
> 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/
>