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
Use "this document" instead of "this International Standard" #1389
Comments
The sampling I did is less clear. There are four categories:
Most of the 150 appearances are in the latter two categories. |
@zygoloid, your opinion? |
What is the worst case if we just stick with the status quo? |
Probably not much. The C++ standard systematically ignores the Directives' prohibition on "hanging paragraphs" (§22.3.3), for instance. |
@timsong-cpp Interesting, can you give an example of a hanging paragraph in the document? |
@Eelis [basic]/1-9, for instance. (Their definition of "hanging paragraph" is really weird. You pretty much have to look at the example in the Directives to see what they mean - basically any paragraph in a non-leaf subclause is "hanging".) |
Ahh, I see, thanks! So that convention lets you say "3.4" to refer to paragraph 4 of section 3 without having to worry about there possibly also being a subsection 3.4 (because the convention prevents such ambiguity). I would say the justification for ignoring that rule is that C++ has a tradition of only using periods for subsections, and using "3p4" or "3/4" or "3#4" to refer to paragraph 4 of section 3. I think it's probably best to only ignore rules when we have a concrete justification like that. |
@Eelis Paragraphs are supposed to be unnumbered (§6.1, Table 1 - so yet another place where we ignore the Directives systematically). The "hanging paragraph" rule is intended to ensure that we do not have to write a reference to, for example, (the entire) Clause 5 [expr] when we really mean to only reference something in the front matter (like the note in [dcl.decomp]/1). |
Wow, now I wonder how other ISO standards cope with not having paragraph numbers. They're so useful! Also, perhaps it would be good to make a list of all the Directives' rules that are knowingly ignored, along with the justification. Could make it part of the "Specification Style Guidelines" wiki page. |
@timsong-cpp: Yes, paragraphs are supposed to be unnumbered --- and our in-standard cross-references don't mention paragraph numbers. So just ignore the random black dots in the margins of the C++ standard, and you're good. Regarding "hanging paragraphs": I think I agree with the rationale in the ISO directives here, and the example in [dcl.decomp]p1 (and similar like it) are indeed disconcerting. My opinion is that those "hanging paragraphs" should only have introductory material without normative impact (maybe in a note for consistency), and everything else should go into a leaf subsection. This way, there is never a need to refer to the material in the hanging paragraph in normative references. Most of the core language sections are fairly bad offenders in that regard, and need rework. |
Editorial meeting consensus: Address the first two categories (Jan 19 comment), conservatively. Leave third and fourth alone. |
places where it is a clear improvement. The 7th Edition of the ISO Directives no longer require us to use "this International Standard" when the document refers to itself. We retain that phrasing when the reference is to the abstract notion of the specification as opposed to the text embodying it. This is a step towards addressing #1389.
Remaining open issue:
|
Addressed by #1732. |
Version 7.0 of the ISO/IEC Directives Part 2 (section 10.6) introduces "this document" as the new and improved way for documents to refer to themselves, replacing the wearisome "this International Standard".
Going over occurrences of "this International Standard" in the document, it seems to me that almost all of them would be improved by the replacement, but there are some cases where the change results in dubious phrasing. For example, [diff.cpp03.containers]:
The text was updated successfully, but these errors were encountered: