Re: DOCS: What SGML markup to use for user objects like tables, columns, etc?

On Thu, Jul 24, 2025 at 2:18 AM Bruce Momjian <bruce(at)momjian(dot)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