Inconsistent "<acronym>" use
Hackorum builds and tests every patch posted to the lists, not only commitfest submissions. This is Hackorum's own CI rather than the PostgreSQL project's, and it is still under testing - please report anything that looks wrong.
You can run a PostgreSQL built from this patch straight from Docker, with no checkout and no build:
docker run --rm -p 5432:5432 ghcr.io/hackorum-dev/postgres-patch:t43514psql -h localhost -U postgresBuilt from patchset v1 (message #1), July 27, 2026 at 05:51 PM.
Every patchset is also pushed to a branch of our PostgreSQL fork, so you can check out the same tree CI built. Without a PostgreSQL checkout:
git clone --branch t43514_1 https://github.com/hackorum-dev/postgres.gitIn a checkout you already have, add the fork once:
git remote add hackorum https://github.com/hackorum-dev/postgres.gitthen, for this patchset and every later one:
git fetch hackorum t43514_1 && git checkout t43514_1Patchset v1 (message #1) is on t43514_1
In doc/src/sgml/func.sgml description of SHOW command use
"<acronym>SQL</acronym>", while SET command description the same
section does not use "<acronym>". Shouldn't the description of SET use
"<acronym>" for "SQL" as well? Patch attached.
Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp
On Sun, Jan 10, 2021 at 08:22:42PM +0900, Tatsuo Ishii wrote:
In doc/src/sgml/func.sgml description of SHOW command use
"<acronym>SQL</acronym>", while SET command description the same
section does not use "<acronym>". Shouldn't the description of SET use
"<acronym>" for "SQL" as well? Patch attached.
https://tdg.docbook.org/tdg/5.2/acronym.html suggests docbook formatters
either ignore that <acronym> or use it as a signal to substitute small caps.
I don't consider small caps an improvement for "SQL", so I'd prefer to never
use <acronym>SQL</acronym>. <acronym> also makes the markup longer (though
one could mitigate that with an entity like &SQL). However, standardizing on
either way is better than varying within the manual.
On Sun, Jan 10, 2021 at 01:11:07PM -0800, Noah Misch wrote:
On Sun, Jan 10, 2021 at 08:22:42PM +0900, Tatsuo Ishii wrote:
In doc/src/sgml/func.sgml description of SHOW command use
"<acronym>SQL</acronym>", while SET command description the same
section does not use "<acronym>". Shouldn't the description of SET use
"<acronym>" for "SQL" as well? Patch attached.https://tdg.docbook.org/tdg/5.2/acronym.html suggests docbook formatters
either ignore that <acronym> or use it as a signal to substitute small caps.
I don't consider small caps an improvement for "SQL", so I'd prefer to never
use <acronym>SQL</acronym>. <acronym> also makes the markup longer (though
one could mitigate that with an entity like &SQL). However, standardizing on
either way is better than varying within the manual.
I think smallcaps is almost always a win for acronyms.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
Bruce Momjian <bruce@momjian.us> writes:
On Sun, Jan 10, 2021 at 01:11:07PM -0800, Noah Misch wrote:
https://tdg.docbook.org/tdg/5.2/acronym.html suggests docbook formatters
either ignore that <acronym> or use it as a signal to substitute small caps.
I don't consider small caps an improvement for "SQL", so I'd prefer to never
use <acronym>SQL</acronym>. <acronym> also makes the markup longer (though
one could mitigate that with an entity like &SQL). However, standardizing on
either way is better than varying within the manual.
I think smallcaps is almost always a win for acronyms.
I'm with Noah: small caps are *not* an improvement, they're just
distractingly fussy. I note that the authors of the stylesheets
we use seem to agree, because AFAICS <acronym> is not rendered
specially in either HTML or PDF output.
Given this docbook.org advice, I'd be inclined to just remove
our use of <acronym> altogether. Although, since it isn't actually
making any difference, it's not clear that it's worth doing anything.
The largest effect of trying to standardize (in either direction)
would be to create back-patching hazards for docs fixes.
regards, tom lane
I'm with Noah: small caps are *not* an improvement, they're just
distractingly fussy. I note that the authors of the stylesheets
we use seem to agree, because AFAICS <acronym> is not rendered
specially in either HTML or PDF output.Given this docbook.org advice, I'd be inclined to just remove
our use of <acronym> altogether. Although, since it isn't actually
making any difference, it's not clear that it's worth doing anything.
The largest effect of trying to standardize (in either direction)
would be to create back-patching hazards for docs fixes.
Yeah, simple grep showed that there are almost 1k lines using
<acronym>. I agree that the pain caused by fixing all of them is much
larger than the benefit to standardize the usage of <acronym>.
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp