[depr] Reorder clauses by origin of deprecation

Reorders the deprecated features annex to follow the order
of the main clauses that the deprecates feature refers to.
Where multiple clauses are references, use the one named by
the [depr.XXX] stable label.

Author: AlisdairM

source/future.tex

@@ -16,6 +16,26 @@
 An implementation may declare library names and entities described in this Clause with the
 \tcode{deprecated} attribute\iref{dcl.attr.deprecated}.
 
+\rSec1[depr.local]{Non-local use of TU-local entities}
+
+\pnum
+A declaration of a non-TU-local entity that is an exposure\iref{basic.link}
+is deprecated.
+\begin{note}
+Such a declaration in an importable module unit is ill-formed.
+\end{note}
+\begin{example}
+\begin{codeblock}
+namespace {
+  struct A {
+    void f() {}
+  };
+}
+A h();                          // deprecated: not internal linkage
+inline void g() {A().f();}      // deprecated: inline and not internal linkage
+\end{codeblock}
+\end{example}
+
 \rSec1[depr.capture.this]{Implicit capture of \tcode{*this} by reference}
 
 \pnum
@@ -35,25 +55,6 @@
 \end{codeblock}
 \end{example}
 
-\rSec1[depr.array.comp]{Array comparisons}
-
-\pnum
-Equality and relational comparisons\iref{expr.eq,expr.rel}
-between two operands of array type
-are deprecated.
-\begin{note}
-Three-way comparisons\iref{expr.spaceship} between such operands are ill-formed.
-\end{note}
-\begin{example}
-\begin{codeblock}
-int arr1[5];
-int arr2[5];
-bool same = arr1 == arr2;       // deprecated, same as \tcode{\&arr1[0] == \&arr2[0]},
-                                // does not compare array contents
-auto cmp = arr1 <=> arr2;       // error
-\end{codeblock}
-\end{example}
-
 \rSec1[depr.volatile.type]{Deprecated \tcode{volatile} types}
 
 \pnum
@@ -115,40 +116,22 @@
 \end{example}
 
 
-\rSec1[depr.static.constexpr]{Redeclaration of \tcode{static constexpr} data members}
-
-\pnum
-For compatibility with prior revisions of \Cpp{}, a \keyword{constexpr}
-static data member may be redundantly redeclared outside the class with no
-initializer\iref{basic.def,class.static.data}.
-This usage is deprecated.
-\begin{example}
-\begin{codeblock}
-struct A {
-  static constexpr int n = 5;   // definition (declaration in \CppXIV{})
-};
-
-constexpr int A::n;             // redundant declaration (definition in \CppXIV{})
-\end{codeblock}
-\end{example}
-
-\rSec1[depr.local]{Non-local use of TU-local entities}
+\rSec1[depr.array.comp]{Array comparisons}
 
 \pnum
-A declaration of a non-TU-local entity that is an exposure\iref{basic.link}
-is deprecated.
+Equality and relational comparisons\iref{expr.eq,expr.rel}
+between two operands of array type
+are deprecated.
 \begin{note}
-Such a declaration in an importable module unit is ill-formed.
+Three-way comparisons\iref{expr.spaceship} between such operands are ill-formed.
 \end{note}
 \begin{example}
 \begin{codeblock}
-namespace {
-  struct A {
-    void f() {}
-  };
-}
-A h();                          // deprecated: not internal linkage
-inline void g() {A().f();}      // deprecated: inline and not internal linkage
+int arr1[5];
+int arr2[5];
+bool same = arr1 == arr2;       // deprecated, same as \tcode{\&arr1[0] == \&arr2[0]},
+                                // does not compare array contents
+auto cmp = arr1 <=> arr2;       // error
 \end{codeblock}
 \end{example}
 
@@ -166,6 +149,23 @@
 It is possible that future versions of \Cpp{} will specify
 that these implicit definitions are deleted\iref{dcl.fct.def.delete}.
 
