Skip to content

\defnc and \defna #3880

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.

Sign up for GitHub

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

\defnc and \defna #3880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6c11f0
Replace \defnx{a}{a!b} with new \defnc{a}{b}
opensdh Mar 16, 2020
9b0f64a
Replace \defnx{a}{b!a} with new \defna{a}{b}
opensdh Mar 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions source/basic.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -833,7 +833,7 @@
\pnum
For a given declarative region \placeholder{R}
and a point \placeholder{P} outside \placeholder{R},
the set of \defnx{intervening}{region!declarative!intervening} declarative regions
the set of \defna{intervening}{region!declarative} declarative regions
Copy link
Member

@zygoloid zygoloid Mar 17, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this be \defnadjx{intervening}{declarative regions}{region!declarative}? Similar question for various other uses of \defna below.

Copy link
Contributor Author

@opensdh opensdh Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you use ! in the third argument to \defnadjx (i.e., in the see{} in \indextext)?

Copy link
Member

@zygoloid zygoloid Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we'd need some magic to turn !s into , s. I don't know if \see does that for us but it seems relatively straightforward to build.

Copy link
Member

@zygoloid zygoloid Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That said, should we really be indexing "declarative region" under "region" rather than under "declarative region" in the first place?

Copy link
Contributor Author

@opensdh opensdh Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We provide "a b, see b, a" because it's standard to look up "noun, adjective", so maybe people do look for "region, declarative" even though the generic word "region" is not useful here? (I also haven't checked to see whether the other uses of \defna are "misuses" like this.)

Copy link
Member

@zygoloid zygoloid Mar 24, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, we don't have index entries for "binding, structured" or "operand, unevaluated". I think that's somewhat appropriate: these aren't "adjective noun" so much as an atomic noun phrase.

I think the right thing here is:

  • This should be \defnadj{intervening}{declarative region}
  • The "region, declarative" index entry should be changed to say "see declarative region" so that it points to this index sub-entry

Copy link
Contributor Author

@opensdh opensdh Mar 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean \defnadjx{intervening}{declarative regions}{declarative region} for this case, right? And are you saying that (\defnadj and) \defnadjx should be changed to always index adjective noun and generate a see for noun, adjective?

between \placeholder{P} and \placeholder{R}
comprises all declarative regions
that are or enclose \placeholder{R} and do not enclose \placeholder{P}.
Expand Down Expand Up @@ -2863,7 +2863,7 @@
\end{example}
As a consequence of these rules,
all declarations of an entity are attached to the same module;
the entity is said to be \defnx{attached}{attached!entity} to that module.
the entity is said to be \defnc{attached}{entity} to that module.
Copy link
Member

@zygoloid zygoloid Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe \defnctx; this is really the same thing as \defncontext but for an inline definition rather than a Terms and Definitions definition, so using a similar macro seems reasonable.

Copy link
Contributor Author

@opensdh opensdh Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, the syntax is a bit different, but you're right about the parallel. Do you have a suggestion for \defna?

Copy link
Member

