Hanging paragraphs vs. warm-up introduction

[jensmaurer]

The ISO Directives, Part 2, require us to get rid of hanging paragraphs.

One sub-issue is that we sometimes have introductory warm-up sentences at the start of a clause or subclause. Occasionally, these are "note"s, making clear their non-normative character. On other occasions (e.g. [constraints.overview]), they are not. Sometimes those warm-up sentences are in a separate subclause "overview", sometimes they form "hanging paragraphs" (often together with normative material).

This issue serves as an anchor to discuss a uniform approach to dealing with these warm-up sentences. Ideas:

• Always put warm-up descriptions into a separate "overview" section (helps avoiding hanging paragraphs).
• Always make warm-up sentences a note.
• Find a differing typographical convention.
• Add warm-up overviews to subclauses which don't have them (yet).

[jensmaurer]

See also #574 and #1730.

[jensmaurer]

Editorial meeting consensus: There are several different situations that warrant different treatment.

• Hanging paragraphs containing substantial normative wording (e.g. Clause 8 [expr]): Reconsider the clause structure in its entirety, move the hanging paragraphs into fresh subclauses, properly structuring the contents. For [expr], have "Properties of expressions" (with more specific subclauses), "Kinds of expressions" (current grammar tree), "Constant expressions".
• Non-normative introductory text as well as (short) normative snippets (e.g. defining a term or similar) should go into a "Preamble" subclause. Use the usual "note" mechanism for non-normative content. (Note: @tkoeppe opposes having a third way of identifying non-normative content (e.g. bars on the side or indentation or similar).) Start a new paragraph once normative content begins. Never mark an entire subclause as "informative".
• Non-normative paraphrase of the contained subclause headings: Delete.
• Having a short paragraph of non-normative introduction before a grammar snippet or a class synopsis is fine. In particular, 23.2.1p1 should be above the synopsis; merge 23.2p1, which also goes before the synopsis; mark as non-normative.

[jensmaurer]

Hanging paragraphs were summarily fixed by addressing an ISO/CS comment on DIS C++20. Keeping open to possibly reconsider the details of the new structure.

[JohelEGP]

• Non-normative introductory text as well as (short) normative snippets (e.g. defining a term or similar) should go into a "Preamble" subclause. Use the usual "note" mechanism for non-normative content. (Note: @tkoeppe opposes having a third way of identifying non-normative content (e.g. bars on the side or indentation or similar).) Start a new paragraph once normative content begins. Never mark an entire subclause as "informative".

https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-informative mentions

Unless there is a clear requirement (“shall”) or imperative language in the text, all document content is informative by default.

[jensmaurer]

@JohelEGP , the "house style" is not as binding as the ISO Directives, Part 2, and we're not generally following the house style. At the very least, due to historical reasons (our standard is much older than the house style).

As you should know, we traditionally use "shall" for requirements on the user and normal mood ("is") for requirements on the implementation, which is usually in the cases where we simply specify the C++ language and expect implementations to implement its rules.