+\rSec1[depr.static.constexpr]{Redeclaration of \tcode{static constexpr} data members}
+
+\pnum
+For compatibility with prior revisions of \Cpp{}, a \keyword{constexpr}
+static data member may be redundantly redeclared outside the class with no
+initializer\iref{basic.def,class.static.data}.
+This usage is deprecated.
+\begin{example}
+\begin{codeblock}
+struct A {
+  static constexpr int n = 5;   // definition (declaration in \CppXIV{})
+};
+
+constexpr int A::n;             // redundant declaration (definition in \CppXIV{})
+\end{codeblock}
+\end{example}
+
 \rSec1[depr.lit]{Literal operator function declarations using an identifier}
 
 \pnum
@@ -244,86 +244,6 @@
 #define @\xname{bool_true_false_are_defined}@ 1
 \end{codeblock}
 
-\rSec1[depr.relops]{Relational operators}%
-\indexlibraryglobal{rel_ops}%
-
-\pnum
-The header \libheaderref{utility} has the following additions:
-
-\begin{codeblock}
-namespace std::rel_ops {
-  template<class T> bool operator!=(const T&, const T&);
-  template<class T> bool operator> (const T&, const T&);
-  template<class T> bool operator<=(const T&, const T&);
-  template<class T> bool operator>=(const T&, const T&);
-}
-\end{codeblock}
-
-\pnum
-To avoid redundant definitions of \tcode{operator!=} out of \tcode{operator==}
-and operators \tcode{>}, \tcode{<=}, and \tcode{>=} out of \tcode{operator<},
-the library provides the following:
-
-\indexlibrary{\idxcode{operator"!=}}%
-\begin{itemdecl}
-template<class T> bool operator!=(const T& x, const T& y);
-\end{itemdecl}
-
-\begin{itemdescr}
-\pnum
-\expects
-\tcode{T} meets the \oldconcept{EqualityComparable} requirements (\tref{cpp17.equalitycomparable}).
-
-\pnum
-\returns
-\tcode{!(x == y)}.
-\end{itemdescr}
-
-\indexlibraryglobal{operator>}%
-\begin{itemdecl}
-template<class T> bool operator>(const T& x, const T& y);
-\end{itemdecl}
-
-\begin{itemdescr}
-\pnum
-\expects
-\tcode{T} meets the \oldconcept{LessThanComparable} requirements (\tref{cpp17.lessthancomparable}).
-
-\pnum
-\returns
-\tcode{y < x}.
-\end{itemdescr}
-
-\indexlibrary{\idxcode{operator<=}}%
-\begin{itemdecl}
-template<class T> bool operator<=(const T& x, const T& y);
-\end{itemdecl}
-
-\begin{itemdescr}
-\pnum
-\expects
-\tcode{T} meets the \oldconcept{LessThanComparable} requirements (\tref{cpp17.lessthancomparable}).
-
-\pnum
-\returns
-\tcode{!(y < x)}.
-\end{itemdescr}
-
-\indexlibrary{\idxcode{operator>=}}%
-\begin{itemdecl}
-template<class T> bool operator>=(const T& x, const T& y);
-\end{itemdecl}
-
-\begin{itemdescr}
-\pnum
-\expects
-\tcode{T} meets the \oldconcept{LessThanComparable} requirements (\tref{cpp17.lessthancomparable}).
-
-\pnum
-\returns
-\tcode{!(x < y)}.
-\end{itemdescr}
-
 \rSec1[depr.cerrno]{Deprecated error numbers}
 
 \pnum
@@ -483,6 +403,86 @@
 whose value is the strictest alignment of all types listed in \tcode{Types}.
 \end{itemdescr}
 
+\rSec1[depr.relops]{Relational operators}%
+\indexlibraryglobal{rel_ops}%
+
+\pnum
+The header \libheaderref{utility} has the following additions:
+
+\begin{codeblock}
+namespace std::rel_ops {
+  template<class T> bool operator!=(const T&, const T&);
+  template<class T> bool operator> (const T&, const T&);
+  template<class T> bool operator<=(const T&, const T&);
+  template<class T> bool operator>=(const T&, const T&);
+}
+\end{codeblock}
+
+\pnum
+To avoid redundant definitions of \tcode{operator!=} out of \tcode{operator==}
+and operators \tcode{>}, \tcode{<=}, and \tcode{>=} out of \tcode{operator<},
+the library provides the following:
+
+\indexlibrary{\idxcode{operator"!=}}%
+\begin{itemdecl}
+template<class T> bool operator!=(const T& x, const T& y);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\expects
+\tcode{T} meets the \oldconcept{EqualityComparable} requirements (\tref{cpp17.equalitycomparable}).
+
+\pnum
+\returns
+\tcode{!(x == y)}.
+\end{itemdescr}
+
+\indexlibraryglobal{operator>}%
+\begin{itemdecl}
+template<class T> bool operator>(const T& x, const T& y);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\expects
+\tcode{T} meets the \oldconcept{LessThanComparable} requirements (\tref{cpp17.lessthancomparable}).
+
+\pnum
+\returns
+\tcode{y < x}.
+\end{itemdescr}
+
+\indexlibrary{\idxcode{operator<=}}%
+\begin{itemdecl}
+template<class T> bool operator<=(const T& x, const T& y);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\expects
+\tcode{T} meets the \oldconcept{LessThanComparable} requirements (\tref{cpp17.lessthancomparable}).
+
+\pnum
+\returns
+\tcode{!(y < x)}.
+\end{itemdescr}
+
+\indexlibrary{\idxcode{operator>=}}%
+\begin{itemdecl}
+template<class T> bool operator>=(const T& x, const T& y);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\expects
+\tcode{T} meets the \oldconcept{LessThanComparable} requirements (\tref{cpp17.lessthancomparable}).
+
+\pnum
+\returns
+\tcode{!(x < y)}.
+\end{itemdescr}
+
 \rSec1[depr.tuple]{Tuple}
 
 \pnum
@@ -674,34 +674,6 @@
 \tcode{current}.
 \end{itemdescr}
 
-\rSec1[depr.format]{Deprecated formatting}
-
-\rSec2[depr.format.syn]{Header \tcode{<format>} synopsis}
-
-\pnum
-The header \libheaderref{format}{format.syn} has the following additions:
-
-\begin{codeblock}
-namespace std {
-  template<class Visitor, class Context>
-    decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
-}
-\end{codeblock}
-
-\rSec2[depr.format.arg]{Formatting arguments}
-
-\indexlibraryglobal{visit_format_arg}%
-\begin{itemdecl}
-template<class Visitor, class Context>
-  decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
-\end{itemdecl}
-
-\begin{itemdescr}
-\pnum
-\effects
-Equivalent to: \tcode{return visit(std::forward<Visitor>(vis), arg.value);}
-\end{itemdescr}
-
 \rSec1[depr.locale.category]{Deprecated locale category facets}
 
 \pnum
@@ -741,6 +713,34 @@
 \tcode{codecvt<char32_t, char8_t, mbstate_t>}
 convert between the UTF-32 and UTF-8 encoding forms.
 
+\rSec1[depr.format]{Deprecated formatting}
+
+\rSec2[depr.format.syn]{Header \tcode{<format>} synopsis}
+
+\pnum
+The header \libheaderref{format}{format.syn} has the following additions:
+
+\begin{codeblock}
+namespace std {
+  template<class Visitor, class Context>
+    decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
+}
+\end{codeblock}
+
+\rSec2[depr.format.arg]{Formatting arguments}
+
+\indexlibraryglobal{visit_format_arg}%
+\begin{itemdecl}
+template<class Visitor, class Context>
+  decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Equivalent to: \tcode{return visit(std::forward<Visitor>(vis), arg.value);}
+\end{itemdescr}
+
 \rSec1[depr.fs.path.factory]{Deprecated filesystem path factory functions}
 
 \pnum