Reference a defined term by its name, not by its clause number

scripts/generate-schema.rb

@@ -236,9 +236,9 @@ def render(groups)
   out << "The tag of a field is normative; it identifies the field on the " \
          "wire and SHALL NOT be reused. A field marked mandatory SHALL be " \
          "present. A field marked optional MAY be absent, and a " \
-         "<<consumer>> SHALL accept a message in which it is. A field marked " \
+         "<<consumer,consumer>> SHALL accept a message in which it is. A field marked " \
          "repeated holds zero or more values. A field marked deprecated " \
-         "SHALL NOT be written by a <<producer>>, and a consumer that reads " \
+         "SHALL NOT be written by a <<producer,producer>>, and a consumer that reads " \
          "one SHALL ignore it."
   out << ""
   out << "The obligations are those in force at the IR version stated in " \

sources/part1/sections/03-terms-and-definitions.adoc

@@ -1,12 +1,13 @@
 == Terms and definitions
 
-For the purposes of this document, the following terms and definitions apply.
+// Metanorma inserts the "For the purposes of this document ..." sentence
+// itself; stating it here as well printed it twice.
 
 [[model]]
 === model
 
-self-contained description of a computation, comprising a top-level <<graph>>,
-the <<operator-set>> versions it depends upon, and producer and metadata
+self-contained description of a computation, comprising a top-level <<graph,graph>>,
+the <<operator-set,operator set>> versions it depends upon, and producer and metadata
 information
 
 [[graph]]
@@ -18,39 +19,39 @@ outputs, initializers and value type information
 [[node]]
 === node
 
-single invocation of an <<operator>>, binding named values to the operator's
+single invocation of an <<operator,operator>>, binding named values to the operator's
 formal inputs and outputs and fixing its <<attribute,attributes>>
 
 [[initializer]]
 === initializer
 
-named tensor value carried in a <<graph>>, being either a constant of that
+named tensor value carried in a <<graph,graph>>, being either a constant of that
 graph or the default value of an input of it
 
 [[subgraph]]
 === subgraph
 
-<<graph>> that is the value of an <<attribute>> of a <<node>>
+<<graph,graph>> that is the value of an <<attribute,attribute>> of a <<node,node>>
 
 [[function]]
 === function
 
-<<operator>> together with an implementation of it in terms of other operators
+<<operator,operator>> together with an implementation of it in terms of other operators
 
 Note 1 to entry: The implementation is a fallback, not a definition of the
 operator's numerical behaviour; see <<functions>>.
 
 [[dimension-variable]]
 === dimension variable
 
-name denoting an extent that is not fixed when a <<model>> is written, and that
+name denoting an extent that is not fixed when a <<model,model>> is written, and that
 is the same wherever the name occurs in that model
 
 [[operator]]
 === operator
 
 named computation with a specified signature and semantics, identified by the
-pair of its <<domain>> and its name
+pair of its <<domain,domain>> and its name
 
 Note 1 to entry: Operators are defined in <<onnx-part-2>>. This document
 specifies the form such a definition takes and the rules it obeys, not the
@@ -68,31 +69,31 @@ Note 1 to entry: The empty string denotes the default ONNX domain.
 [.alt]
 opset
 
-set of operator definitions belonging to one <<domain>>, identified by that
+set of operator definitions belonging to one <<domain,domain>>, identified by that
 domain and a monotonically increasing integer version
 
 [[attribute]]
 === attribute
 
-named value that is fixed at the time the <<model>> is constructed and that
+named value that is fixed at the time the <<model,model>> is constructed and that
 does not participate in dataflow
 
 [[tensor]]
 === tensor
 
-dense multidimensional array of elements of a single <<element-type>>, having a
-<<shape>>
+dense multidimensional array of elements of a single <<element-type,element type>>, having a
+<<shape,shape>>
 
 [[element-type]]
 === element type
 
-member of the enumeration of scalar types that the elements of a <<tensor>> may
+member of the enumeration of scalar types that the elements of a <<tensor,tensor>> may
 take
 
 [[shape]]
 === shape
 
