Inconsistent "<acronym>" use
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
Attachments:
func.difftext/x-patch; charset=us-asciiDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 02a37658ad..ecb66f9c3f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -24551,7 +24551,7 @@ SELECT collation for ('foo' COLLATE "de_DE");
If <parameter>is_local</parameter> is <literal>true</literal>, the new
value will only apply for the current transaction. If you want the new
value to apply for the current session, use <literal>false</literal>
- instead. This function corresponds to the SQL
+ instead. This function corresponds to the <acronym>SQL</acronym>
command <command>SET</command>.
</para>
<para>
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