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 > p...@bothner.com http://per.bothner.com/ >