-ordered sequence of dimensions of a <<tensor>>, each of which is a
+ordered sequence of dimensions of a <<tensor,tensor>>, each of which is a
 non-negative integer, a symbolic name, or unknown
 
 [[conforming-implementation]]
@@ -104,17 +105,17 @@ conformance classes defined in <<conformance>>
 [[producer]]
 === producer
 
-program that emits a <<model>>
+program that emits a <<model,model>>
 
 [[consumer]]
 === consumer
 
-program that reads a <<model>> in order to evaluate, transform or inspect it
+program that reads a <<model,model>> in order to evaluate, transform or inspect it
 
 [[validation]]
 === validation
 
-determination of whether a <<model>> satisfies the requirements of this
+determination of whether a <<model,model>> satisfies the requirements of this
 document, without evaluating it
 
 [[conformance-profile]]

sources/part1/sections/04-conformance.adoc

@@ -21,7 +21,7 @@ not a technical one.
 This document defines the conformance classes listed in
 <<tbl-conformance-classes>>. An implementation claiming conformance to this
 document SHALL state which classes it claims and, for each class it claims, the
-<<operator-set>> versions it supports.
+<<operator-set,operator set>> versions it supports.
 
 [[tbl-conformance-classes]]
 .Conformance classes
@@ -62,7 +62,7 @@ conformance claim. To be settled with the Steering Committee.
 
 === Operator set coverage
 
-A <<conforming-implementation>> is not required to support every operator
+A <<conforming-implementation,conforming implementation>> is not required to support every operator
 defined in an operator set. It SHALL, however, report unambiguously which
 operators it does not support, and it SHALL NOT silently substitute an
 approximation of an unsupported operator.
@@ -75,7 +75,7 @@ containing the information required by Annex A.
 === Relationship to Parts 2 and 3
 
 This document specifies the form an operator definition takes and the rules an
-<<operator-set>> obeys; it defines no operator. Operator definitions are in
+<<operator-set,operator set>> obeys; it defines no operator. Operator definitions are in
 <<onnx-part-2>>.
 
 A claim of conformance to this document alone is a claim about structure,

sources/part1/sections/05-information-model.adoc

@@ -3,18 +3,18 @@
 
 === General
 
-This clause introduces the entities of an ONNX <<model>> and their
+This clause introduces the entities of an ONNX <<model,model>> and their
 relationships. <<graph-structure>> states the constraints a well-formed graph
 satisfies; <<graph-semantics>> states what evaluating one means.
 
 === Entities and their relationships
 
-A model contains exactly one top-level <<graph>>.
+A model contains exactly one top-level <<graph,graph>>.
 
 A graph contains an ordered sequence of <<node,nodes>>, together with its
 declared inputs, outputs, initializers and value type information.
 
-A node invokes one <<operator>>, identified by <<domain>> and name, binds named
+A node invokes one <<operator,operator>>, identified by <<domain,domain>> and name, binds named
 values to that operator's formal inputs and outputs, and fixes its
 <<attribute,attributes>>.
 
@@ -62,7 +62,7 @@ the same graph, or an enclosing scope.
 
 | Model version
 | optional
-| An identifier assigned by the <<producer>>, opaque to this document.
+| An identifier assigned by the <<producer,producer>>, opaque to this document.
 
 | Documentation string
 | optional
@@ -79,11 +79,11 @@ organization responsible for the model.
 [[operator-set-import]]
 ==== Operator set imports
 
-An <<operator-set>> is identified by a pair of a <<domain>> and a version. The
+An <<operator-set,operator set>> is identified by a pair of a <<domain,domain>> and a version. The
 version is a positive integer that increases monotonically as versions of that
 operator set are published.
 
-A model SHALL declare, for every <<domain>> used by any node reachable from its
+A model SHALL declare, for every <<domain,domain>> used by any node reachable from its
 top-level graph, the operator set version of that domain that the model
 requires. The default domain is denoted by the empty domain name and is
 imported implicitly.
@@ -93,7 +93,7 @@ reverse domain name based on the identity of the organization responsible for
 it.
 
 Every operator invoked by a node SHALL be declared by one of the operator sets
-the model imports. A <<consumer>> that does not implement every operator of
+the model imports. A <<consumer,consumer>> that does not implement every operator of
 every imported operator set SHALL reject the model; see <<conformance>>.
 
 [[names-and-scoping]]
@@ -194,7 +194,7 @@ without regard to case.
 
 === Domains as the extension point
 
-The <<domain>> is the sole extension point of the information model. An
+The <<domain,domain>> is the sole extension point of the information model. An
 operator outside the domains defined by <<onnx-part-2>> is a custom operator;
 see <<maintenance>>. A custom domain MAY also introduce value types of its own;
 see <<opaque-types>>.

sources/part1/sections/06-type-system.adoc

@@ -2,7 +2,7 @@
 
 === General
 
-Every value in an ONNX <<graph>> has a type. Types are either tensor types,
+Every value in an ONNX <<graph,graph>> has a type. Types are either tensor types,
 sparse tensor types, sequence types, map types, optional types or opaque types.
 
 Primitive numeric, string and Boolean types SHALL be used only as the element
@@ -68,7 +68,7 @@ interchange formats, and integer element types narrower than eight bits. This
 subclause states their value encoding and their packing into octets. The
 packing is part of the wire format and is therefore normative.
 
-Support for these types is not required of every <<conforming-implementation>>;
+Support for these types is not required of every <<conforming-implementation,conforming implementation>>;
 see <<conformance>>.
 
 ==== Narrow floating-point formats
@@ -218,7 +218,7 @@ A tensor type whose shape is absent denotes a tensor of unknown rank. This is
 distinct from a tensor of rank zero, and distinct from a tensor whose rank is
 known and whose extents are unknown.
 
-The inputs and outputs of a top-level <<graph>> SHALL have a shape, so that
+The inputs and outputs of a top-level <<graph,graph>> SHALL have a shape, so that
 their rank is stated, even where the individual extents are not.
 
 [[dimension-variables]]
@@ -227,7 +227,7 @@ their rank is stated, even where the individual extents are not.
 A dimension variable is a name. Two occurrences of the same dimension variable
 SHALL denote the same extent at evaluation.
 
-Dimension variables are scoped to the <<model>>, not to a graph: an occurrence
+Dimension variables are scoped to the <<model,model>>, not to a graph: an occurrence
 in a subgraph and an occurrence in an enclosing graph denote the same extent.
 This is what allows a model to relate an extent inside a subgraph to an extent
 outside it.
@@ -300,7 +300,7 @@ the rule above is satisfied without appeal to the value of the variable.
 
 A type MAY carry a type denotation, and a dimension MAY carry a dimension
 denotation. A denotation ascribes a meaning to a type or an axis for the
-benefit of a <<producer>> or a <<consumer>>.
+benefit of a <<producer,producer>> or a <<consumer,consumer>>.
 
 A denotation SHALL NOT affect the result of evaluating a model. A consumer MAY
 ignore a denotation, and MAY reject a model whose denotations are inconsistent
@@ -376,7 +376,7 @@ the same mechanism as an unsupplied operator input, which is described in
 [[opaque-types]]
 ==== Opaque
 
-An opaque type is identified by a pair of a <<domain>> and a name. The name is
+An opaque type is identified by a pair of a <<domain,domain>> and a name. The name is
 required; an absent or empty domain denotes the default domain.
 
 The meaning of an opaque type is defined by the operators of its domain, and

sources/part1/sections/07-graph-structure.adoc

@@ -3,7 +3,7 @@
 
 === Graph, inputs and outputs
 
-A <<graph>> SHALL have a name, and SHALL declare its inputs, its outputs and,
+A <<graph,graph>> SHALL have a name, and SHALL declare its inputs, its outputs and,
 optionally, its initializers and value type information.
 
 A top-level graph SHALL declare the name, type and shape of each of its inputs
@@ -24,7 +24,7 @@ An initializer is a named tensor value carried in the graph. The order of the
 initializers of a graph is not significant.
 
 Where an initializer has the same name as an input of the same graph, it
-specifies a default value for that input. A <<consumer>> MAY allow the caller
+specifies a default value for that input. A <<consumer,consumer>> MAY allow the caller
 to supply a value for that input, overriding the initializer, and MAY allow the
 caller to omit it, in which case the value of the initializer is used.
 
@@ -54,7 +54,7 @@ so under what compatibility rule; see <<versioning>>.
 
 ==== General
 
-A <<node>> SHALL identify the <<operator>> it invokes by domain and name.
+A <<node,node>> SHALL identify the <<operator,operator>> it invokes by domain and name.
 
 The number and types of a node's inputs and outputs, and the set and types of
 its attributes, SHALL satisfy the signature of the operator as defined in the
@@ -95,7 +95,7 @@ a type, and the operators that construct and destruct it are defined in
 
 === Attributes
 
-An <<attribute>> SHALL have a name that is unique within its node.
+An <<attribute,attribute>> SHALL have a name that is unique within its node.
 
 An attribute value SHALL NOT refer to a value produced by dataflow: it is fixed
 when the graph is constructed.

sources/part1/sections/08-graph-semantics.adoc

@@ -3,10 +3,10 @@
 
 === Evaluation model
 
-Evaluating a <<graph>> means computing a value for each of its declared
+Evaluating a <<graph,graph>> means computing a value for each of its declared
 outputs, given a value for each of its declared inputs.
 
-A <<model>> denotes a stateless function. Evaluating the same model on the same
+A <<model,model>> denotes a stateless function. Evaluating the same model on the same
 inputs SHALL yield the same outputs, save where an operator of the model is
 permitted to be non-deterministic; see <<determinism>>.
 
@@ -19,7 +19,7 @@ which the caller passes to the next invocation as an input.
 Evaluation is defined by the dataflow relation between nodes. This document
 does not prescribe an evaluation order beyond the constraint that a node's
 inputs are available before the node is evaluated; in particular, a
-<<conforming-implementation>> MAY evaluate nodes concurrently, may elide nodes
+<<conforming-implementation,conforming implementation>> MAY evaluate nodes concurrently, may elide nodes
 whose outputs are unused, and may fuse or reassociate computations, provided
 that the results remain within the tolerances of <<numerical>>.
 
@@ -39,11 +39,11 @@ axis handling of `Scan`. The structural constraints are in
 [[functions]]
 === Functions
 
-A function is an <<operator>> together with an implementation of it in terms of
+A function is an <<operator,operator>> together with an implementation of it in terms of
 other operators, called its function body. The body is a topologically sorted
 list of nodes, as a graph is.
 
-A function is identified by a triple of a <<domain>>, a name and an overload.
+A function is identified by a triple of a <<domain,domain>>, a name and an overload.
 The overload distinguishes function bodies that are required to differ between
 call sites; where a model needs no such distinction the overload is empty. A
 function does not carry an operator set version of its own: the version is that
@@ -57,7 +57,7 @@ value; where there is no default value, the attribute is omitted from that
 node.
 
 A function body is a fallback implementation, not a definition of the
-operator's numerical behaviour. A <<conforming-implementation>> MAY compute the
+operator's numerical behaviour. A <<conforming-implementation,conforming implementation>> MAY compute the
 operator by any means, and the tolerances of <<numerical>> apply to the
 operator rather than to the evaluation of its body.
 

sources/part1/sections/09-inference.adoc

@@ -4,10 +4,10 @@
 === General
 
 Shape and type inference derives the types and shapes of values that a
-<<model>> does not state explicitly.
+<<model,model>> does not state explicitly.
 
 Inference is normative rather than a convenience: consumers rely on it, and a
-<<producer>> is permitted to omit value type information for values other than
+<<producer,producer>> is permitted to omit value type information for values other than
 graph inputs and outputs.
 
 [[inference-obligations]]

sources/part1/sections/10-validation.adoc

@@ -3,7 +3,7 @@
 
 === General
 
-Validation determines whether a <<model>> satisfies the requirements of this
+Validation determines whether a <<model,model>> satisfies the requirements of this
 document, without evaluating it.
 
 A validating consumer SHALL perform the checks of this clause and SHALL report

sources/part1/sections/12-serialization.adoc

@@ -3,7 +3,7 @@
 
 === General
 
-An ONNX <<model>> is serialized as a Protocol Buffers message.
+An ONNX <<model,model>> is serialized as a Protocol Buffers message.
 
 [IMPORTANT]
 .Editorial note