Process: final page-by-page review

[tkoeppe]

This is a tracking issue to discuss the various steps we should perform duing the final review.

Once we agree on the set of steps, I would like to add them to the editorial wiki.

Let's begin with the context:

One of the last steps before we send the final PDF to ISO is to review the candidate document page-by-page to look for "glaring errors". This shouldn't require close attention to the text, but instead focus on the overall presentation. As such, this should be relatively quick, with only a few seconds spent on each page. If we share the workload, then this is best done along Clause boundaries for vertical reasons.

The goal is to make the document look as nice as possible, and at this stage we can use one-shot changes that do not need to be sustainable and that will not be carried forward into the main branch. The main tool of this nature is adding explicit page breaks.

I will post one comment for each individual step.

[tkoeppe]

Gross errors. Make sure the body of the page stays within its boundaries. Occasionally we have long tables that flow off the page. This can be done quickly by, say, viewing the entire page at once (i.e. at a suitably small zoom level).

[tkoeppe]

Multi-page footnotes. Footnotes should ideally not span multiple pages.

Remedial actions? Discuss.

[tkoeppe]

Modal verb review. Check whether footnotes contain bad words. See e.g. cplusplus/nbballot#393 (comment).

@jensmaurer, @zygoloid could you elaborate what exactly we want to avoid in footnotes? "Might" and "could"?

Jens:

We want to avoid in footnotes those verbs that we also want to avoid in notes, i.e. "may", "shall", "should". It's probably best to extend check.sh with some footnote detection. "Must" needs individual review, but seems inappropriate for footnotes.

[tkoeppe]

Orphans and widows. If there is too little of a new section starting at the bottom of a page, consider breaking the page before, subject to not increasing the overall page count. Use discretion; the goal is to make the overall product look tidier and less distracting than what LaTeX generates by default. (Yes, orphan/widow tolerances can be configured, but I'd like to keep the defaults as they are and only intervene when it is affordable.)

[jensmaurer]

We want to avoid in footnotes those verbs that we also want to avoid in notes, i.e. "may", "shall", "should". It's probably best to extend check.sh with some footnote detection. "Must" needs individual review, but seems inappropriate for footnotes.

Orphans and widows: A few years ago, I spent quite a lot of time to tune the page breaks by modifying the listings package (prefer page breaks at empty lines) and properly gluing headings to the subsequent text. The page breaks should therefore be mostly fine; if we need to add more than, say, 10 manual page breaks, we should revisit the page break configuration for C++23.

[zygoloid]

Mid-sentence notes and examples. Now that notes and examples induce paragraph breaks, it's entirely inappropriate for them to occur within a sentence. Fix by moving the note or example out of the sentence as suitable.

[tkoeppe]

@jensmaurer: re orphans/widows: Sorry, I was unclear: I don't mean literal one-line cases, which LaTeX already handles. I mean the slightly more discretionary cases where it's, say, a heading followed by two lines, which isn't an orphan in the strict sense, but making the page break before the heading manually would still improve the overall look. This might require a bit of trial-and-error to see what the follow-on effects are.

I'll edit your clarification for modal verbs into the main comment.

[tkoeppe]

Hanging paragraphs. We no longer tolerate these. If you find any, also notify #4170 so we can update the detection logic.

[zygoloid]

I've done one final pass; final proofing done and fixes applied (some taken from Dawn's #4275). With that, I think we're done with C++20.