@zygoloid zygoloid Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well... should \defna{x}{y} be an alias for \defnadjx{x}{}{y}? (I think we probably always want the see entry, so I'm inclined to say yes.) If so, perhaps we could use \defnadjx{x}{}{y} directly rather than introducing a new macro?

Copy link
Contributor Author

@opensdh opensdh Mar 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

\defnadjx{x}{}{y} renders as "x ", which would be problematic at least if punctuation follows. I'm sure we could teach it to not do so; maybe #1 #2\unskip would be enough.

Copy link
Member

@zygoloid zygoloid Mar 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another idea for \defnctx: use an optional argument: \defn[entity]{attached}. That seems pretty clean. Although now I come to think of it, that might instead be a nice way to get rid of the \...x macros instead.

Maybe:

  • \defnx{bodytext}{indextext} -> \defn[indextext]{bodytext}
  • \defnc{bodytext}{indexgroup} -> \defnctx[indexgroup]{bodytext}
  • \defnadjx{bodyadj}{bodynoun}{indexnoun} -> \defnadj{bodyadj}[indexnoun]{bodynoun}
  • \defna{bodyadj}{indexnoun} -> \defnadj{bodyadj}[indexnoun]{}
    ? (Leaving room for \defnadj[indexadj]{bodyadj}{bodynoun} if we ever want that.)

General idea: the text in braces always appears in the document; the text in brackets is only used to form the index entry.

What do you think?

Copy link
Contributor Author

@opensdh opensdh Mar 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, that seems like an improvement: fewer magic names and less in the way of argument-order guesswork. \newcommand supports only leading optional arguments, but we could certainly use a raw \def for your first \defnadj. We still have to deal with emitting a space only if the bodynoun is non-empty. I don't immediately know how to support optional arguments in two different places, but I'm sure something like \expandafter can be used to do it if it ever matters.

Copy link
Member

@zygoloid zygoloid Sep 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a standard trick for an optional argument after a mandatory argument: \defnadj would be a two-parameter command with an optional argument that saves its arguments in some scratch space then expands to another two-parameter command with an optional argument.


\pnum
\indextext{consistency!type declaration}%
Expand Down Expand Up @@ -2934,7 +2934,7 @@
\end{note}

\pnum
An entity is \defnx{TU-local}{TU-local!entity} if it is
An entity is \defnc{TU-local}{entity} if it is
\begin{itemize}
\item
a type, function, variable, or template that
Expand Down Expand Up @@ -2966,7 +2966,7 @@
\end{itemize}

\pnum
A value or object is \defnx{TU-local}{TU-local!value or object} if either
A value or object is \defnc{TU-local}{value or object} if either
\begin{itemize}
\item
it is, or is a pointer to,
Expand Down Expand Up @@ -4246,8 +4246,8 @@
Every alignment value shall be a non-negative integral power of two.

\pnum
Alignments have an order from \defnx{weaker}{alignment!weaker} to
\defnx{stronger}{alignment!stronger} or \defnx{stricter}{alignment!stricter} alignments. Stricter
Alignments have an order from \defna{weaker}{alignment} to
\defna{stronger}{alignment} or \defna{stricter}{alignment} alignments. Stricter
alignments have larger alignment values. An address that satisfies an alignment
requirement also satisfies any weaker valid alignment requirement.

Expand Down Expand Up @@ -5107,7 +5107,7 @@
floating-point operations; see also~\ref{support.limits}.
\end{note}
Integral and floating-point types are collectively
called \defnx{arithmetic}{type!arithmetic} types.
called \defna{arithmetic}{type} types.
\indextext{\idxcode{numeric_limits}!specializations for arithmetic types}%
Specializations of the standard library template
\tcode{std::numeric_limits}\iref{support.limits} shall specify the
Expand Down
24 changes: 12 additions & 12 deletions source/classes.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1222,7 +1222,7 @@
\pnum
A defaulted special member function is
\indextext{member function!constexpr-compatible}%
\defnx{constexpr-compatible}{constexpr-compatible!defaulted special member function}
\defnc{constexpr-compatible}{defaulted special member function}
if the corresponding implicitly-declared special member function
would be a constexpr function.

Expand Down Expand Up @@ -1393,7 +1393,7 @@

\pnum
A default constructor is
\defnx{trivial}{constructor!default!trivial}
\defna{trivial}{constructor!default}
if it is not user-provided and if:
\begin{itemize}
\item
Expand All @@ -1412,13 +1412,13 @@
\end{itemize}

Otherwise, the default constructor is
\defnx{non-trivial}{constructor!default!non-trivial}.
\defna{non-trivial}{constructor!default}.

\pnum
A default constructor
that is defaulted and not defined as deleted
is
\defnx{implicitly defined}{constructor!implicitly defined}
\defna{implicitly defined}{constructor}
when it is odr-used\iref{basic.def.odr}
to create an object of its class type\iref{intro.object},
when it is needed for constant evaluation\iref{expr.const}, or
Expand Down Expand Up @@ -2017,7 +2017,7 @@
\end{itemize}
\indextext{assignment operator!move!non-trivial}%
otherwise the copy/move assignment operator is
\defnx{non-trivial}{assignment operator!copy!non-trivial}.
\defna{non-trivial}{assignment operator!copy}.

\pnum
\indextext{assignment operator!copy!implicitly defined}%
Expand Down Expand Up @@ -2237,7 +2237,7 @@
\end{itemize}

Otherwise, the destructor is
\defnx{non-trivial}{destructor!non-trivial}.
\defna{non-trivial}{destructor}.

\pnum
A defaulted destructor is a constexpr destructor
Expand All @@ -2247,7 +2247,7 @@
A destructor
that is defaulted and not defined as deleted
is
\defnx{implicitly defined}{destructor!implicitly defined}
\defna{implicitly defined}{destructor}
when it is odr-used\iref{basic.def.odr}
or when it is explicitly defaulted after its first declaration.

Expand Down Expand Up @@ -3112,7 +3112,7 @@

\pnum
In a union,
a non-static data member is \defnx{active}{active!union member}
a non-static data member is \defnc{active}{union member}
if its name refers to an object
whose lifetime has begun and has not ended\iref{basic.life}.
At most one of the non-static data members of an object of union type
Expand Down Expand Up @@ -3886,7 +3886,7 @@

\pnum
The return type of an overriding function shall be either identical to
the return type of the overridden function or \defnx{covariant}{return type!covariant} with
the return type of the overridden function or \defna{covariant}{return type} with
the classes of the functions. If a function \tcode{D::f} overrides a
function \tcode{B::f}, the return types of the functions are covariant
if they satisfy the following criteria:
Expand Down Expand Up @@ -6693,7 +6693,7 @@
A comparison operator function for class \tcode{C} that
is defaulted on its first declaration and
is not defined as deleted is
\defnx{implicitly defined}{operator!comparison!implicitly defined}
\defna{implicitly defined}{operator!comparison}
when it is odr-used or needed for constant evaluation.
Name lookups in the defaulted definition
of a comparison operator function
Expand All @@ -6713,7 +6713,7 @@

\pnum
A binary operator expression \tcode{a @ b} is
\defnx{usable}{usable!binary operator expression}
\defnc{usable}{binary operator expression}
if either

\begin{itemize}
Expand All @@ -6730,7 +6730,7 @@
\pnum
A defaulted comparison function is
\indextext{operator!comparison!constexpr-compatible}%
\defnx{constexpr-compatible}{constexpr-compatible!defaulted comparison operator}
\defnc{constexpr-compatible}{defaulted comparison operator}
if it
satisfies the requirements for a constexpr function\iref{dcl.constexpr} and
no overload resolution
Expand Down
2 changes: 1 addition & 1 deletion source/concepts.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
\rSec1[concepts.equality]{Equality preservation}

\pnum
An expression is \defnx{equality-preserving}{expression!equality-preserving} if,
An expression is \defna{equality-preserving}{expression} if,
given equal inputs, the expression results in equal outputs. The inputs to an
expression are the set of the expression's operands. The output of an expression
is the expression's result and all operands modified by the expression.
Expand Down
12 changes: 6 additions & 6 deletions source/declarations.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4623,7 +4623,7 @@
\end{note}

\pnum
The \defnx{elements}{aggregate!elements} of an aggregate are:
The \defna{elements}{aggregate} of an aggregate are:
\begin{itemize}
\item
for an array, the array elements in increasing subscript order, or
Expand All @@ -4638,7 +4638,7 @@
as specified in~\ref{dcl.init.list},
the elements of the initializer list are taken as initializers
for the elements of the aggregate.
The \defnx{explicitly initialized elements}{explicitly initialized elements!aggregate}
The \defnc{explicitly initialized elements}{aggregate}
of the aggregate are determined as follows:
\begin{itemize}
\item
Expand Down Expand Up @@ -5996,7 +5996,7 @@
\grammarterm{function-body}
is of the form
\tcode{= default ;}
is called an \defnx{explicitly-defaulted}{definition!function!explicitly-defaulted} definition.
is called an \defna{explicitly-defaulted}{definition!function} definition.
A function that is explicitly defaulted shall
\begin{itemize}
\item be a special member function or
Expand Down Expand Up @@ -6241,7 +6241,7 @@

\pnum
\indextext{promise type|see{coroutine, promise type}}%
The \defnx{promise type}{coroutine!promise type} of a coroutine is
The \defna{promise type}{coroutine} of a coroutine is
\tcode{std::coroutine_traits<R, P$_1$, $\dotsc$, P$_n$>::promise_type},
where
\tcode{R} is the return type of the function, and
Expand Down Expand Up @@ -6338,7 +6338,7 @@
of a coroutine handle\iref{coroutine.handle}
that refers to the coroutine.
The function that invoked a resumption member function is
called the \defnx{resumer}{coroutine!resumer}.
called the \defna{resumer}{coroutine}.
Invoking a resumption member function for a coroutine
that is not suspended results in undefined behavior.

Expand Down Expand Up @@ -6776,7 +6776,7 @@
The underlying type can be explicitly specified using an \grammarterm{enum-base}.
For a scoped enumeration type, the underlying type is \tcode{int} if it is not
explicitly specified. In both of these cases, the underlying type is said to be
\defnx{fixed}{type!underlying!fixed}.
\defna{fixed}{type!underlying}.
Following the closing brace of an \grammarterm{enum-specifier}, each
enumerator has the type of its enumeration.
If the underlying type is fixed, the type of each enumerator
Expand Down
10 changes: 5 additions & 5 deletions source/exceptions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@
Throwing an exception
copy-initializes~(\ref{dcl.init}, \ref{class.copy.ctor}) a temporary object,
called the
\defnx{exception object}{exception handling!exception object}.
\defna{exception object}{exception handling}.
An lvalue denoting the temporary is used to initialize the
variable declared in the matching
\grammarterm{handler}\iref{except.handle}.
Expand Down Expand Up @@ -599,7 +599,7 @@
of the same thread.

\pnum
A handler is considered \defnx{active}{exception handling!handler!active} when
A handler is considered \defna{active}{exception handling!handler} when
initialization is complete for the parameter (if any) of the catch clause.
\begin{note}
The stack will have been unwound at that point.
Expand All @@ -613,7 +613,7 @@
\indextext{currently handled exception|see{exception handling, currently handled exception}}%
The exception with the most recently activated handler that is
still active is called the
\defnx{currently handled exception}{exception handling!currently handled exception}.
\defna{currently handled exception}{exception handling}.

\pnum
If no matching handler is found,
Expand Down Expand Up @@ -818,7 +818,7 @@

\pnum
An expression $E$ is
\defnx{potentially-throwing}{potentially-throwing!expression} if
\defnc{potentially-throwing}{expression} if
\begin{itemize}
\item
$E$ is a function call\iref{expr.call}
Expand Down Expand Up @@ -948,7 +948,7 @@
\end{example}

\pnum
An exception specification is considered to be \defnx{needed}{needed!exception specification} when:
An exception specification is considered to be \defnc{needed}{exception specification} when:
\begin{itemize}
\item in an expression, the function is the unique lookup result or the selected
member of a set of overloaded functions~(\ref{basic.lookup}, \ref{over.match}, \ref{over.over});
Expand Down
6 changes: 3 additions & 3 deletions source/expressions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,8 +215,8 @@
\end{example}

\pnum
The \defnx{result}{result!glvalue} of a glvalue is the entity denoted by the expression.
The \defnx{result}{result!prvalue} of a prvalue
The \defnc{result}{glvalue} of a glvalue is the entity denoted by the expression.
The \defnc{result}{prvalue} of a prvalue
is the value that the expression stores into its context;
a prvalue that has type \cv{}~\tcode{void} has no result.
A prvalue whose result is the value \placeholder{V}
Expand Down Expand Up @@ -2923,7 +2923,7 @@
member access expression is a \grammarterm{qualified-id}, that function is
called. Otherwise, its final overrider\iref{class.virtual} in the dynamic type
of the object expression is called; such a call is referred to as a
\defnx{virtual function call}{function!virtual function call}.
\defna{virtual function call}{function}.
\begin{note}
The dynamic type is the type of the object referred to by the
current value of the object expression. \ref{class.cdtor}~describes the
Expand Down
6 changes: 3 additions & 3 deletions source/iostreams.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11947,7 +11947,7 @@

\pnum
A \defn{filename} is
the name of a file. The \defnx{dot}{dot!filename} and \defnx{dot-dot}{dot-dot!filename} filenames,
the name of a file. The \defnc{dot}{filename} and \defnc{dot-dot}{filename} filenames,
consisting solely of one and two period characters respectively,
have special meaning.
The following characteristics of filenames are operating system dependent:
Expand Down Expand Up @@ -12030,7 +12030,7 @@
\item If the path is empty, add a dot.
\end{enumerate}

The result of normalization is a path in \defnx{normal form}{normal form!path},
The result of normalization is a path in \defnc{normal form}{path},
which is said to be \term{normalized}.
\indextext{path!normalization|)}%

