Some documentation pages are unexpectedly blank

[inetknght]

Version of Beast

it seems all versions

Steps necessary to reproduce the problem

Small documentation issue.

Main documentation page [master, 1.78.0, 1.68.0] -> see "HTTP Examples" or "More Examples" with subitems. Click it.
HTTP Examples documentation page [master, 1.78.0, 1.68.0] -> empty page. I would expect the subitems on the previous page to be listed here

I did a small amount of digging. It looks like HTTP Examples page is generated from this QBK? I see the text These examples in this section are working functions that may be found in the examples directory. They demonstrate the usage of the library for a variety of scenarios. is there and additional text describing each sub item. But I am not familiar with QBK to diagnose why the page is empty.

It seems some other sections are similarly empty. The Concepts 1.78.0 page is similarly empty as is the 1.78.0 Configuration page. The 1.78.0 Quick Look page is empty -- but it at least links to the example directory listing even if it doesn't describe which examples do what.

Other sections appear to be correctly filled out. For example, the 1.78.0 WebSockets section has content.

It looks like the WebSocket section QBK mentions only a single section (with notes, headings, tables, includes, etc) and links to other sections while the HTTP Examples QBK has multiple sections.

[vinniefalco]

The page is empty because its a new section I guess, press the "Next" button on that mostly blank page (the right arrow)

[sehe]

The settings for section chunking with HTML output are in doc/Jamfile:

  <xsl:param>chunk.section.depth=8                # Depth to which sections should be chunked
  <xsl:param>chunk.first.sections=1               # Chunk the first top-level section?
  <xsl:param>toc.section.depth=8                  # How deep should recursive sections appear in the TOC?
  <xsl:param>toc.max.depth=8                      # How many levels should be created for each TOC?
  <xsl:param>generate.section.toc.level=8         # Control depth of TOC generation in sections

See also https://boostorg.github.io/quickbook/doc/html/boost_doc_tools/parameters.html

Changing to chunk.first.sections=0 is too invasive (and would e.g. lead to the quick reference appearing on the same page as the TOC).

Chunking (splitting to separate HTML pages) can be disabled locally:

[block'''<?dbhtml stop-chunking?>''']

Indeed including that leads to the first example appearing on the "more_examples.htm" page, while subsequent sections still appear on their own individual pages. I'd say we want to do this change:

[sehe]

Mmm. Sadness:

1. I was potentially too quick. Apparently the behaviour I described was only at partial rendered documentation, after completing the local rendering, all the "More HTTP Examples" appeared on a single page, which is not what we wanted
2. The "Quick Start" (1_quick_look.qbk) appeared to have this stop-chunking directive but with a typo. "Fixing" the typo sadly shows the same behaviour of squashing all descendant sections to the single HMTL:
   

The best I think we could do, then, is manually create some placeholder context on the main section page, perhaps with a bespoke hyperlink that duplicates what the "Next" button does in context...

[vinniefalco]

Yeah its not perfect..

[alandefreitas]

We tried to fix that before. I don't even remember in what library.

IIRC, the problem is we can't control the TOC depth for individual sections and the reference has subsections that look bad in the TOC.

If that's the case, the best solution would be to adapt docca to generate a document hierarchy that looks betters in the TOC.

[sehe]

I reckon it would be nice if we could include "local" TOCs on page currently empty-ish

…

On Wed, Jul 13, 2022, at 10:01 PM, Alan de Freitas wrote: We tried to fix that before. I don't even remember in what library. IIRC, the problem is we can't control the TOC depth for individual sections and the reference has subsections that look bad in the TOC. If that's the case, the best solution would be to adapt docca to generate a document hierarchy that looks betters in the TOC. — Reply to this email directly, view it on GitHub <#2483 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACPEAIVVMX6E7ELY6EG7L3VT4OATANCNFSM53PBWVXQ>. You are receiving this because you commented.Message ID: ***@***.***>

[inetknght]

Yes, I think it would be good enough to have a local TOC with the subitems from the parent page and a link back to the parent page.

As-is, if I copy the link from the main page and send it to a colleage, then the colleage could be lost because there's no information on the page linked and navigation by icons in the top right isn't clear (no text) and, when they opened the direct link, they can't just press the browser's back button to work from the parent page. So having the local TOC would help to navigate around the documentation.

[alandefreitas]

Just as a reference, this is what happens when we remove the blank page: