Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1p088R-0003H4-Bg for pgsql-docs@arkaria.postgresql.org; Tue, 29 Nov 2022 21:27:23 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1p088Q-0002xk-6u for pgsql-docs@arkaria.postgresql.org; Tue, 29 Nov 2022 21:27:22 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1p088P-0002xa-Tz for pgsql-docs@lists.postgresql.org; Tue, 29 Nov 2022 21:27:21 +0000 Received: from mail-oo1-xc31.google.com ([2607:f8b0:4864:20::c31]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1p088N-000742-Ra for pgsql-docs@lists.postgresql.org; Tue, 29 Nov 2022 21:27:21 +0000 Received: by mail-oo1-xc31.google.com with SMTP id j6-20020a4ab1c6000000b004809a59818cso2355584ooo.0 for ; Tue, 29 Nov 2022 13:27:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=laCw0y/ClW7nCGrrlZC/2L92MCvRjAFrZSSNWtboLPE=; b=FyxWFzBiotNj9pkUAj9b4Xhjsq0sn1dn6SutNVD0GU4zzklo8O6qm2CPTwpvC2Xl3Z eD1+Z6MQUUIt29Xo6DNUjCGBgGu/sx4pr8xAPXZ+IvZLVm/FZo01VQJycADIPdMVFA2e Rj2KYPZbYCbpkxiADg4Xe7oy0ZK7LHrBmh9foMk7DgYc5W8ndIhFDrQWqstncVqGFT1x i6fE9n9kIjS3EMP02x5Rnd1Q1Go5qjQTPSHh2/JDHtVjqfSHypV/mhZRtKhNPI9gFRlu y4VkMwajuf8HrLs8SBV70rvHjXHl/X7QvnBsx02g7sMoZT6QPQ0v80jwYMFro6J7fp5A pp1g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=laCw0y/ClW7nCGrrlZC/2L92MCvRjAFrZSSNWtboLPE=; b=6pd0bu1dhkBr31Jjv5lbBAF7AJYczcW0Zo/zjTvIVPde8tW2nRcjeJ/p77Rdnr3fIF EU5IzmHyx7WKxUzU7heLjbOUBkvFvTJInFOVALhy1NAqQYLYE6Av6OglfZDDD7+xR/OD 61ZK9Xgib1gDvrR990H1vWuWC3+KtWN5ZjT7ZVYWwFGz4Lvh4qbC7YFBBgrc5xVOZEqb GgsTMWQQwRAcVNX3/OMiSvGIAnq1Vd4I0ClilduJzigVhHHaa+vdo+b0n4snx8WtiJbs W1Kfd11mOok55HTxUN1f1r+L7nZWLKKR7J3PyScBpcprp7+CIHYXwWEEgJHAVcsn2xa9 uxkw== X-Gm-Message-State: ANoB5pnZKF1gX3kWQ1VAE/hb4JRNlNGC/aogdGvQUWf/qK4zIfXipHSt 4iqMiUhFvTEGpIpDFc/det7yo7pvuriHBvRODpELo3+t X-Google-Smtp-Source: AA0mqf63crUWpKcR4jclyZiT0qc89WTveP+hWYxTueF8Ro8VT1eQRqQAECZlvbIxy4+Q471ZKOQGzdKALx7vO7yJi/s= X-Received: by 2002:a4a:102:0:b0:476:1d36:4cef with SMTP id 2-20020a4a0102000000b004761d364cefmr15917462oor.60.1669757238167; Tue, 29 Nov 2022 13:27:18 -0800 (PST) MIME-Version: 1.0 References: <166608103231.2042183.13992576112735261253@wrigleys.postgresql.org> <21e017222199f3ca397fa70549140d226236e4b6.camel@cybertec.at> <0c0eddb287571e72a2df1be8758fbbb0cb7cc378.camel@cybertec.at> <452493.1669614328@sss.pgh.pa.us> In-Reply-To: <452493.1669614328@sss.pgh.pa.us> From: Kirk Wolak Date: Tue, 29 Nov 2022 16:26:51 -0500 Message-ID: Subject: Re: nextval parameter is not clear To: Tom Lane Cc: Laurenz Albe , "David G. Johnston" , Bruce Momjian , ailjushkin@gmail.com, pgsql-docs@lists.postgresql.org Content-Type: multipart/mixed; boundary="0000000000000b36ec05eea2a79c" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --0000000000000b36ec05eea2a79c Content-Type: multipart/alternative; boundary="0000000000000b36e805eea2a79a" --0000000000000b36e805eea2a79a Content-Type: text/plain; charset="UTF-8" On Mon, Nov 28, 2022 at 12:45 AM Tom Lane wrote: > Laurenz Albe 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 as every attempt to make it such fails the LINT process. regards, Kirk --0000000000000b36e805eea2a79a Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div dir=3D"ltr">On Mon, Nov 28, 2022 at 12:45 AM Tom Lane= <<a href=3D"mailto:tgl@sss.pgh.pa.us">tgl@sss.pgh.pa.us</a>> wrote:<= br></div><div class=3D"gmail_quote"><blockquote class=3D"gmail_quote" style= =3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding= -left:1ex">Laurenz Albe <<a href=3D"mailto:laurenz.albe@cybertec.at" tar= get=3D"_blank">laurenz.albe@cybertec.at</a>> writes:<br> > Now I think that is taking it too far.=C2=A0 Your code sample would be= great<br> > for a tutorial, but it is too elaborate for the technical documentatio= n.<br> > The example should focus on the sequence functions, but more than half= <br> > of the code describes other parts of PostgreSQL:<br> <br> Yeah, that stuff seems quite out of place here.<br> <br> > I am alright with having a CREATE TABLE with a DEFAULT and an INSERT o= r two;<br> > whatever it takes to show the functions in a realistic scenario.<br> > For example, you could INSERT a row that overrides the DEFAULT, then c= all<br> > "setval()" to readjust the sequence.<br> <br> I don't believe we have such detail around very many, if indeed any,<br= > of our other functions' documentation.<br> <br> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 regards, tom lane<br></blockquote><div><br></div><div>All change= s specified have been addressed.</div><div>The Example is significantly red= uced, but readable.</div><div>The extra "SELECT "'s have been= removed off of the inline examples, excluding the existing paragraph.</div= ><div><br></div><div>This is the smallest possible change, that still has a= n example.</div><div><br></div><div>The "Example" is not <titl= e> as every attempt to make it such fails the LINT process.=C2=A0</div><= div><br></div><div>regards, Kirk</div></div></div> --0000000000000b36e805eea2a79a-- --0000000000000b36ec05eea2a79c Content-Type: text/plain; charset="US-ASCII"; name="func-examples-8.patch" Content-Disposition: attachment; filename="func-examples-8.patch" Content-Transfer-Encoding: base64 Content-ID: <f_lb2qbtx00> X-Attachment-Id: f_lb2qbtx00 ZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9mdW5jLnNnbWwgYi9kb2Mvc3JjL3NnbWwvZnVuYy5z Z21sCmluZGV4IDgyZmJhNDhkNWYuLjNiZTJjNWVmOTcgMTAwNjQ0Ci0tLSBhL2RvYy9zcmMvc2dt bC9mdW5jLnNnbWwKKysrIGIvZG9jL3NyYy9zZ21sL2Z1bmMuc2dtbApAQCAtMTc2MjMsNyArMTc2 MjMsMTIgQEAgJC4qID8gKEAgbGlrZV9yZWdleCAiXlxcZCskIikKICAgICAgICAgdmFsdWVzIGJl Z2lubmluZyB3aXRoIDEuICBPdGhlciBiZWhhdmlvcnMgY2FuIGJlIG9idGFpbmVkIGJ5IHVzaW5n CiAgICAgICAgIGFwcHJvcHJpYXRlIHBhcmFtZXRlcnMgaW4gdGhlIDx4cmVmIGxpbmtlbmQ9InNx bC1jcmVhdGVzZXF1ZW5jZSIvPgogICAgICAgICBjb21tYW5kLgotICAgICAgPC9wYXJhPgorICAg ICAgIDwvcGFyYT4KKyAgICAgICA8cGFyYT4KKzxwcm9ncmFtbGlzdGluZz4KK25leHR2YWwoJ215 c2VxJyk7Cis8L3Byb2dyYW1saXN0aW5nPgorICAgICAgIDwvcGFyYT4KICAgICAgICA8cGFyYT4K ICAgICAgICAgVGhpcyBmdW5jdGlvbiByZXF1aXJlcyA8bGl0ZXJhbD5VU0FHRTwvbGl0ZXJhbD4K ICAgICAgICAgb3IgPGxpdGVyYWw+VVBEQVRFPC9saXRlcmFsPiBwcml2aWxlZ2Ugb24gdGhlIHNl cXVlbmNlLgpAQCAtMTc2NTcsMTEgKzE3NjYyLDExIEBAICQuKiA/IChAIGxpa2VfcmVnZXggIl5c XGQrJCIpCiAgICAgICAgIEZ1cnRoZXJtb3JlLCB0aGUgdmFsdWUgcmVwb3J0ZWQgYnkgPGZ1bmN0 aW9uPmN1cnJ2YWw8L2Z1bmN0aW9uPiBpcyBub3QKICAgICAgICAgY2hhbmdlZCBpbiB0aGlzIGNh c2UuICBGb3IgZXhhbXBsZSwKIDxwcm9ncmFtbGlzdGluZz4KLVNFTEVDVCBzZXR2YWwoJ215c2Vx JywgNDIpOyAgICAgICAgICAgPGxpbmVhbm5vdGF0aW9uPk5leHQgPGZ1bmN0aW9uPm5leHR2YWw8 L2Z1bmN0aW9uPiB3aWxsIHJldHVybiA0MzwvbGluZWFubm90YXRpb24+Ci1TRUxFQ1Qgc2V0dmFs KCdteXNlcScsIDQyLCB0cnVlKTsgICAgIDxsaW5lYW5ub3RhdGlvbj5TYW1lIGFzIGFib3ZlPC9s aW5lYW5ub3RhdGlvbj4KLVNFTEVDVCBzZXR2YWwoJ215c2VxJywgNDIsIGZhbHNlKTsgICAgPGxp bmVhbm5vdGF0aW9uPk5leHQgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1bmN0aW9uPiB3aWxsIHJldHVy biA0MjwvbGluZWFubm90YXRpb24+CitTRUxFQ1Qgc2V0dmFsKCdteXNlcScsIDQyKTsgICAgICAg ICAgIDxsaW5lYW5ub3RhdGlvbj4tLSBUaGUgbmV4dCA8ZnVuY3Rpb24+bmV4dHZhbDwvZnVuY3Rp b24+KCdteXNlcScpIHdpbGwgcmV0dXJuIDQzPC9saW5lYW5ub3RhdGlvbj4KK1NFTEVDVCBzZXR2 YWwoJ215c2VxJywgNDIsIHRydWUpOyAgICAgPGxpbmVhbm5vdGF0aW9uPi0tIFNhbWUgYXMgYWJv dmU8L2xpbmVhbm5vdGF0aW9uPgorU0VMRUNUIHNldHZhbCgnbXlzZXEnLCA0MiwgZmFsc2UpOyAg ICA8bGluZWFubm90YXRpb24+LS0gVGhlIG5leHQgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1bmN0aW9u PignbXlzZXEnKSB3aWxsIHJldHVybiA0MjwvbGluZWFubm90YXRpb24+CiA8L3Byb2dyYW1saXN0 aW5nPgotICAgICAgICBUaGUgcmVzdWx0IHJldHVybmVkIGJ5IDxmdW5jdGlvbj5zZXR2YWw8L2Z1 bmN0aW9uPiBpcyBqdXN0IHRoZSB2YWx1ZSBvZiBpdHMKKyAgICAgICAgVGhlIHJlc3VsdCByZXR1 cm5lZCBieSA8ZnVuY3Rpb24+c2V0dmFsPC9mdW5jdGlvbj4gaXMgdGhlIHZhbHVlIG9mIGl0cwog ICAgICAgICBzZWNvbmQgYXJndW1lbnQuCiAgICAgICAgPC9wYXJhPgogICAgICAgIDxwYXJhPgpA QCAtMTc2ODYsNiArMTc2OTEsOSBAQCBTRUxFQ1Qgc2V0dmFsKCdteXNlcScsIDQyLCBmYWxzZSk7 ICAgIDxsaW5lYW5ub3RhdGlvbj5OZXh0IDxmdW5jdGlvbj5uZXh0dmFsPC9mdQogICAgICAgICBy ZXR1cm5pbmcgYSBzZXNzaW9uLWxvY2FsIHZhbHVlLCBpdCBnaXZlcyBhIHByZWRpY3RhYmxlIGFu c3dlciB3aGV0aGVyCiAgICAgICAgIG9yIG5vdCBvdGhlciBzZXNzaW9ucyBoYXZlIGV4ZWN1dGVk IDxmdW5jdGlvbj5uZXh0dmFsPC9mdW5jdGlvbj4gc2luY2UKICAgICAgICAgdGhlIGN1cnJlbnQg c2Vzc2lvbiBkaWQuCis8cHJvZ3JhbWxpc3Rpbmc+CitjdXJydmFsKCdteXNlcScpOworPC9wcm9n cmFtbGlzdGluZz4KICAgICAgICA8L3BhcmE+CiAgICAgICAgPHBhcmE+CiAgICAgICAgIFRoaXMg ZnVuY3Rpb24gcmVxdWlyZXMgPGxpdGVyYWw+VVNBR0U8L2xpdGVyYWw+CkBAIC0xNzcwNyw5ICsx NzcxNSw4IEBAIFNFTEVDVCBzZXR2YWwoJ215c2VxJywgNDIsIGZhbHNlKTsgICAgPGxpbmVhbm5v dGF0aW9uPk5leHQgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1CiAgICAgICAgIGlkZW50aWNhbCB0byA8 ZnVuY3Rpb24+Y3VycnZhbDwvZnVuY3Rpb24+LCBleGNlcHQgdGhhdCBpbnN0ZWFkCiAgICAgICAg IG9mIHRha2luZyB0aGUgc2VxdWVuY2UgbmFtZSBhcyBhbiBhcmd1bWVudCBpdCByZWZlcnMgdG8g d2hpY2hldmVyCiAgICAgICAgIHNlcXVlbmNlIDxmdW5jdGlvbj5uZXh0dmFsPC9mdW5jdGlvbj4g d2FzIG1vc3QgcmVjZW50bHkgYXBwbGllZCB0bwotICAgICAgICBpbiB0aGUgY3VycmVudCBzZXNz aW9uLiBJdCBpcyBhbiBlcnJvciB0byBjYWxsCi0gICAgICAgIDxmdW5jdGlvbj5sYXN0dmFsPC9m dW5jdGlvbj4gaWYgPGZ1bmN0aW9uPm5leHR2YWw8L2Z1bmN0aW9uPgotICAgICAgICBoYXMgbm90 IHlldCBiZWVuIGNhbGxlZCBpbiB0aGUgY3VycmVudCBzZXNzaW9uLgorICAgICAgICBpbiB0aGUg Y3VycmVudCBzZXNzaW9uLiAoQW4gZXJyb3IgaXMgcmVwb3J0ZWQgaWYgPGZ1bmN0aW9uPm5leHR2 YWw8L2Z1bmN0aW9uPiBoYXMKKyAgICAgICAgbmV2ZXIgYmVlbiBjYWxsZWQgaW4gdGhpcyBzZXNz aW9uLikKICAgICAgICA8L3BhcmE+CiAgICAgICAgPHBhcmE+CiAgICAgICAgIFRoaXMgZnVuY3Rp b24gcmVxdWlyZXMgPGxpdGVyYWw+VVNBR0U8L2xpdGVyYWw+CkBAIC0xNzcxOSw3ICsxNzcyNiwy MSBAQCBTRUxFQ1Qgc2V0dmFsKCdteXNlcScsIDQyLCBmYWxzZSk7ICAgIDxsaW5lYW5ub3RhdGlv bj5OZXh0IDxmdW5jdGlvbj5uZXh0dmFsPC9mdQogICAgICA8L3Rib2R5PgogICAgIDwvdGdyb3Vw PgogICAgPC90YWJsZT4KKyAgPHBhcmE+RXhhbXBsZQorPHByb2dyYW1saXN0aW5nPgorQ1JFQVRF IFNFUVVFTkNFIHRlc3Rfc2VxOworCitTRUxFQ1QgbmV4dHZhbCgndGVzdF9zZXEnOjpyZWdjbGFz cyk7ICAgICAgICAgIDxsaW5lYW5ub3RhdGlvbj4tLSAxPC9saW5lYW5ub3RhdGlvbj4KK1NFTEVD VCBjdXJydmFsKCd0ZXN0X3NlcScpOyAgICAgICAgICAgICAgICAgICAgPGxpbmVhbm5vdGF0aW9u Pi0tIDE8L2xpbmVhbm5vdGF0aW9uPgorU0VMRUNUIGxhc3R2YWwoKTsgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICA8bGluZWFubm90YXRpb24+LS0gMTwvbGluZWFubm90YXRpb24+CisKKzxs aW5lYW5ub3RhdGlvbj4tLSBVc2luZyB0aGUgREVGQVVMVCB2YWx1ZSB5b3UgY2FuIGFzc2lnbiB0 aGlzIFNFUVVFTkNFIHRvIGJlIHVzZWQgd2hlbiB0aGUgZmllbGQgaXMgbm90IGFzc2lnbmVkIGEg dmFsdWU8L2xpbmVhbm5vdGF0aW9uPgogCitDUkVBVEUgVEFCTEUgdDEgKGlkIGJpZ2ludCBOT1Qg TlVMTCBERUZBVUxUIG5leHR2YWwoJ3Rlc3Rfc2VxJyksIG90aGVyX2RhdGEgdGV4dCk7IDxsaW5l YW5ub3RhdGlvbj4tLSBsaW5rcyBjb2x1bW4vc2VxdWVuY2U8L2xpbmVhbm5vdGF0aW9uPgorCitJ TlNFUlQgSU5UTyB0MSAob3RoZXJfZGF0YSkgVkFMVUVTICgnU29tZSBEYXRhJyk7ICA8bGluZWFu bm90YXRpb24+LS0gQXNzaWducyB0aGUgbmV4dCBJRCBhdXRvbWF0aWNhbGx5PC9saW5lYW5ub3Rh dGlvbj4KKzwvcHJvZ3JhbWxpc3Rpbmc+CisgIDwvcGFyYT4KICAgPGNhdXRpb24+CiAgICA8cGFy YT4KICAgICBUbyBhdm9pZCBibG9ja2luZyBjb25jdXJyZW50IHRyYW5zYWN0aW9ucyB0aGF0IG9i dGFpbiBudW1iZXJzIGZyb20K --0000000000000b36ec05eea2a79c--