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

Hanging paragraphs vs. warm-up introduction #1771

Open
jensmaurer opened this issue Oct 16, 2017 · 5 comments
Open

Hanging paragraphs vs. warm-up introduction #1771

jensmaurer opened this issue Oct 16, 2017 · 5 comments

Comments

@jensmaurer
Copy link
Member

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 jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Oct 16, 2017
@jensmaurer
Copy link
Member Author

jensmaurer commented Oct 19, 2017

See also #574 and #1730.

@jensmaurer
Copy link
Member Author

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

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

JohelEGP commented Oct 8, 2023

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

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

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

2 participants