beast
beast copied to clipboard
boostorg
Some documentation pages are unexpectedly blank
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.
The page is empty because its a new section I guess, press the "Next" button on that mostly blank page (the right arrow)
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:
Mmm. Sadness:
- 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
- The "Quick Start" (1_quick_look.qbk) appeared to have this
stop-chunkingdirective 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...
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.
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 https://github.com/boostorg/beast/issues/2483#issuecomment-1183623516, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACPEAIVVMX6E7ELY6EG7L3VT4OATANCNFSM53PBWVXQ. You are receiving this because you commented.Message ID: @.***>
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.
Just as a reference, this is what happens when we remove the blank page:
