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

[zygoloid]

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]

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

[zygoloid]

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]

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]

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]

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]

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

[jensmaurer]

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]

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]

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

[jensmaurer]

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