Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Process: final page-by-page review #4219

Closed
tkoeppe opened this issue Sep 17, 2020 · 9 comments
Closed

Process: final page-by-page review #4219

tkoeppe opened this issue Sep 17, 2020 · 9 comments
Milestone

Comments

@tkoeppe
Copy link
Contributor

tkoeppe commented Sep 17, 2020

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
Copy link
Contributor Author

tkoeppe commented Sep 17, 2020

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
Copy link
Contributor Author

tkoeppe commented Sep 17, 2020

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

Remedial actions? Discuss.

@tkoeppe
Copy link
Contributor Author

tkoeppe commented Sep 17, 2020

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
Copy link
Contributor Author

tkoeppe commented Sep 17, 2020

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
Copy link
Member

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
Copy link
Member

zygoloid commented Sep 18, 2020

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
Copy link
Contributor Author

tkoeppe commented Sep 18, 2020

@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.

@zygoloid zygoloid transferred this issue from cplusplus/nbballot Sep 21, 2020
@zygoloid zygoloid added this to the C++20 milestone Sep 21, 2020
@tkoeppe
Copy link
Contributor Author

tkoeppe commented Sep 22, 2020

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

@zygoloid
Copy link
Member

zygoloid commented Oct 5, 2020

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.

@zygoloid zygoloid closed this as completed Oct 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants