DOC: italicize RFC magic must/must not, should/should not

$ sed -E -i  "/not/! s/must/\*must\*/g" ./*.rst
$ sed -E -i  "s/must not/\*must not\*/g" ./*.rst
$ sed -E -i  "/not/! s/should/\*should\*/g" ./*.rst

etc

Author: ev-br

Diff for: spec/draft/API_specification/array_object.rst

@@ -5,12 +5,12 @@ Array object
 
     Array API specification for array object attributes and methods.
 
-A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods.
+A conforming implementation of the array API standard *must* provide and support an array object having the following attributes and methods.
 
-Furthermore, a conforming implementation of the array API standard must support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and must explicitly document their maximum supported rank ``N``.
+Furthermore, a conforming implementation of the array API standard *must* support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and *must* explicitly document their maximum supported rank ``N``.
 
 .. note::
-    Conforming implementations must support zero-dimensional arrays.
+    Conforming implementations *must* support zero-dimensional arrays.
 
     Apart from array object attributes, such as ``ndim``, ``device``, and ``dtype``, all operations in this standard return arrays (or tuples of arrays), including those operations, such as ``mean``, ``var``, and ``std``, from which some common array libraries (e.g., NumPy) return scalar values.
 
@@ -23,12 +23,12 @@ Furthermore, a conforming implementation of the array API standard must support,
 Operators
 ---------
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python operators.
 
 Arithmetic Operators
 ~~~~~~~~~~~~~~~~~~~~
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following Python arithmetic operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python arithmetic operators.
 
 -   ``+x``: :meth:`.array.__pos__`
 
@@ -75,24 +75,24 @@ A conforming implementation of the array API standard must provide and support a
     -   `operator.pow(x1, x2) <https://docs.python.org/3/library/operator.html#operator.pow>`_
     -   `operator.__pow__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__pow__>`_
 
-Arithmetic operators should be defined for arrays having real-valued data types.
+Arithmetic operators *should* be defined for arrays having real-valued data types.
 
 Array Operators
 ~~~~~~~~~~~~~~~
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following Python array operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python array operators.
 
 -   `x1 @ x2`: :meth:`.array.__matmul__`
 
     -   `operator.matmul(x1, x2) <https://docs.python.org/3/library/operator.html#operator.matmul>`_
     -   `operator.__matmul__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__matmul__>`_
 
-The matmul ``@`` operator should be defined for arrays having real-valued data types.
+The matmul ``@`` operator *should* be defined for arrays having real-valued data types.
 
 Bitwise Operators
 ~~~~~~~~~~~~~~~~~
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following Python bitwise operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python bitwise operators.
 
 -   `~x`: :meth:`.array.__invert__`
 
@@ -126,12 +126,12 @@ A conforming implementation of the array API standard must provide and support a
     -   `operator.rshift(x1, x2) <https://docs.python.org/3/library/operator.html#operator.rshift>`_
     -   `operator.__rshift__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__rshift__>`_
 
-Bitwise operators should be defined for arrays having integer and boolean data types.
+Bitwise operators *should* be defined for arrays having integer and boolean data types.
 
 Comparison Operators
 ~~~~~~~~~~~~~~~~~~~~
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following Python comparison operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following Python comparison operators.
 
 -   `x1 < x2`: :meth:`.array.__lt__`
 
@@ -163,20 +163,20 @@ A conforming implementation of the array API standard must provide and support a
     -   `operator.ne(x1, x2) <https://docs.python.org/3/library/operator.html#operator.ne>`_
     -   `operator.__ne__(x1, x2) <https://docs.python.org/3/library/operator.html#operator.__ne__>`_
 
-:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type.
+:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators *should* be defined for arrays having any data type.
 For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
 
 In-place Operators
 ~~~~~~~~~~~~~~~~~~
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following in-place Python operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following in-place Python operators.
 
-An in-place operation must not change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`.
+An in-place operation *must not* change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`.
 
-An in-place operation must have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``.
+An in-place operation *must* have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` *must* always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``.
 
 .. note::
-    In-place operators must be supported as discussed in :ref:`copyview-mutability`.
+    In-place operators *must* be supported as discussed in :ref:`copyview-mutability`.
 
 Arithmetic Operators
 """"""""""""""""""""
@@ -206,12 +206,12 @@ Bitwise Operators
 Reflected Operators
 ~~~~~~~~~~~~~~~~~~~
 
-A conforming implementation of the array API standard must provide and support an array object supporting the following reflected operators.
+A conforming implementation of the array API standard *must* provide and support an array object supporting the following reflected operators.
 
-The results of applying reflected operators must match their non-reflected equivalents.
+The results of applying reflected operators *must* match their non-reflected equivalents.
 
 .. note::
-    All operators for which ``array <op> scalar`` is implemented must have an equivalent reflected operator implementation.
+    All operators for which ``array <op> scalar`` is implemented *must* have an equivalent reflected operator implementation.
 
 Arithmetic Operators
 """"""""""""""""""""

Diff for: spec/draft/API_specification/broadcasting.rst

@@ -19,7 +19,7 @@ Given an element-wise operation involving two compatible arrays, an array having
 
 If two arrays are of unequal rank, the array having a lower rank is promoted to a higher rank by (virtually) prepending singleton dimensions until the number of dimensions matches that of the array having a higher rank.
 
-The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm.
+The results of the element-wise operation *must* be stored in an array having a shape determined by the following algorithm.
 
 #.  Let ``A`` and ``B`` both be arrays.
 
@@ -112,7 +112,7 @@ The following examples demonstrate array shapes which do **not** broadcast.
 In-place Semantics
 ------------------
 
-As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) must not change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed.
+As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) *must not* change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed.
 
 For example:
 

Diff for: spec/draft/API_specification/constants.rst

@@ -3,9 +3,9 @@ Constants
 
     Array API specification for constants.
 
-A conforming implementation of the array API standard must provide and support the following constants adhering to the following conventions.
+A conforming implementation of the array API standard *must* provide and support the following constants adhering to the following conventions.
 
--   Each constant must have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value.
+-   Each constant *must* have a Python floating-point data type (i.e., ``float``) and be provided as a Python scalar value.
 
 Objects in API
 --------------

Diff for: spec/draft/API_specification/creation_functions.rst

@@ -3,7 +3,7 @@ Creation Functions
 
     Array API specification for creating arrays.
 
-A conforming implementation of the array API standard must provide and support the following functions.
+A conforming implementation of the array API standard *must* provide and support the following functions.
 
 
 Objects in API

Diff for: spec/draft/API_specification/data_type_functions.rst

@@ -3,7 +3,7 @@ Data Type Functions
 
     Array API specification for data type functions.
 
-A conforming implementation of the array API standard must provide and support the following data type functions.
+A conforming implementation of the array API standard *must* provide and support the following data type functions.
 
 
 Objects in API

Diff for: spec/draft/API_specification/data_types.rst

@@ -5,7 +5,7 @@ Data Types
 
     Array API specification for supported data types.
 
-A conforming implementation of the array API standard must provide and support
+A conforming implementation of the array API standard *must* provide and support
 the following data types ("dtypes") in its array object, and as data type
 objects in its main namespace under the specified names:
 
@@ -34,12 +34,12 @@ objects in its main namespace under the specified names:
 +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | float64      | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).                                                                                                       |
 +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| complex64    | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019).  |
+| complex64    | Single-precision (64-bit) complex floating-point number whose real and imaginary components *must* be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019).  |
 +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| complex128   | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). |
+| complex128   | Double-precision (128-bit) complex floating-point number whose real and imaginary components *must* be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). |
 +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
-Data type objects must have the following methods (no attributes are required):
+Data type objects *must* have the following methods (no attributes are required):
 
 ..
   NOTE: please keep the functions in alphabetical order
@@ -89,28 +89,28 @@ See :ref:`type-promotion` for specification guidance describing the rules govern
 Default Data Types
 ------------------
 
-A conforming implementation of the array API standard must define the following default data types.
+A conforming implementation of the array API standard *must* define the following default data types.
 
 -   a default real-valued floating-point data type (either ``float32`` or ``float64``).
 -   a default complex floating-point data type (either ``complex64`` or ``complex128``).
 -   a default integer data type (either ``int32`` or ``int64``).
 -   a default array index data type (either ``int32`` or ``int64``).
 
-The default real-valued floating-point and complex floating-point data types must be the same across platforms.
+The default real-valued floating-point and complex floating-point data types *must* be the same across platforms.
 
-The default complex floating-point point data type should match the default real-valued floating-point data type. For example, if the default real-valued floating-point data type is ``float32``, the default complex floating-point data type must be ``complex64``. If the default real-valued floating-point data type is ``float64``, the default complex floating-point data type must be ``complex128``.
+The default complex floating-point point data type *should* match the default real-valued floating-point data type. For example, if the default real-valued floating-point data type is ``float32``, the default complex floating-point data type *must* be ``complex64``. If the default real-valued floating-point data type is ``float64``, the default complex floating-point data type *must* be ``complex128``.
 
-The default integer data type should be the same across platforms, but the default may vary depending on whether Python is 32-bit or 64-bit.
+The default integer data type *should* be the same across platforms, but the default may vary depending on whether Python is 32-bit or 64-bit.
 
-The default array index data type may be ``int32`` on 32-bit platforms, but the default should be ``int64`` otherwise.
+The default array index data type may be ``int32`` on 32-bit platforms, but the default *should* be ``int64`` otherwise.
 
 Note that it is possible that a library supports multiple devices, with not all
 those device types supporting the same data types. In this case, the default
 integer or floating-point data types may vary with device. If that is the case,
-the library should clearly warn about this in its documentation.
+the library *should* clearly warn about this in its documentation.
 
 .. note::
-   The default data types should be clearly defined in a conforming library's documentation.
+   The default data types *should* be clearly defined in a conforming library's documentation.
 
 
 .. _data-type-categories:

Diff for: spec/draft/API_specification/function_and_method_signatures.rst

@@ -5,7 +5,7 @@ Function and method signatures
 
 Function signatures in this standard adhere to the following:
 
-1. Positional parameters should be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters.
+1. Positional parameters *should* be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters.
    Positional-only parameters have no externally-usable name. When a function
    accepting positional-only parameters is called, positional arguments are
    mapped to these parameters based solely on their order.
@@ -20,7 +20,7 @@ Function signatures in this standard adhere to the following:
     namespace >= 3.8. Alternatively, they can add guidance to their users in the
     documentation to use the functions as if they were positional-only.
 
-2. Optional parameters should be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
+2. Optional parameters *should* be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
 
    *Rationale: this leads to more readable code, and it makes it easier to
    evolve an API over time by adding keywords without having to worry about

Diff for: spec/draft/API_specification/index.rst

@@ -3,16 +3,16 @@
 API specification
 =================
 
-A conforming implementation of the array API standard must provide and support the APIs and behavior detailed in this specification while adhering to the following conventions.
+A conforming implementation of the array API standard *must* provide and support the APIs and behavior detailed in this specification while adhering to the following conventions.
 
--   When a function signature includes a `/`, positional parameters must be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters. See :ref:`function-and-method-signatures`.
--   When a function signature includes a `*`, optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments. See :ref:`function-and-method-signatures`.
--   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
--   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
+-   When a function signature includes a `/`, positional parameters *must* be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters. See :ref:`function-and-method-signatures`.
+-   When a function signature includes a `*`, optional parameters *must* be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments. See :ref:`function-and-method-signatures`.
+-   Broadcasting semantics *must* follow the semantics defined in :ref:`broadcasting`.
+-   Unless stated otherwise, functions *must* support the data types defined in :ref:`data-types`.
 -   Functions may only be required for a subset of input data types. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`.
--   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
--   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
--   Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`.
+-   Unless stated otherwise, functions *must* adhere to the type promotion rules defined in :ref:`type-promotion`.
+-   Unless stated otherwise, floating-point operations *must* adhere to IEEE 754-2019.
+-   Unless stated otherwise, element-wise mathematical functions *must* satisfy the minimum accuracy requirements defined in :ref:`accuracy`.
 
 
 .. toctree::