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

Use "this document" instead of "this International Standard" #1389

Closed
Eelis opened this issue Jan 19, 2017 · 13 comments
Closed

Use "this document" instead of "this International Standard" #1389

Eelis opened this issue Jan 19, 2017 · 13 comments

Comments

@Eelis
Copy link
Contributor

Eelis commented Jan 19, 2017

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]:

Valid C++ 2003 code that relies on these functions returning void [..] will fail to compile with this International Standard.

@jensmaurer
Copy link
Member

The sampling I did is less clear. There are four categories:

  • Replace "International Standard" with "document" where we're administratively referring to the document as a body of text, e.g. [intro.scope] (last reference) and [intro.defs].
  • Strike "this International Standard", because we're by default not reaching outside of the standard, e.g. [reentrancy].
  • Leave as-is, because we're contrasting with a different version of C++, e.g. [diff].
  • Leave as-is, because we're contrasting with C, e.g. C headers in clauses 17-30.

Most of the 150 appearances are in the latter two categories.

@jensmaurer
Copy link
Member

@zygoloid, your opinion?

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Jan 19, 2017
@tkoeppe
Copy link
Contributor

tkoeppe commented Jan 19, 2017

What is the worst case if we just stick with the status quo?

@timsong-cpp
Copy link
Contributor

Probably not much. The C++ standard systematically ignores the Directives' prohibition on "hanging paragraphs" (§22.3.3), for instance.

@Eelis
Copy link
Contributor Author

Eelis commented Jan 20, 2017

@timsong-cpp Interesting, can you give an example of a hanging paragraph in the document?

@timsong-cpp
Copy link
Contributor

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

@Eelis
Copy link
Contributor Author

Eelis commented Jan 20, 2017

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.

@timsong-cpp
Copy link
Contributor

timsong-cpp commented Jan 20, 2017

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

@Eelis
Copy link
Contributor Author

Eelis commented Jan 20, 2017

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.

@jensmaurer
Copy link
Member

jensmaurer commented Jan 20, 2017

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

@jensmaurer
Copy link
Member

Editorial meeting consensus: Address the first two categories (Jan 19 comment), conservatively. Leave third and fourth alone.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Mar 2, 2017
zygoloid added a commit that referenced this issue Mar 20, 2017
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.
@jensmaurer
Copy link
Member

Remaining open issue:

  • Strike "this International Standard", because we're by default not reaching outside of the standard, e.g. [reentrancy].

@jensmaurer
Copy link
Member

jensmaurer commented Sep 15, 2017

Addressed by #1732.

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

4 participants