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

Avoid hanging paragraphs as well as 'in general' / 'overview' subclauses #574

Closed
zygoloid opened this issue Dec 5, 2015 · 12 comments
Closed
Labels
big An issue causing a large set of changes, scattered across most of the text.
Milestone

Comments

@zygoloid
Copy link
Member

zygoloid commented Dec 5, 2015

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.

@tkoeppe
Copy link
Contributor

tkoeppe commented Dec 5, 2015

Would it be possible to assign multiple stable lables to a heading? Then we could have, say, "Diagnostics library [diagnostics, diagnostics.general]".

@zygoloid
Copy link
Member Author

zygoloid commented Dec 8, 2015

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.

@zygoloid
Copy link
Member Author

zygoloid commented Dec 8, 2015

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.

@AlisdairM
Copy link
Contributor

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.

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Dec 7, 2016
@jensmaurer
Copy link
Member

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?

@tkoeppe
Copy link
Contributor

tkoeppe commented Dec 8, 2016

@jensmaurer: Printed books, lecture notes, commit messages, ...

@jensmaurer
Copy link
Member

jensmaurer commented Dec 8, 2016

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.

@jensmaurer
Copy link
Member

jensmaurer commented Feb 8, 2017

The ISO Directives part 2 http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf say in 22.3.3:

"Hanging paragraphs" such as those shown in Figure 4 shall be avoided since reference to them is ambiguous.

(With "hanging paragraphs, they mean text under a section's heading where that section has subsections.)

@jensmaurer
Copy link
Member

I believe some of the core clauses could benefit from introducing an additional subsection, e.g. the front matter in clause 5 [expr].

@jensmaurer jensmaurer added this to the C++20 milestone Mar 2, 2017
@jensmaurer
Copy link
Member

Editorial meeting consensus: Incrementally move towards removal of "hanging paragraphs". Do not call them "in general" or similar; keep the heading meaningful.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Mar 2, 2017
@jensmaurer jensmaurer changed the title consider removing 'in general' / 'overview' subclauses consider removing 'in general' / 'overview' subclauses208 Mar 31, 2017
@jensmaurer jensmaurer changed the title consider removing 'in general' / 'overview' subclauses208 consider removing 'in general' / 'overview' subclauses Apr 20, 2017
@jensmaurer jensmaurer changed the title consider removing 'in general' / 'overview' subclauses Avoid hanging paragraphs as well as 'in general' / 'overview' subclauses Oct 6, 2017
@jensmaurer jensmaurer added the big An issue causing a large set of changes, scattered across most of the text. label Sep 27, 2019
@zygoloid zygoloid modified the milestones: C++20, C++23 Mar 12, 2020
@JohelEGP
Copy link
Contributor

When avoiding hanging paragraphs, look out for "this subclause", which should be replaced with "subclause [parent.subclause]". See #3354 and #4123 (comment).

@jensmaurer
Copy link
Member

Hanging paragraphs were bulk-fixed by introducing "General" subclauses, addressing ISO/CS comments on the C++20 DIS.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
big An issue causing a large set of changes, scattered across most of the text.
Projects
None yet
Development

No branches or pull requests

5 participants