Expand Down Expand Up @@ -14084,7 +14084,7 @@
during directory iteration if their values are available
and storing the values would allow the implementation to eliminate file system accesses
by \tcode{directory_entry} observer functions\iref{fs.op.funcs}.
Such stored file attribute values are said to be \defnx{cached}{file attributes!cached}.
Such stored file attribute values are said to be \defna{cached}{file attributes}.

\pnum
\begin{note}
Expand Down
2 changes: 1 addition & 1 deletion source/iterators.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -565,7 +565,7 @@
Such a value is called a \defnx{past-the-end value}{iterator!past-the-end}.
Values of an iterator \tcode{i}
for which the expression \tcode{*i} is defined
are called \defnx{dereferenceable}{iterator!dereferenceable}.
are called \defna{dereferenceable}{iterator}.
The library never assumes that past-the-end values are dereferenceable.
Iterators can also have singular values that are not associated with any
sequence.
Expand Down
12 changes: 6 additions & 6 deletions source/lib-intro.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -896,15 +896,15 @@
bitmask types:
\begin{itemize}
\item
To \defnx{set}{bitmask!value!set}
To \defna{set}{bitmask!value}
a value \textit{Y} in an object \textit{X}
is to evaluate the expression \textit{X} \tcode{|=} \textit{Y}.
\item
To \defnx{clear}{bitmask!value!clear}
To \defna{clear}{bitmask!value}
a value \textit{Y} in an object
\textit{X} is to evaluate the expression \textit{X} \tcode{\&= \~}\textit{Y}.
\item
The value \textit{Y} \defnx{is set}{bitmask!value!is set} in the object
The value \textit{Y} \defna{is set}{bitmask!value} in the object
\textit{X} if the expression \textit{X} \tcode{\&} \textit{Y} is nonzero.
\end{itemize}

