Обсуждение: Inconsistent "" 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 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