Обсуждение: 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
Re: DOCS: What SGML markup to use for user objects like tables, columns, etc?
От
Bruce Momjian
Дата:
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
Вложения
Added a CF entry [1] for this. A rebase was needed. PSA patch v2. ====== [1] https://commitfest.postgresql.org/patch/6063/ Kind Regards, Peter Smith. Fujitsu Australia.