Horton

Thread

Commits

  1. Doc: Use <structfield> markup for sequence fields.

  2. doc: adjust "Replication Slot" to mention physical & logical

  3. doc: consistently use "structname" and "structfield" markup

  1. DOCS: Missing <structfield> tags for some SEQUENCE fields

    Peter Smith <smithpb2250@gmail.com> — 2025-11-13T05:17:17Z

    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

  2. Re: DOCS: Missing <structfield> tags for some SEQUENCE fields

    Chao Li <li.evan.chao@gmail.com> — 2025-11-13T09:22:08Z

    
> 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/

  3. Re: DOCS: Missing <structfield> tags for some SEQUENCE fields

    Amit Kapila <amit.kapila16@gmail.com> — 2025-11-14T03:53:20Z

    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.

  4. Re: DOCS: Missing <structfield> tags for some SEQUENCE fields

    Peter Smith <smithpb2250@gmail.com> — 2025-11-14T05:13:09Z

    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

  5. Re: DOCS: Missing <structfield> tags for some SEQUENCE fields

    Amit Kapila <amit.kapila16@gmail.com> — 2025-11-14T11:15:23Z

    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.

  6. Re: DOCS: Missing <structfield> tags for some SEQUENCE fields

    Amit Kapila <amit.kapila16@gmail.com> — 2025-11-18T06:01:07Z

    On Fri, Nov 14, 2025 at 4:45 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
>
> 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.
>

Pushed.

-- 
With Regards,
Amit Kapila.

  7. Re: DOCS: Missing <structfield> tags for some SEQUENCE fields

    Peter Smith <smithpb2250@gmail.com> — 2025-11-18T21:34:23Z

    On Tue, Nov 18, 2025 at 5:01 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
...
> > Okay, thanks for the context. I'll push your patch on Monday unless
> > there are any comments.
> >
>
> Pushed.
>

Thanks for pushing!

======
Kind Regards,
Peter Smith.
Fujitsu Australia