Message-ID: <075bcf0bf071140c294261d52687fd8d78fb5255.camel@cybertec.at>
Subject: Re: nextval parameter is not clear
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Kirk Wolak <wolakk@gmail.com>, Tom Lane <tgl@sss.pgh.pa.us>
Cc: "David G. Johnston" <david.g.johnston@gmail.com>, Bruce Momjian
	 <bruce@momjian.us>, ailjushkin@gmail.com, pgsql-docs@lists.postgresql.org
Date: Thu, 01 Dec 2022 22:21:54 +0100
In-Reply-To: 
 <CACLU5mRd-xpVfhmDJwGwM33uV4hovGT85DZbd_F4vAS1FVRMSA@mail.gmail.com>
References: 
	<166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
	 <Y30ekxQpiIaG9eSl@momjian.us>
	 <CACLU5mQBVn+cyeAAbs7O6c8h14MBurhuxpp7z+TXWo2+vQcO+w@mail.gmail.com>
	 <CAKFQuwau7CpY+TLufpU1RPPzyLzjS0mvrXnSLf+eGSUJS-_pRQ@mail.gmail.com>
	 <CACLU5mQ1LTz9BnG-bbfCmwzytyUFwej90XBnFtQJKQkubS9Khw@mail.gmail.com>
	 <CACLU5mTKsNgWfY9qcsn1fhMRXbfJ0M8bPEwgXbmanxVgdKPQ7A@mail.gmail.com>
	 <CACLU5mS4b3xM-tuMpT2oP-pqwwnHJbSeLDBzZSs9Lq_ObgMu7Q@mail.gmail.com>
	 <21e017222199f3ca397fa70549140d226236e4b6.camel@cybertec.at>
	 <CACLU5mShHGjroH=Cp_k6i-T+357_Fhxahc5NqpNPoJnN56GyFg@mail.gmail.com>
	 <CAKFQuwarCJs9bbgJ9_PtsCBJKmSM1UnLx80J5JUJm1eJyYzHXQ@mail.gmail.com>
	 <CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com>
	 <0c0eddb287571e72a2df1be8758fbbb0cb7cc378.camel@cybertec.at>
	 <CAKFQuwYuu_FrZZ=TEdUPdB4c-hbsCHSKD+XSUdDFrGnaDMQ_=A@mail.gmail.com>
	 <CACLU5mTmEieU-uTF6bNm9T5Y94gd1g_cgz_JDLz6Qw36RjcBHQ@mail.gmail.com>
	 <f7a51be79a5146740954e0b9b70515529a1d944b.camel@cybertec.at>
	 <452493.1669614328@sss.pgh.pa.us>
	 <CACLU5mRd-xpVfhmDJwGwM33uV4hovGT85DZbd_F4vAS1FVRMSA@mail.gmail.com>
Content-Type: multipart/mixed; boundary="=-z9mTMahXwEfw1jdKDQN4"
User-Agent: Evolution 3.42.4 (3.42.4-2.fc35) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/075bcf0bf071140c294261d52687fd8d78fb5255.camel%40cybertec.at>
Precedence: bulk


--=-z9mTMahXwEfw1jdKDQN4
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 8bit

On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
> On Mon, Nov 28, 2022 at 12:45 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Laurenz Albe <laurenz.albe@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

--=-z9mTMahXwEfw1jdKDQN4
Content-Disposition: attachment;
	filename="0001-Improve-sequence-manipulation-function-doc.v9.patch"
Content-Transfer-Encoding: base64
Content-Type: text/x-patch;
	name="0001-Improve-sequence-manipulation-function-doc.v9.patch";
	charset="UTF-8"

