On Thu, Jul 24, 2025 at 2:18 AM Bruce Momjian <br...@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
v1-0001-use-consistent-sgml-for-tables-and-columns.patch
Description: Binary data
