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
