doc: improve create/alter sequence CYCLE syntax

Reported-by: Peter Smith

Discussion: https://postgr.es/m/CAHut+PtqwZwPfGq62xq2614_ce2ejDmbB9CfP+a1azxpneFRBQ@mail.gmail.com

Author: Peter Smith

Backpatch-through: master

2 files changed, 62 insertions, 59 deletions

diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml
index 7be36cf466d..a998ccc7ead 100644
--- a/doc/src/sgml/ref/alter_sequence.sgml
+++ b/doc/src/sgml/ref/alter_sequence.sgml
@@ -27,9 +27,10 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
     [ AS <replaceable class="parameter">data_type</replaceable> ]
     [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
     [ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
+    [ [ NO ] CYCLE ]
     [ START [ WITH ] <replaceable class="parameter">start</replaceable> ]
     [ RESTART [ [ WITH ] <replaceable class="parameter">restart</replaceable> ] ]
-    [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
+    [ CACHE <replaceable class="parameter">cache</replaceable> ]
     [ OWNED BY { <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> | NONE } ]
 ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> SET { LOGGED | UNLOGGED }
 ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> OWNER TO { <replaceable class="parameter">new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
@@ -155,6 +156,38 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S
      </varlistentry>
 
      <varlistentry>
+      <term><literal>CYCLE</literal></term>
+      <listitem>
+       <para>
+        The optional <literal>CYCLE</literal> key word can be used to enable
+        the sequence to wrap around when the
+        <replaceable class="parameter">maxvalue</replaceable> or
+        <replaceable class="parameter">minvalue</replaceable> has been
+        reached by
+        an ascending or descending sequence respectively. If the limit is
+        reached, the next number generated will be the
+        <replaceable class="parameter">minvalue</replaceable> or
+        <replaceable class="parameter">maxvalue</replaceable>,
+        respectively.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><literal>NO CYCLE</literal></term>
+      <listitem>
+       <para>
+        If the optional <literal>NO CYCLE</literal> key word is
+        specified, any calls to <function>nextval</function> after the
+        sequence has reached its maximum value will return an error.
+        If neither <literal>CYCLE</literal> or <literal>NO
+        CYCLE</literal> are specified, the old cycle behavior will be
+        maintained.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><replaceable class="parameter">start</replaceable></term>
       <listitem>
        <para>
@@ -208,38 +241,6 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S
      </varlistentry>
 
      <varlistentry>
-      <term><literal>CYCLE</literal></term>
-      <listitem>
-       <para>
-        The optional <literal>CYCLE</literal> key word can be used to enable
-        the sequence to wrap around when the
-        <replaceable class="parameter">maxvalue</replaceable> or
-        <replaceable class="parameter">minvalue</replaceable> has been
-        reached by
-        an ascending or descending sequence respectively. If the limit is
-        reached, the next number generated will be the
-        <replaceable class="parameter">minvalue</replaceable> or
-        <replaceable class="parameter">maxvalue</replaceable>,
-        respectively.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><literal>NO CYCLE</literal></term>
-      <listitem>
-       <para>
-        If the optional <literal>NO CYCLE</literal> key word is
-        specified, any calls to <function>nextval</function> after the
-        sequence has reached its maximum value will return an error.
-        If neither <literal>CYCLE</literal> or <literal>NO
-        CYCLE</literal> are specified, the old cycle behavior will be
-        maintained.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><literal>SET { LOGGED | UNLOGGED }</literal></term>
       <listitem>
        <para>
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 34e9084b5cc..1e283f13d15 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -25,7 +25,9 @@ CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] <replaceab
     [ AS <replaceable class="parameter">data_type</replaceable> ]
     [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
     [ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
-    [ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
+    [ [ NO ] CYCLE ]
+    [ START [ WITH ] <replaceable class="parameter">start</replaceable> ]
+    [ CACHE <replaceable class="parameter">cache</replaceable> ]
     [ OWNED BY { <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> | NONE } ]
 </synopsis>
  </refsynopsisdiv>
@@ -194,6 +196,31 @@ SELECT * FROM <replaceable>name</replaceable>;
    </varlistentry>
 
    <varlistentry>
+    <term><literal>CYCLE</literal></term>
+    <term><literal>NO CYCLE</literal></term>
+    <listitem>
+     <para>
+      The <literal>CYCLE</literal> option allows the sequence to wrap
+      around when the <replaceable
+      class="parameter">maxvalue</replaceable> or <replaceable
+      class="parameter">minvalue</replaceable> has been reached by an
+      ascending or descending sequence respectively. If the limit is
+      reached, the next number generated will be the <replaceable
+      class="parameter">minvalue</replaceable> or <replaceable
+      class="parameter">maxvalue</replaceable>, respectively.
+     </para>
+
+     <para>
+      If <literal>NO CYCLE</literal> is specified, any calls to
+      <function>nextval</function> after the sequence has reached its
+      maximum value will return an error.  If neither
+      <literal>CYCLE</literal> or <literal>NO CYCLE</literal> are
+      specified, <literal>NO CYCLE</literal> is the default.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
     <term><replaceable class="parameter">start</replaceable></term>
     <listitem>
      <para>
@@ -222,31 +249,6 @@ SELECT * FROM <replaceable>name</replaceable>;
    </varlistentry>
 
    <varlistentry>
-    <term><literal>CYCLE</literal></term>
-    <term><literal>NO CYCLE</literal></term>
-    <listitem>
-     <para>
-      The <literal>CYCLE</literal> option allows the sequence to wrap
-      around when the <replaceable
-      class="parameter">maxvalue</replaceable> or <replaceable
-      class="parameter">minvalue</replaceable> has been reached by an
-      ascending or descending sequence respectively. If the limit is
-      reached, the next number generated will be the <replaceable
-      class="parameter">minvalue</replaceable> or <replaceable
-      class="parameter">maxvalue</replaceable>, respectively.
-     </para>
-
-     <para>
-      If <literal>NO CYCLE</literal> is specified, any calls to
-      <function>nextval</function> after the sequence has reached its
-      maximum value will return an error.  If neither
-      <literal>CYCLE</literal> or <literal>NO CYCLE</literal> are
-      specified, <literal>NO CYCLE</literal> is the default.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
     <term><literal>OWNED BY</literal> <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable></term>
     <term><literal>OWNED BY NONE</literal></term>
     <listitem>