Thread: Question: Do we have a rule to use "PostgreSQL" and "PostgreSQL" separately?

Dear hackers,

While checking documentations, I found that one line notes our product as
"<productname>PostgreSQL</productname>", whereas another line notes as just
"PostgreSQL". For example, in bgworker.sgml:

```
PostgreSQL can be extended to run user-supplied code in separate processes.
...
These processes are attached to <productname>PostgreSQL</productname>'s
shared memory area and have the option to connect to databases internally; ...
```

It seems that <productname> tag is not used when the string is used as link or
title, but I cannot find other rule to use them. Could you please tell me discussions
or wikipage about it?

Best Regards,
Hayato Kuroda
FUJITSU LIMITED

"Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> writes:
> While checking documentations, I found that one line notes our product as
> "<productname>PostgreSQL</productname>", whereas another line notes as just
> "PostgreSQL".

IMO the convention is to use the <productname> tag everywhere that we
spell out "PostgreSQL".  I don't think it's actually rendered differently
with our current stylesheets, but maybe someday it will be.

            regards, tom lane

> On 20 Mar 2023, at 15:31, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> "Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> writes:
>> While checking documentations, I found that one line notes our product as
>> "<productname>PostgreSQL</productname>", whereas another line notes as just
>> "PostgreSQL".
>
> IMO the convention is to use the <productname> tag everywhere that we
> spell out "PostgreSQL".  I don't think it's actually rendered differently
> with our current stylesheets, but maybe someday it will be.

IIRC the main use in DocBook is for automatically decorating productnames with
trademark signs etc, and to generate lists of trademarks, but also that they
can be rendered differently.

This reminded me that I was planning to apply the below to make the markup of
PostgreSQL consistent:

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 4df8bd1b64..9ff6b08f5a 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2667,7 +2667,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
      To complicate matters, some jurisdictions have used the same timezone
      abbreviation to mean different UTC offsets at different times; for
      example, in Moscow <literal>MSK</literal> has meant UTC+3 in some years and
-     UTC+4 in others.  <application>PostgreSQL</application> interprets such
+     UTC+4 in others.  <productname>PostgreSQL</productname> interprets such
      abbreviations according to whatever they meant (or had most recently
      meant) on the specified date; but, as with the <literal>EST</literal> example
      above, this is not necessarily the same as local civil time on that date.

--
Daniel Gustafsson

Dear Daniel, Tom,

> > On 20 Mar 2023, at 15:31, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >
> > "Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> writes:
> >> While checking documentations, I found that one line notes our product as
> >> "<productname>PostgreSQL</productname>", whereas another line notes
> as just
> >> "PostgreSQL".
> >
> > IMO the convention is to use the <productname> tag everywhere that we
> > spell out "PostgreSQL".  I don't think it's actually rendered differently
> > with our current stylesheets, but maybe someday it will be.
>
> IIRC the main use in DocBook is for automatically decorating productnames with
> trademark signs etc, and to generate lists of trademarks, but also that they
> can be rendered differently.

OK, I understood that even if the string is not rendered, that should be tagged as <productname>.

> IIRC the main use in DocBook is for automatically decorating productnames with
> trademark signs etc, and to generate lists of trademarks, but also that they
> can be rendered differently.
>
> This reminded me that I was planning to apply the below to make the markup of
> PostgreSQL consistent:

I have also grepped to detect another wrong markups, and I think at least
"<entry>PostgreSQL</entry>" should be changed. PSA the patch.

```
$ grep -rI \>PostgreSQL\< | grep -v productname
config.sgml:        the log. The default is <literal>PostgreSQL</literal>.
func.sgml:        <returnvalue>PostgreSQL</returnvalue>
func.sgml:        <entry>PostgreSQL</entry>
runtime.sgml:   event source named <literal>PostgreSQL</literal>.
problems.sgml:   The software package in total is called <quote>PostgreSQL</quote>,
ref/pg_ctl-ref.sgml:       default is <literal>PostgreSQL</literal>.  Note that this only controls
ref/pg_ctl-ref.sgml:       source name <literal>PostgreSQL</literal>.
ref/pg_ctl-ref.sgml:       The default is <literal>PostgreSQL</literal>.
```

Best Regards,
Hayato Kuroda
FUJITSU LIMITED

> On 22 Mar 2023, at 04:19, Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com> wrote:

> I have also grepped to detect another wrong markups, and I think at least
> "<entry>PostgreSQL</entry>" should be changed. PSA the patch.

I agree with that analysis, this instance should be marked up with
<productname> but not the other ones.  I'll go ahead with your patch after some
testing.

--
Daniel Gustafsson