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

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(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Do not let urgent matters crowd out time for investment in the future.