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
Avoid hanging paragraphs as well as 'in general' / 'overview' subclauses #574
Comments
Would it be possible to assign multiple stable lables to a heading? Then we could have, say, "Diagnostics library [diagnostics, diagnostics.general]". |
We could have a mapping from old labels to new labels in Annex F. I'd rather keep the legacy stuff out of the main text if possible. |
The core language section actually does have a handful of these sections: [expr.prim.general] (which is a horrible mishmash that should be divided into subsections), [dcl.fct.def.general], [dcl.attr.grammar], [lex.literal.kinds], and perhaps [basic.scope.declarative]. [basic.start] also contains no text, but there's not really anything for it to say, so it should remain as-is. |
I believe this is inspired by Pete Becker's time as the editor. There was an understanding that ISO rules for documents required text could only occur in 'leaf' nodes of the [a.b.c] tree, and while our standard clearly violated that rule all over, there was an attempt to bring it closer to conformance. If that rule/convention has since been rescinded, there could be an argument for simplifying out the empty tags again. |
I think the section label issue should work out. We can certainly fix all references in the standard and in the LWG issues list. Are there large quantities of references elsewhere? |
@jensmaurer: Printed books, lecture notes, commit messages, ... |
We have 39 section labels with ".general". We have 28 references to such sections, with a substantial chunk referring to [iterator.requirements.general] and [containers.requirements.general]. Both sections contain much more than introductory material and should not be folded in any event. I think this is evidence that we don't actually refer to the "in general" sections in the standard. And that experience matches their normative content, which approximates zero. I've got a hard time imagining that external material would refer to these "in general" sections. |
The ISO Directives part 2 http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf say in 22.3.3:
(With "hanging paragraphs, they mean text under a section's heading where that section has subsections.) |
I believe some of the core clauses could benefit from introducing an additional subsection, e.g. the front matter in clause 5 [expr]. |
Editorial meeting consensus: Incrementally move towards removal of "hanging paragraphs". Do not call them "in general" or similar; keep the heading meaningful. |
When avoiding hanging paragraphs, look out for "this subclause", which should be replaced with "subclause [parent.subclause]". See #3354 and #4123 (comment). |
Hanging paragraphs were bulk-fixed by introducing "General" subclauses, addressing ISO/CS comments on the C++20 DIS. |
Within the library, it's relatively common for a clause with subclauses to contain no other content. The content that would most naturally be directly included in that clause is instead in a subclause named "General" or "In general" or " overview".
These additional clauses seem to be without merit, and are inconsistent (as the core language doesn't use them, and the library doesn't consistently use them either). We should consider removing them and folding the content into the containing clause.
Removing a clause and its corresponding section label is not something that should be done lightly, since people use the section labels as stable names for the corresponding content, so this would need some care. We might want to keep the subclause section labels and discard the labels that used to have no content, to avoid breaking too many external references to particular paragraphs, even though that will leave us with somewhat bizarre section labels in some cases.
The text was updated successfully, but these errors were encountered: