Enhance wording guidelines #677
Conversation
| with a focus on core language wording (clauses 2-15). | ||
| targeted at integration into the [ISO C++ Working Draft][draft], | ||
| with a focus on core language wording | ||
| (clauses [[intro.refs]](https://eel.is/c++draft/intro.refs) through |
There was a problem hiding this comment.
eel.is is unofficial; I think I don't want to refer to it in these guidelines at all.
(I'll pick the parts I like for a future update of this document.)
There was a problem hiding this comment.
Perhaps add a disclaimer that the eel.is links are not an endorsement at the beginning? They can still be pretty helpful, and we don't have any way of stable-linking to content within the latest draft.
There was a problem hiding this comment.
I feel we do want less linking and more work for the authors to actually read the Working Draft, as much as possible.
| Use the Oxford (or serial) comma. | ||
|
|
||
| The wording in the C++ Standard adheres to | ||
| [ISO/IEC Principles and rules for the structure and drafting of ISO and IEC documents][iso-principles], |
There was a problem hiding this comment.
The title is ISO/IEC Directives, Part 2, I think. And I'm very hesitant to claim we adhere to it; at the very least, our uses of "shall" are in violation,
There was a problem hiding this comment.
I still think the link is helpful, considering we at least try to follow it. And yeah, I've abbreviated the title a bit and taken just the subtitle.
| When adding a new conversion, also check overload resolution for a | ||
| corresponding adjustment. | ||
| > *Recommended practice*: | ||
| > An implementation should issue a diagnostic when such an operation is executed. |
There was a problem hiding this comment.
"executed" and "diagnostic" is a problem for some; I've taken another example.
There was a problem hiding this comment.
That's okay. Iirc I took that example in particular because it was the first appearance of recommended practice in the draft.
a992f9b to
d1c8b52
Compare
This PR is quite massive and enhances the wording guidelines in both content and presentation.
It also adds numerous relevant cross-references.
You're probably best off taking the new version and looking at it rendered on GitHub. I've verified that some of the more exotic formatting (like
<dl>under "Specific words and phrases") renders as expected on GitHub.