On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
> On Mon, Nov 28, 2022 at 12:45 AM Tom Lane <t...@sss.pgh.pa.us> wrote:
> > Laurenz Albe <laurenz.a...@cybertec.at> writes:
> > > Now I think that is taking it too far. Your code sample would be great
> > > for a tutorial, but it is too elaborate for the technical documentation.
> > > The example should focus on the sequence functions, but more than half
> > > of the code describes other parts of PostgreSQL:
> >
> > Yeah, that stuff seems quite out of place here.
> >
> > > I am alright with having a CREATE TABLE with a DEFAULT and an INSERT or
> > > two;
> > > whatever it takes to show the functions in a realistic scenario.
> > > For example, you could INSERT a row that overrides the DEFAULT, then call
> > > "setval()" to readjust the sequence.
> >
> > I don't believe we have such detail around very many, if indeed any,
> > of our other functions' documentation.
> >
> > regards, tom lane
>
>
> All changes specified have been addressed.
> The Example is significantly reduced, but readable.
> The extra "SELECT "'s have been removed off of the inline examples, excluding
> the existing paragraph.
>
> This is the smallest possible change, that still has an example.
>
> The "Example" is not <title> as every attempt to make it such fails the LINT
> process.
You can have <title> only after the start of a section.
The new examples in the table don't really add anything to the function
declaration...
I realized that there already are some examples in the CREATE SEQUENCE
documentation,
so what about linking there instead of writing more examples?
The attached patch does that and removes the less useful examples. What do you
think?
Yours,
Laurenz Albe
From df836162e88e6ac51d47c26908df64fb122414ce Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.a...@cybertec.at>
Date: Thu, 1 Dec 2022 22:16:28 +0100
Subject: [PATCH] Improve sequence manipulation function doc
Point to the example section of CREATE SEQUENCE for examples.
Add "--" before comments interleaved with code.
Some slight rewording.
Author: Kirk Wolak
---
doc/src/sgml/func.sgml | 20 ++++++++++++--------
doc/src/sgml/ref/create_sequence.sgml | 2 +-
2 files changed, 13 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6e0425cb3d..2391deabea 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17623,7 +17623,7 @@ $.* ? (@ like_regex "^\\d+$")
values beginning with 1. Other behaviors can be obtained by using
appropriate parameters in the <xref linkend="sql-createsequence"/>
command.
- </para>
+ </para>
<para>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
@@ -17657,11 +17657,11 @@ $.* ? (@ like_regex "^\\d+$")
Furthermore, the value reported by <function>currval</function> is not
changed in this case. For example,
<programlisting>
-SELECT setval('myseq', 42); <lineannotation>Next <function>nextval</function> will return 43</lineannotation>
-SELECT setval('myseq', 42, true); <lineannotation>Same as above</lineannotation>
-SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</function> will return 42</lineannotation>
+SELECT setval('myseq', 42); <lineannotation>-- The next <function>nextval</function>('myseq') will return 43</lineannotation>
+SELECT setval('myseq', 42, true); <lineannotation>-- Same as above</lineannotation>
+SELECT setval('myseq', 42, false); <lineannotation>-- The next <function>nextval</function>('myseq') will return 42</lineannotation>
</programlisting>
- The result returned by <function>setval</function> is just the value of its
+ The result returned by <function>setval</function> is the value of its
second argument.
</para>
<para>
@@ -17707,9 +17707,8 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
identical to <function>currval</function>, except that instead
of taking the sequence name as an argument it refers to whichever
sequence <function>nextval</function> was most recently applied to
- in the current session. It is an error to call
- <function>lastval</function> if <function>nextval</function>
- has not yet been called in the current session.
+ in the current session. (An error is reported if <function>nextval</function> has
+ never been called in this session.)
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17720,6 +17719,11 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
</tgroup>
</table>
+ <para>
+ You can see sequence manipulation functions being used in the
+ <xref linkend="sql-createsequence-examples"/>.
+ </para>
+
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 34e9084b5c..d417405930 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -329,7 +329,7 @@ SELECT * FROM <replaceable>name</replaceable>;
</para>
</refsect1>
- <refsect1>
+ <refsect1 id="sql-createsequence-examples" xreflabel="Examples for CREATE SEQUENCE">
<title>Examples</title>
<para>
--
2.38.1
