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 <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com Do not let urgent matters crowd out time for investment in the future.
