From 595ad853b831da183581200a31f69fa17fbc5e65 Mon Sep 17 00:00:00 2001 From: Eisenwave Date: Sun, 19 Jul 2026 13:15:48 +0200 Subject: [PATCH 1/2] Add explanation of "in", "of", "names", "denotes", and "designates" --- wording-guidelines.md | 44 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/wording-guidelines.md b/wording-guidelines.md index 8cf33f5870..43dfa41b21 100644 --- a/wording-guidelines.md +++ b/wording-guidelines.md @@ -259,3 +259,47 @@ Avoid unbounded unspecified behavior. > If X happens, the behavior of the program is unspecified. Do not try to make runtime behavior ill-formed; this is a category error. + +### Grammar: "in" vs. "of" + +We use two different prepositions to put parts of the grammar in relation: + +
+
of
+
specifies a direct relationship between syntactical constructs
+ +
in
+
specifies a nested relationship between syntactical constructs
+
+ +**Example:** + + +> the *type-specifier* in the *parameter-declaration* of a *template-parameter* + +This wording is chosen because a *parameter-declaration* +appears directly in the definition of *template-parameter*, +and *type-specifier* is nested several levels deep into *parameter-declaration* +(*type-specifier* → *defining-type-specifier* → *decl-specifier* → *decl-specifier-seq* +→ *parameter-declaration*). + +### "names", "denotes", and "designates" + +There are several words used to describe lookup: + +
+
(to) name
+
means that an entity is looked up by name
+ +
(to) denote ([basic.pre])
+
means to name an entity, but also "sees through" type aliases and namespace aliases
+ +
(to) designate ([basic.splice])
+
means to denote in a splice-specifier what a reflection represents
+
+ +**Example:** +- the *type-specifier* `std::int32_t` names the type alias `std::int32_t` +- the *type-specifier* `std::int32_t` denotes the type `int` or some other signed integer type +- the *splice-specifier* `[: ^^int :]` designates type `int` +- the *splice-specifier* `[: ^^std::int32_t :]` designates the type denoted by `std::int32_t` From d7f6d2bc47e9cce3b5bd26cc790c10af65640161 Mon Sep 17 00:00:00 2001 From: Eisenwave Date: Sun, 19 Jul 2026 14:53:12 +0200 Subject: [PATCH 2/2] Replace old description of "in" and "of", restructure, add some notes --- wording-guidelines.md | 117 +++++++++++++++++++++--------------------- 1 file changed, 59 insertions(+), 58 deletions(-) diff --git a/wording-guidelines.md b/wording-guidelines.md index 43dfa41b21..9e731d5b6d 100644 --- a/wording-guidelines.md +++ b/wording-guidelines.md @@ -192,29 +192,74 @@ violation means non-conformance of the implementation. In the standard library, "shall" establishes a precondition; when violated, the program has undefined behavior. -Do not use "in" when nested constructs are not supposed to be in -scope. - -**Example (bad):** -> X shall not appear in the expression - -covers lambda bodies nested in the expression, which is often undesirable. - Use a recursive definition of a term or phrase to clearly specify how a rule applies to a recursive construct such as an expression or block. -Use "of" to uniquely identify top-level grammar components, without -risk of unwanted recursion. +### "in" vs. "of" + +We use two different prepositions to put parts of the syntax in relation: + +
+
of
+
specifies a direct relationship between constructs
+ +
in
+
specifies a nested relationship between constructs
+
**Example:** -> The _nested-name-specifier_ of a _qualified-id_ ... + + +> the *type-specifier* in the *parameter-declaration* of a *template-parameter* + +This wording is chosen because a *parameter-declaration* +appears directly in the definition of *template-parameter*, +and *type-specifier* is nested several levels deep into *parameter-declaration* +(*type-specifier* → *defining-type-specifier* → *decl-specifier* → *decl-specifier-seq* +→ *parameter-declaration*). + +> [!CAUTION] +> Do not use "in" when nested constructs are not supposed to be in scope. +> +> **Example (bad):** +> > X shall not appear in the expression +> +> covers lambda bodies nested in the expression, which is often undesirable. + +> [!TIP] +> "of" can be chained to describe nested relationships, like +> > *type-specifier* of a *defining-type-specifier* of a *decl-specifier*. + +### "names", "denotes", and "designates" + +There are several words used to describe lookup: + +
+
(to) name
+
means that declarations are found by name
-does not cover any _nested-name-specifier_ nested -within the top-level _nested-name-specifier_. +
(to) denote ([basic.pre])
+
means to name an entity, but also "see through" type aliases and namespace aliases
+ +
(to) designate ([basic.splice])
+
means to denote in a splice-specifier what a reflection represents, +or simply for a name to denote something +(that is, "designate" is universal and works for either case)
+
+ +**Example:** +- the *type-specifier* `std::int32_t` names the type alias `std::int32_t` +- the *type-specifier* `std::int32_t` denotes the type `int` or some other signed integer type +- the *type-specifier* `int` designates type `int` +- the *splice-specifier* `[: ^^int :]` designates type `int` +- the *splice-specifier* `[: ^^std::int32_t :]` designates the type denoted by `std::int32_t` +> [!NOTE] +> The least powerful term should be chosen when in doubt. +> For example, we can say "`T` designates type `int`", but "denotes" is preferred. -## Specific words and phrases +### Specific words and phrases
ill-formed, no diagnostic required
@@ -259,47 +304,3 @@ Avoid unbounded unspecified behavior. > If X happens, the behavior of the program is unspecified. Do not try to make runtime behavior ill-formed; this is a category error. - -### Grammar: "in" vs. "of" - -We use two different prepositions to put parts of the grammar in relation: - -
-
of
-
specifies a direct relationship between syntactical constructs
- -
in
-
specifies a nested relationship between syntactical constructs
-
- -**Example:** - - -> the *type-specifier* in the *parameter-declaration* of a *template-parameter* - -This wording is chosen because a *parameter-declaration* -appears directly in the definition of *template-parameter*, -and *type-specifier* is nested several levels deep into *parameter-declaration* -(*type-specifier* → *defining-type-specifier* → *decl-specifier* → *decl-specifier-seq* -→ *parameter-declaration*). - -### "names", "denotes", and "designates" - -There are several words used to describe lookup: - -
-
(to) name
-
means that an entity is looked up by name
- -
(to) denote ([basic.pre])
-
means to name an entity, but also "sees through" type aliases and namespace aliases
- -
(to) designate ([basic.splice])
-
means to denote in a splice-specifier what a reflection represents
-
- -**Example:** -- the *type-specifier* `std::int32_t` names the type alias `std::int32_t` -- the *type-specifier* `std::int32_t` denotes the type `int` or some other signed integer type -- the *splice-specifier* `[: ^^int :]` designates type `int` -- the *splice-specifier* `[: ^^std::int32_t :]` designates the type denoted by `std::int32_t`