docs: S23.22 style the documentation tables, and stop Core naming a platform - #765
Conversation
…latform The tables were unstyled rather than badly styled: brand.css carried no table rule at all, so Material's defaults ran -- .64rem text with .9375em 1.25em padding, which reads as small type adrift in white space. Bigger text, roughly half the vertical padding, a narrower header minimum. Sized in em, not Material's rem, for the reason the headings in the same file are fixed px: Material scales its rem root with the viewport while .md-typeset pins body text at 16px, so a rem table outgrows the prose around it on a wide monitor. Long identifiers were breaking mid-token because a hyphen is a wrap opportunity, not because of any word rule. Fixed on the code span rather than the cell -- most first cells are prose, or prose mixed with code, and those must still wrap at their spaces -- and scoped to the first column, because a later one can carry a long unbroken run such as the SPDX licence expression. Separately, the BlockStore threshold callback offered one platform's buffer as the way to avoid re-entering Log. The hazard is Core's to state; the example was not, and the eleventh platform would never have been added to it. Part of #708
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
WalkthroughThe change updates one documentation line in ChangesThreshold callback documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Mergeability Score: ⚪ Minimal · up to This PR only adjusts documentation table styling and clarifies a public header comment; the reported checks pass, and no actionable merge-blocking risk remains. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
☀️ Quality Summary Created by Quality Monitor v4.15.0 (#82d77af). More details are shown in the GitHub Checks Result. |
1 participant
Purpose
Part of #708. The table presentation raised on seeing the built site — too much
white space, text too small, long identifiers badly wrapped — plus the last
finding from the narrowed Batch 6 comment pass.
Change Description
Tables.
brand.csscarried no table rule at all, so this was unstyled ratherthan badly styled and Material's defaults were running:
.64remtext with.9375em 1.25empadding. Now0.9emtext,0.5em 0.8empadding,4remheaderminimum, and code set at
.85emso an identifier column is no wider than it needsto be. Chosen by comparing rendered variants of a real table on the built site,
not by picking numbers.
Two decisions worth recording, both visible in the CSS comments:
Sized in
em, not Material'srem. Material scales its rem root with theviewport — 125%, 137.5% past 100em, 150% past 125em — while
.md-typesetpinsbody text at a fixed 16px. A rem-sized table therefore renders 14.4px, 15.8px or
17.3px depending on window width, and on a wide monitor is larger than the prose
around it. At
0.9emit is 14.4px at every width. This is the same trap theheadings and the logo in that file already document, and they resolved it the same
way.
The wrap fix is on the code span, not the cell. Identifiers were breaking
mid-token because a hyphen is a wrap opportunity, not because of any word
rule.
white-space: nowrapon the first cell would have been wrong: 145 of the285 first cells in the documentation are multi-word or mixed, so the majority
would have become one long unwrappable line. Scoped to the code span, a lone
identifier stays whole while prose still wraps at its spaces. Scoped to the first
column, because a later column can carry a long unbroken run — the SPDX licence
expression in
security/sbom.mdis one.SolidSyslogBlockStore.h. The threshold-callback gotcha offeredSolidSyslogPosixMessageQueueBufferas the way to avoid re-enteringLog. Thehazard is Core's to state, but naming one platform's buffer as the example is the
coupling we do not allow: the eleventh platform never gets added to that list.
"A Buffer that returns rather than sending inline" already says it.
Test Evidence
mkdocs build --strictexit 0.a large monitor and on mobile, across
ci.mdand a selection of othertable-heavy pages. The scratch comparison page and its
page_descriptions.pyentry were deleted once the numbers were settled; neither is in this branch.
clang-format --dry-run --Werroron the changed header: clean. The edit iscomment-only and line-count neutral, so
misra_suppressions.txtis unaffectedand no renumber was needed.
Areas Affected
docs/assets/stylesheets/brand.css— affects every table on the published site.One comment-only change to a public header, which changes its generated API page.
No production logic changes.
Summary by CodeRabbit
Bufferreference instead of a specific implementation example.