Expand Down Expand Up @@ -1467,9 +1467,9 @@

\pnum
Two kinds of implementations are defined:
\defnx{hosted}{implementation!hosted}
\defna{hosted}{implementation}
and
\defnx{freestanding}{implementation!freestanding}\iref{intro.compliance};
\defna{freestanding}{implementation}\iref{intro.compliance};
the kind of the implementation is
\impldef{whether the implementation is hosted or freestanding}.
For a hosted implementation, this document
Expand Down Expand Up @@ -2992,7 +2992,7 @@
\pnum
A sequence \tcode{Args} of template arguments is said to
\indextext{concept!model}%
\defnx{model}{model!concept} a concept \tcode{C}
\defnc{model}{concept} a concept \tcode{C}
if \tcode{Args}
satisfies \tcode{C}\iref{temp.constr.decl} and
meets all semantic requirements (if any)
Expand Down
4 changes: 4 additions & 0 deletions source/macros.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,10 @@

% Non-compound defined term.
\newcommand{\defn}[1]{\defnx{#1}{#1}}
% Contextual defined term.
\newcommand{\defnc}[2]{\defnx{#1}{#1!#2}}
% Adjectival defined term.
\newcommand{\defna}[2]{\defnx{#1}{#2!#1}}
% Defined term with different index entry.
\newcommand{\defnx}[2]{\indexdefn{#2}\textit{#1}}
% Compound defined term with 'see' for primary term.
Expand Down
Loading