DOCS: What SGML markup to use for user objects like tables, columns, etc?
Hi,
I am looking for some guidelines/recommended SGML tags to use when
referring in the PG documentation to any user-defined
schema/table/column names.
This is most commonly seen near a <programlisting> SQL example.
Currently, it seems a bit inconsistent. The rendering also looks quite
different for these different markups.
EXAMPLES OF DIFFERENT USAGE
===========================
1. <structname> as seen in create_publication.sgml,
alter_publication.sgml, ddl.sgml, etc.
e.g.
<para>
Add tables <structname>users</structname>,
<structname>departments</structname> and schema
<structname>production</structname> to the publication
<structname>production_publication</structname>:
<programlisting>
ALTER PUBLICATION production_publication ADD TABLE users, departments,
TABLES IN SCHEMA production;
</programlisting></para>
</refsect1>
===
2. <literal>, as seen in logical-replication.sgml
e.g.
<programlisting>
CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar
user=repuser' PUBLICATION mypub;
</programlisting>
</para>
<para>
The above will start the replication process, which synchronizes the
initial table contents of the tables <literal>users</literal> and
<literal>departments</literal> and then starts replicating
incremental changes to those tables.
</para>
===
3. <classname>, as seen in advanced.sgml
e.g.
<para>
Let's create two tables: A table <classname>cities</classname>
and a table <classname>capitals</classname>. Naturally, capitals
are also cities, so you want some way to show the capitals
implicitly when you list all cities. If you're really clever you
might invent some scheme like this:
<programlisting>
CREATE TABLE capitals (
name text,
population real,
elevation int, -- (in ft)
state char(2)
);
======
My AI tool says the following.
----
PostgreSQL documentation typically uses:
<LITERAL> for specific, concrete names
<REPLACEABLE> for generic placeholders
<STRUCTNAME> for system objects and data types
----
TBH, this seemed like good advice to me... however there are quite a
few examples not following that.
Thoughts?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Mon, Jun 23, 2025 at 10:29:50AM +1000, Peter Smith wrote:
Hi,
I am looking for some guidelines/recommended SGML tags to use when
referring in the PG documentation to any user-defined
schema/table/column names.This is most commonly seen near a <programlisting> SQL example.
Currently, it seems a bit inconsistent. The rendering also looks quite
different for these different markups.EXAMPLES OF DIFFERENT USAGE
===========================1. <structname> as seen in create_publication.sgml,
alter_publication.sgml, ddl.sgml, etc.e.g.
<para>
Add tables <structname>users</structname>,
<structname>departments</structname> and schema
<structname>production</structname> to the publication
<structname>production_publication</structname>:
<programlisting>
ALTER PUBLICATION production_publication ADD TABLE users, departments,
TABLES IN SCHEMA production;
</programlisting></para>
</refsect1>===
2. <literal>, as seen in logical-replication.sgml
e.g.
<programlisting>
CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar
user=repuser' PUBLICATION mypub;
</programlisting>
</para><para>
The above will start the replication process, which synchronizes the
initial table contents of the tables <literal>users</literal> and
<literal>departments</literal> and then starts replicating
incremental changes to those tables.
</para>===
3. <classname>, as seen in advanced.sgml
e.g.
<para>
Let's create two tables: A table <classname>cities</classname>
and a table <classname>capitals</classname>. Naturally, capitals
are also cities, so you want some way to show the capitals
implicitly when you list all cities. If you're really clever you
might invent some scheme like this:<programlisting>
CREATE TABLE capitals (
name text,
population real,
elevation int, -- (in ft)
state char(2)
);======
My AI tool says the following.
----
PostgreSQL documentation typically uses:
<LITERAL> for specific, concrete names
<REPLACEABLE> for generic placeholders
<STRUCTNAME> for system objects and data types
----TBH, this seemed like good advice to me... however there are quite a
few examples not following that.Thoughts?
You are right that we are inconsistent. I think <structname> is the
accepted way to reference table names, and <structfield> for column
names. If you can create a patch to make them consistent, I can apply
it.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
On Thu, Jul 24, 2025 at 2:18 AM Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Jun 23, 2025 at 10:29:50AM +1000, Peter Smith wrote:
Hi,
I am looking for some guidelines/recommended SGML tags to use when
referring in the PG documentation to any user-defined
schema/table/column names.This is most commonly seen near a <programlisting> SQL example.
Currently, it seems a bit inconsistent. The rendering also looks quite
different for these different markups.EXAMPLES OF DIFFERENT USAGE
===========================1. <structname> as seen in create_publication.sgml,
alter_publication.sgml, ddl.sgml, etc.e.g.
<para>
Add tables <structname>users</structname>,
<structname>departments</structname> and schema
<structname>production</structname> to the publication
<structname>production_publication</structname>:
<programlisting>
ALTER PUBLICATION production_publication ADD TABLE users, departments,
TABLES IN SCHEMA production;
</programlisting></para>
</refsect1>===
2. <literal>, as seen in logical-replication.sgml
e.g.
<programlisting>
CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar
user=repuser' PUBLICATION mypub;
</programlisting>
</para><para>
The above will start the replication process, which synchronizes the
initial table contents of the tables <literal>users</literal> and
<literal>departments</literal> and then starts replicating
incremental changes to those tables.
</para>===
3. <classname>, as seen in advanced.sgml
e.g.
<para>
Let's create two tables: A table <classname>cities</classname>
and a table <classname>capitals</classname>. Naturally, capitals
are also cities, so you want some way to show the capitals
implicitly when you list all cities. If you're really clever you
might invent some scheme like this:<programlisting>
CREATE TABLE capitals (
name text,
population real,
elevation int, -- (in ft)
state char(2)
);======
My AI tool says the following.
----
PostgreSQL documentation typically uses:
<LITERAL> for specific, concrete names
<REPLACEABLE> for generic placeholders
<STRUCTNAME> for system objects and data types
----TBH, this seemed like good advice to me... however there are quite a
few examples not following that.Thoughts?
You are right that we are inconsistent. I think <structname> is the
accepted way to reference table names, and <structfield> for column
names. If you can create a patch to make them consistent, I can apply
it.
Thanks! Here is a v1 patch.
Replacements were identified by regex. Hopefully, I found most of them...
The patch replaces SGML tags as suggested:
- use <structname> for table names
- use <structfield> for column names
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
Added a CF entry [1]https://commitfest.postgresql.org/patch/6063/ for this.
A rebase was needed. PSA patch v2.
======
[1]: https://commitfest.postgresql.org/patch/6063/
Kind Regards,
Peter Smith.
Fujitsu Australia.
Attachments:
On Thu, Jul 24, 2025 at 2:18 AM Bruce Momjian <bruce@momjian.us> wrote:
...
You are right that we are inconsistent. I think <structname> is the
accepted way to reference table names, and <structfield> for column
names. If you can create a patch to make them consistent, I can apply
it.
Thanks for offering to apply the patch. It has been available for a
few months now.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Tue, Nov 4, 2025 at 02:35:29PM +1100, Peter Smith wrote:
On Thu, Jul 24, 2025 at 2:18â¯AM Bruce Momjian <bruce@momjian.us> wrote:
...You are right that we are inconsistent. I think <structname> is the
accepted way to reference table names, and <structfield> for column
names. If you can create a patch to make them consistent, I can apply
it.Thanks for offering to apply the patch. It has been available for a
few months now.
My apologies for not getting to this sooner. (Seems I need to review
all my saved emails for these type of items.) Patch applied to master.
Nice improvement.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
On Sun, Nov 9, 2025 at 1:50 AM Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 4, 2025 at 02:35:29PM +1100, Peter Smith wrote:
On Thu, Jul 24, 2025 at 2:18 AM Bruce Momjian <bruce@momjian.us> wrote:
...You are right that we are inconsistent. I think <structname> is the
accepted way to reference table names, and <structfield> for column
names. If you can create a patch to make them consistent, I can apply
it.Thanks for offering to apply the patch. It has been available for a
few months now.My apologies for not getting to this sooner. (Seems I need to review
all my saved emails for these type of items.) Patch applied to master.
Nice improvement.
Thanks for pushing!
I updated the CF entry -- https://commitfest.postgresql.org/patch/6063/#
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Mon, Nov 10, 2025 at 08:30:47AM +1100, Peter Smith wrote:
On Sun, Nov 9, 2025 at 1:50â¯AM Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 4, 2025 at 02:35:29PM +1100, Peter Smith wrote:
On Thu, Jul 24, 2025 at 2:18â¯AM Bruce Momjian <bruce@momjian.us> wrote:
...You are right that we are inconsistent. I think <structname> is the
accepted way to reference table names, and <structfield> for column
names. If you can create a patch to make them consistent, I can apply
it.Thanks for offering to apply the patch. It has been available for a
few months now.My apologies for not getting to this sooner. (Seems I need to review
all my saved emails for these type of items.) Patch applied to master.
Nice improvement.Thanks for pushing!
I updated the CF entry -- https://commitfest.postgresql.org/patch/6063/#
Thanks!
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.