public inbox for [email protected]  

help / color / mirror / Atom feed

From: Daniel Gustafsson <[email protected]>
To: Marcos Pegoraro <[email protected]>
Cc: PostgreSQL Hackers <[email protected]>
Subject: Re: <productname> on SGML files is used for what ?
Date: Thu, 5 Mar 2026 23:12:29 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAB-JLwZdry=DKpZT3brX37w8wn5rS3FrcRk+8XVbY=xhrfskrQ@mail.gmail.com>
References: <CAB-JLwZdry=DKpZT3brX37w8wn5rS3FrcRk+8XVbY=xhrfskrQ@mail.gmail.com>

> On 5 Mar 2026, at 19:53, Marcos Pegoraro <[email protected]> wrote:
> 
> Yesterday, Michael Paquier submitted this correction:
> Revert "Change the default value of default_toast_compression to "lz4""
> which is in the installation.sgml has:
>          Build with <productname>LZ4</productname> compression support.
> But other SGML files on that commit are all using literal tag.
> So I thought, LZ4 is not a product name, so where else is this tag used ?
> And that tag is used for Kerberos, Zstandard, GSSAPI, SSPI, Windows, Oracle and others. So, there are company names, programs, protocols, utilities and others.

The DocBook manual is the main source for truth about when to use the various
tags, <productname> is documented in [1].  So Oracle is clearly a productname
if it refers to the database and not the company, but Windows should probably
use <systemitem class="osname"> [1] instead.  Whether or not LZ4 is a product
name feels harder to define, but it doesn't seem entirely wrong, especially not
for the installation docs.

Mind you, we aren't using the tagging exactly according to the specification so
appropriate levels of salt should be applied, for example <application> is
meant to be used for larger software packages whereas we apply it pg_dump etc.

> Do these need to use the <literal> tag, or do we need an additional one, or perhaps a tag for each of these types ?

<literal> is IMHO great for tagging text to indicate that it is expected system
input/output or source code.  Depending on context, lz4 could absolutely use
<literal> (but personally I think we should be careful to not overuse
<literal>).

--
Daniel Gustafsson

[0] https://tdg.docbook.org/tdg/5.0/productname.html
[1] https://tdg.docbook.org/tdg/5.0/systemitem.html

view thread (8+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: <productname> on SGML files is used for what ?
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox