Обсуждение: DOCS: Missing tags for some SEQUENCE fields
Hi, While reviewing the recent patches for SEQUENCE documentation I found [1] a few more instances where the <structfield> tag should have been used for some of the sequence fields (per the recent push [2]). PSA patch v1 to address these. ====== [1] Searched all docs for 'is_called' and for 'last_value' [2] https://github.com/postgres/postgres/commit/980a855c5c2e21e964a739694e24004f72e03fdf Kind Regards, Peter Smith. Fujitsu Australia
Вложения
> On Nov 13, 2025, at 13:17, Peter Smith <smithpb2250@gmail.com> wrote: > > Hi, > > While reviewing the recent patches for SEQUENCE documentation I found > [1] a few more instances where the <structfield> tag should have been > used for some of the sequence fields (per the recent push [2]). > > PSA patch v1 to address these. > > ====== > [1] Searched all docs for 'is_called' and for 'last_value' > [2] https://github.com/postgres/postgres/commit/980a855c5c2e21e964a739694e24004f72e03fdf > > Kind Regards, > Peter Smith. > Fujitsu Australia > <v1-0001-Fix-more-structfield-tags.patch> Good catch. LGTM. I rendered the html pages and viewed them, the pages also look good. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
On Thu, Nov 13, 2025 at 4:46 PM Chao Li <li.evan.chao@gmail.com> wrote: > > On Nov 13, 2025, at 13:17, Peter Smith <smithpb2250@gmail.com> wrote: > > > > Hi, > > > > While reviewing the recent patches for SEQUENCE documentation I found > > [1] a few more instances where the <structfield> tag should have been > > used for some of the sequence fields (per the recent push [2]). > > > > Good catch. LGTM. I rendered the html pages and viewed them, the pages also look good. > Why do we think using <structfield> tag is appropriate instead of the current <literal> tag? The explanation of the is_called says: "Sets the sequence object's current value, and optionally its is_called flag.", so from "object's current value", are we deducing it is the same as struct? Ideally, it should be used to mark up the name of a field in a struct which is close to what we are doing here. Do we have a similar usage at other places in the docs? -- With Regards, Amit Kapila.
On Fri, Nov 14, 2025 at 2:53 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
>
> On Thu, Nov 13, 2025 at 4:46 PM Chao Li <li.evan.chao@gmail.com> wrote:
> > > On Nov 13, 2025, at 13:17, Peter Smith <smithpb2250@gmail.com> wrote:
> > >
> > > Hi,
> > >
> > > While reviewing the recent patches for SEQUENCE documentation I found
> > > [1] a few more instances where the <structfield> tag should have been
> > > used for some of the sequence fields (per the recent push [2]).
> > >
> >
> > Good catch. LGTM. I rendered the html pages and viewed them, the pages also look good.
> >
>
> Why do we think using <structfield> tag is appropriate instead of the
> current <literal> tag? The explanation of the is_called says: "Sets
> the sequence object's current value, and optionally its is_called
> flag.", so from "object's current value", are we deducing it is the
> same as struct? Ideally, it should be used to mark up the name of a
> field in a struct which is close to what we are doing here. Do we have
> a similar usage at other places in the docs?
>
As referenced in the first post above, Bruce had recommended/pushed
[1] that the appropriate SGML tags to use for tables and columns are
<structname> and <structfield>.
So, I chose <structfield> because those fields ('last_value' and
'is_called') are columns of the sequence relation [2].
case SEQ_COL_LASTVAL:
coldef = makeColumnDef("last_value", INT8OID, -1, InvalidOid);
value[i - 1] = Int64GetDatumFast(last_value);
break;
case SEQ_COL_LOG:
coldef = makeColumnDef("log_cnt", INT8OID, -1, InvalidOid);
value[i - 1] = Int64GetDatum((int64) 0);
break;
case SEQ_COL_CALLED:
coldef = makeColumnDef("is_called", BOOLOID, -1, InvalidOid);
value[i - 1] = BoolGetDatum(false);
break;
e.g.
test_pub=# create sequence myseq;
CREATE SEQUENCE
test_pub=# select * from myseq;
last_value | log_cnt | is_called
------------+---------+-----------
1 | 0 | f
======
[1] https://github.com/postgres/postgres/commit/980a855c5c2e21e964a739694e24004f72e03fdf
[2]
https://github.com/postgres/postgres/blob/8fa6b9030d689c856578e5769088a2527b7283d6/src/backend/commands/sequence.c#L182
Kind Regards,
Peter Smith.
Fujitsu Australia
On Fri, Nov 14, 2025 at 10:43 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Fri, Nov 14, 2025 at 2:53 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
> >
> > On Thu, Nov 13, 2025 at 4:46 PM Chao Li <li.evan.chao@gmail.com> wrote:
> > > > On Nov 13, 2025, at 13:17, Peter Smith <smithpb2250@gmail.com> wrote:
> > > >
> > > > Hi,
> > > >
> > > > While reviewing the recent patches for SEQUENCE documentation I found
> > > > [1] a few more instances where the <structfield> tag should have been
> > > > used for some of the sequence fields (per the recent push [2]).
> > > >
> > >
> > > Good catch. LGTM. I rendered the html pages and viewed them, the pages also look good.
> > >
> >
> > Why do we think using <structfield> tag is appropriate instead of the
> > current <literal> tag? The explanation of the is_called says: "Sets
> > the sequence object's current value, and optionally its is_called
> > flag.", so from "object's current value", are we deducing it is the
> > same as struct? Ideally, it should be used to mark up the name of a
> > field in a struct which is close to what we are doing here. Do we have
> > a similar usage at other places in the docs?
> >
>
> As referenced in the first post above, Bruce had recommended/pushed
> [1] that the appropriate SGML tags to use for tables and columns are
> <structname> and <structfield>.
>
> So, I chose <structfield> because those fields ('last_value' and
> 'is_called') are columns of the sequence relation [2].
>
Okay, thanks for the context. I'll push your patch on Monday unless
there are any comments.
--
With Regards,
Amit Kapila.