RnJvbSBkZjgzNjE2MmU4OGU2YWM1MWQ0N2MyNjkwOGRmNjRmYjEyMjQxNGNlIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBMYXVyZW56IEFsYmUgPGxhdXJlbnouYWxiZUBjeWJlcnRlYy5h
dD4KRGF0ZTogVGh1LCAxIERlYyAyMDIyIDIyOjE2OjI4ICswMTAwClN1YmplY3Q6IFtQQVRDSF0g
SW1wcm92ZSBzZXF1ZW5jZSBtYW5pcHVsYXRpb24gZnVuY3Rpb24gZG9jCgpQb2ludCB0byB0aGUg
ZXhhbXBsZSBzZWN0aW9uIG9mIENSRUFURSBTRVFVRU5DRSBmb3IgZXhhbXBsZXMuCkFkZCAiLS0i
IGJlZm9yZSBjb21tZW50cyBpbnRlcmxlYXZlZCB3aXRoIGNvZGUuClNvbWUgc2xpZ2h0IHJld29y
ZGluZy4KCkF1dGhvcjogS2lyayBXb2xhawotLS0KIGRvYy9zcmMvc2dtbC9mdW5jLnNnbWwgICAg
ICAgICAgICAgICAgfCAyMCArKysrKysrKysrKystLS0tLS0tLQogZG9jL3NyYy9zZ21sL3JlZi9j
cmVhdGVfc2VxdWVuY2Uuc2dtbCB8ICAyICstCiAyIGZpbGVzIGNoYW5nZWQsIDEzIGluc2VydGlv
bnMoKyksIDkgZGVsZXRpb25zKC0pCgpkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21sL2Z1bmMuc2dt
bCBiL2RvYy9zcmMvc2dtbC9mdW5jLnNnbWwKaW5kZXggNmUwNDI1Y2IzZC4uMjM5MWRlYWJlYSAx
MDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL2Z1bmMuc2dtbAorKysgYi9kb2Mvc3JjL3NnbWwvZnVu
Yy5zZ21sCkBAIC0xNzYyMyw3ICsxNzYyMyw3IEBAICQuKiA/IChAIGxpa2VfcmVnZXggIl5cXGQr
JCIpCiAgICAgICAgIHZhbHVlcyBiZWdpbm5pbmcgd2l0aCAxLiAgT3RoZXIgYmVoYXZpb3JzIGNh
biBiZSBvYnRhaW5lZCBieSB1c2luZwogICAgICAgICBhcHByb3ByaWF0ZSBwYXJhbWV0ZXJzIGlu
IHRoZSA8eHJlZiBsaW5rZW5kPSJzcWwtY3JlYXRlc2VxdWVuY2UiLz4KICAgICAgICAgY29tbWFu
ZC4KLSAgICAgIDwvcGFyYT4KKyAgICAgICA8L3BhcmE+CiAgICAgICAgPHBhcmE+CiAgICAgICAg
IFRoaXMgZnVuY3Rpb24gcmVxdWlyZXMgPGxpdGVyYWw+VVNBR0U8L2xpdGVyYWw+CiAgICAgICAg
IG9yIDxsaXRlcmFsPlVQREFURTwvbGl0ZXJhbD4gcHJpdmlsZWdlIG9uIHRoZSBzZXF1ZW5jZS4K
QEAgLTE3NjU3LDExICsxNzY1NywxMSBAQCAkLiogPyAoQCBsaWtlX3JlZ2V4ICJeXFxkKyQiKQog
ICAgICAgICBGdXJ0aGVybW9yZSwgdGhlIHZhbHVlIHJlcG9ydGVkIGJ5IDxmdW5jdGlvbj5jdXJy
dmFsPC9mdW5jdGlvbj4gaXMgbm90CiAgICAgICAgIGNoYW5nZWQgaW4gdGhpcyBjYXNlLiAgRm9y
IGV4YW1wbGUsCiA8cHJvZ3JhbWxpc3Rpbmc+Ci1TRUxFQ1Qgc2V0dmFsKCdteXNlcScsIDQyKTsg
ICAgICAgICAgIDxsaW5lYW5ub3RhdGlvbj5OZXh0IDxmdW5jdGlvbj5uZXh0dmFsPC9mdW5jdGlv
bj4gd2lsbCByZXR1cm4gNDM8L2xpbmVhbm5vdGF0aW9uPgotU0VMRUNUIHNldHZhbCgnbXlzZXEn
LCA0MiwgdHJ1ZSk7ICAgICA8bGluZWFubm90YXRpb24+U2FtZSBhcyBhYm92ZTwvbGluZWFubm90
YXRpb24+Ci1TRUxFQ1Qgc2V0dmFsKCdteXNlcScsIDQyLCBmYWxzZSk7ICAgIDxsaW5lYW5ub3Rh
dGlvbj5OZXh0IDxmdW5jdGlvbj5uZXh0dmFsPC9mdW5jdGlvbj4gd2lsbCByZXR1cm4gNDI8L2xp
bmVhbm5vdGF0aW9uPgorU0VMRUNUIHNldHZhbCgnbXlzZXEnLCA0Mik7ICAgICAgICAgICA8bGlu
ZWFubm90YXRpb24+LS0gVGhlIG5leHQgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1bmN0aW9uPignbXlz
ZXEnKSB3aWxsIHJldHVybiA0MzwvbGluZWFubm90YXRpb24+CitTRUxFQ1Qgc2V0dmFsKCdteXNl
cScsIDQyLCB0cnVlKTsgICAgIDxsaW5lYW5ub3RhdGlvbj4tLSBTYW1lIGFzIGFib3ZlPC9saW5l
YW5ub3RhdGlvbj4KK1NFTEVDVCBzZXR2YWwoJ215c2VxJywgNDIsIGZhbHNlKTsgICAgPGxpbmVh
bm5vdGF0aW9uPi0tIFRoZSBuZXh0IDxmdW5jdGlvbj5uZXh0dmFsPC9mdW5jdGlvbj4oJ215c2Vx
Jykgd2lsbCByZXR1cm4gNDI8L2xpbmVhbm5vdGF0aW9uPgogPC9wcm9ncmFtbGlzdGluZz4KLSAg
ICAgICAgVGhlIHJlc3VsdCByZXR1cm5lZCBieSA8ZnVuY3Rpb24+c2V0dmFsPC9mdW5jdGlvbj4g
aXMganVzdCB0aGUgdmFsdWUgb2YgaXRzCisgICAgICAgIFRoZSByZXN1bHQgcmV0dXJuZWQgYnkg
PGZ1bmN0aW9uPnNldHZhbDwvZnVuY3Rpb24+IGlzIHRoZSB2YWx1ZSBvZiBpdHMKICAgICAgICAg
c2Vjb25kIGFyZ3VtZW50LgogICAgICAgIDwvcGFyYT4KICAgICAgICA8cGFyYT4KQEAgLTE3NzA3
LDkgKzE3NzA3LDggQEAgU0VMRUNUIHNldHZhbCgnbXlzZXEnLCA0MiwgZmFsc2UpOyAgICA8bGlu
ZWFubm90YXRpb24+TmV4dCA8ZnVuY3Rpb24+bmV4dHZhbDwvZnUKICAgICAgICAgaWRlbnRpY2Fs
IHRvIDxmdW5jdGlvbj5jdXJydmFsPC9mdW5jdGlvbj4sIGV4Y2VwdCB0aGF0IGluc3RlYWQKICAg
ICAgICAgb2YgdGFraW5nIHRoZSBzZXF1ZW5jZSBuYW1lIGFzIGFuIGFyZ3VtZW50IGl0IHJlZmVy
cyB0byB3aGljaGV2ZXIKICAgICAgICAgc2VxdWVuY2UgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1bmN0
aW9uPiB3YXMgbW9zdCByZWNlbnRseSBhcHBsaWVkIHRvCi0gICAgICAgIGluIHRoZSBjdXJyZW50
IHNlc3Npb24uIEl0IGlzIGFuIGVycm9yIHRvIGNhbGwKLSAgICAgICAgPGZ1bmN0aW9uPmxhc3R2
YWw8L2Z1bmN0aW9uPiBpZiA8ZnVuY3Rpb24+bmV4dHZhbDwvZnVuY3Rpb24+Ci0gICAgICAgIGhh
cyBub3QgeWV0IGJlZW4gY2FsbGVkIGluIHRoZSBjdXJyZW50IHNlc3Npb24uCisgICAgICAgIGlu
IHRoZSBjdXJyZW50IHNlc3Npb24uIChBbiBlcnJvciBpcyByZXBvcnRlZCBpZiA8ZnVuY3Rpb24+
bmV4dHZhbDwvZnVuY3Rpb24+IGhhcworICAgICAgICBuZXZlciBiZWVuIGNhbGxlZCBpbiB0aGlz
IHNlc3Npb24uKQogICAgICAgIDwvcGFyYT4KICAgICAgICA8cGFyYT4KICAgICAgICAgVGhpcyBm
dW5jdGlvbiByZXF1aXJlcyA8bGl0ZXJhbD5VU0FHRTwvbGl0ZXJhbD4KQEAgLTE3NzIwLDYgKzE3
NzE5LDExIEBAIFNFTEVDVCBzZXR2YWwoJ215c2VxJywgNDIsIGZhbHNlKTsgICAgPGxpbmVhbm5v
dGF0aW9uPk5leHQgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1CiAgICAgPC90Z3JvdXA+CiAgICA8L3Rh
YmxlPgogCisgIDxwYXJhPgorICAgWW91IGNhbiBzZWUgc2VxdWVuY2UgbWFuaXB1bGF0aW9uIGZ1
bmN0aW9ucyBiZWluZyB1c2VkIGluIHRoZQorICAgPHhyZWYgbGlua2VuZD0ic3FsLWNyZWF0ZXNl
cXVlbmNlLWV4YW1wbGVzIi8+LgorICA8L3BhcmE+CisKICAgPGNhdXRpb24+CiAgICA8cGFyYT4K
ICAgICBUbyBhdm9pZCBibG9ja2luZyBjb25jdXJyZW50IHRyYW5zYWN0aW9ucyB0aGF0IG9idGFp
biBudW1iZXJzIGZyb20KZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yZWYvY3JlYXRlX3NlcXVl
bmNlLnNnbWwgYi9kb2Mvc3JjL3NnbWwvcmVmL2NyZWF0ZV9zZXF1ZW5jZS5zZ21sCmluZGV4IDM0
ZTkwODRiNWMuLmQ0MTc0MDU5MzAgMTAwNjQ0Ci0tLSBhL2RvYy9zcmMvc2dtbC9yZWYvY3JlYXRl
X3NlcXVlbmNlLnNnbWwKKysrIGIvZG9jL3NyYy9zZ21sL3JlZi9jcmVhdGVfc2VxdWVuY2Uuc2dt
bApAQCAtMzI5LDcgKzMyOSw3IEBAIFNFTEVDVCAqIEZST00gPHJlcGxhY2VhYmxlPm5hbWU8L3Jl
cGxhY2VhYmxlPjsKICAgPC9wYXJhPgogIDwvcmVmc2VjdDE+CiAKLSA8cmVmc2VjdDE+CisgPHJl
ZnNlY3QxIGlkPSJzcWwtY3JlYXRlc2VxdWVuY2UtZXhhbXBsZXMiIHhyZWZsYWJlbD0iRXhhbXBs
ZXMgZm9yIENSRUFURSBTRVFVRU5DRSI+CiAgIDx0aXRsZT5FeGFtcGxlczwvdGl0bGU+CiAKICAg
PHBhcmE+Ci0tIAoyLjM4LjEKCg==


--=-z9mTMahXwEfw1jdKDQN4--