Skip to content

Commit 2298922

Browse files
julian-cablejulian-cable
authored
Applied second batch of enhancements for 6.0 (#419)
* First changes for Enhancements 2 * Adding next batch of enhancements * Added further enhancements * Implemented fixes from review
1 parent be533cf commit 2298922

File tree

7 files changed

+338
-10
lines changed

7 files changed

+338
-10
lines changed

‎en-US/Design.xml

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -702,7 +702,7 @@ $ vi myFile.txt
702702
<section id="refer-object-names">
703703
<title>Referring to Object Names</title>
704704
<para>
705-
Do not use object names as part of normative grammar. A sentence should be complete without the object name.
705+
When using object names, write a sentence so that it is complete without the object name.
706706
</para>
707707

708708
<table>
@@ -721,7 +721,77 @@ $ vi myFile.txt
721721
<tbody>
722722
<row>
723723
<entry> Find the current default <systemitem>StorageClass</systemitem>. </entry>
724-
<entry> Either: Find the current default storage class. Or: Find the current default <systemitem>StorageClass</systemitem> value. </entry>
724+
<entry>
725+
<para>
726+
Either: Find the current default storage class.
727+
</para>
728+
<para>
729+
Or: Find the current default <systemitem>StorageClass</systemitem> value.
730+
</para>
731+
</entry>
732+
733+
</row>
734+
735+
</tbody>
736+
737+
</tgroup>
738+
739+
</table>
740+
<para>
741+
Avoid starting or ending a sentence with an object name.
742+
</para>
743+
744+
<table>
745+
<title></title>
746+
<tgroup cols="2" colsep="1" rowsep="1">
747+
<colspec colname="c1"></colspec>
748+
<colspec colname="c2"></colspec>
749+
<thead>
750+
<row>
751+
<entry> Example </entry>
752+
<entry> Improvement </entry>
753+
754+
</row>
755+
756+
</thead>
757+
<tbody>
758+
<row>
759+
<entry> <systemitem>Umount /mnt/save</systemitem>. </entry>
760+
<entry> Unmount the <filename>/mnt/save</filename> directory. </entry>
761+
762+
</row>
763+
<row>
764+
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this <systemitem>nameserver</systemitem>. </entry>
765+
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this name server. </entry>
766+
767+
</row>
768+
769+
</tbody>
770+
771+
</tgroup>
772+
773+
</table>
774+
<para>
775+
Place an object name before the noun that it modifies rather than after the noun.
776+
</para>
777+
778+
<table>
779+
<title></title>
780+
<tgroup cols="2" colsep="1" rowsep="1">
781+
<colspec colname="c1"></colspec>
782+
<colspec colname="c2"></colspec>
783+
<thead>
784+
<row>
785+
<entry> Example </entry>
786+
<entry> Improvement </entry>
787+
788+
</row>
789+
790+
</thead>
791+
<tbody>
792+
<row>
793+
<entry> Enable the default module stream for the module <systemitem>python36</systemitem> and install all packages from that stream. </entry>
794+
<entry> Enable the default module stream for the <systemitem>python36</systemitem> module and install all packages from that stream. </entry>
725795

726796
</row>
727797

‎en-US/Grammar.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -590,7 +590,7 @@ Split contractions and abbreviations into separate paragraphs. -->
590590
Do not hyphenate "open source", even when used as a complex adjective.
591591
</para>
592592
<para>
593-
Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82.
593+
Do not hyphenate a compound that includes an adverb that ends in <emphasis>-ly</emphasis>, whether it comes before or after the noun, because it is never ambiguous. This is described in Chicago Manual of Style 7.82. For example, "Red&nbsp;Hat Enterprise Linux is a production-ready, commercially supported Linux distribution."
594594
</para>
595595

596596
</note>

‎en-US/L.xml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,17 @@
104104
</listitem>
105105

106106
</varlistentry>
107+
<varlistentry id="like">
108+
<term>lifecycle</term>
109+
<listitem>
110+
<para>
111+
Avoid "like" to mean "such as".
112+
For example, instead of "Namespaces can include resources like network interfaces", use "Namespaces can include resources such as network interfaces".
113+
</para>
114+
115+
</listitem>
116+
117+
</varlistentry>
107118
<varlistentry id="linux">
108119
<term>Linux</term>
109120
<listitem>

‎en-US/Language.xml

Lines changed: 81 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1063,12 +1063,26 @@
10631063
<tbody>
10641064
<row>
10651065
<entry> The <methodname>next()</methodname> method should return <code>null</code> to indicate the end of results. </entry>
1066-
<entry> The <methodname>next()</methodname> method is expected to return <code>null</code> to indicate the end of results. <emphasis>OR</emphasis> The <methodname>next()</methodname> method must return <code>null</code> to indicate the end of results. </entry>
1066+
<entry>
1067+
<para>
1068+
The <methodname>next()</methodname> method is expected to return <code>null</code> to indicate the end of results.
1069+
</para>
1070+
<para>
1071+
<emphasis>Or:</emphasis> The <methodname>next()</methodname> method must return <code>null</code> to indicate the end of results.
1072+
</para>
1073+
</entry>
10671074

10681075
</row>
10691076
<row>
10701077
<entry> It may be held in memory. </entry>
1071-
<entry> It can be held in memory. <emphasis>OR</emphasis> It might be held in memory. </entry>
1078+
<entry>
1079+
<para>
1080+
It can be held in memory.
1081+
</para>
1082+
<para>
1083+
<emphasis>Or:</emphasis> It might be held in memory.
1084+
</para>
1085+
</entry>
10721086

10731087
</row>
10741088

@@ -1108,7 +1122,14 @@
11081122
</row>
11091123
<row>
11101124
<entry> To create another administrator, click <guimenuitem>New</guimenuitem> on the <guimenuitem>File</guimenuitem> menu. </entry>
1111-
<entry> To create another administrator account, click <guimenuitem>New</guimenuitem> on the <guimenuitem>File</guimenuitem> menu. <emphasis>OR</emphasis> To set privileges for another administrator, click <guimenuitem>New</guimenuitem> on the <guimenuitem>File</guimenuitem> menu. </entry>
1125+
<entry>
1126+
<para>
1127+
To create another administrator account, click <guimenuitem>New</guimenuitem> on the <guimenuitem>File</guimenuitem> menu.
1128+
</para>
1129+
<para>
1130+
<emphasis>Or:</emphasis> To set privileges for another administrator, click <guimenuitem>New</guimenuitem> on the <guimenuitem>File</guimenuitem> menu.
1131+
</para>
1132+
</entry>
11121133

11131134
</row>
11141135

@@ -1151,7 +1172,14 @@
11511172
<row>
11521173
<entry> Use the utility to run activities and save your settings. </entry>
11531174
<!-- Split into 2 sentences -->
1154-
<entry> Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). </entry>
1175+
<entry> Depending on the meaning:
1176+
<para>
1177+
Use the utility to run activities and to save your settings (if the utility does both functions).
1178+
</para>
1179+
<para>
1180+
<emphasis>Or:</emphasis> Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one).
1181+
</para>
1182+
</entry>
11551183

11561184
</row>
11571185

@@ -1200,6 +1228,55 @@
12001228
</listitem>
12011229
</varlistentry>
12021230

1231+
<varlistentry id="misplaced-only">
1232+
<term> Misplaced Only </term>
1233+
<listitem>
1234+
<para>
1235+
Ensure that "only" is placed directly before the word that it modifies, which often should not be a verb.
1236+
</para>
1237+
<table>
1238+
<title></title>
1239+
<tgroup cols="2" colsep="1" rowsep="1">
1240+
<colspec colname="c1"></colspec>
1241+
<colspec colname="c2"></colspec>
1242+
<thead>
1243+
<row>
1244+
<entry> Example </entry>
1245+
<entry> Improvement </entry>
1246+
1247+
</row>
1248+
1249+
</thead>
1250+
<tbody>
1251+
<row>
1252+
<entry>
1253+
<para>
1254+
Users can only delete files that they own.
1255+
</para>
1256+
<para>
1257+
(Misleadingly suggests that users cannot take any actions other than deletion on those files)
1258+
</para>
1259+
</entry>
1260+
<entry>
1261+
<para>
1262+
Users can delete only files that they own.
1263+
</para>
1264+
<para>
1265+
(Clarifies the files that deletion applies to)
1266+
</para>
1267+
</entry>
1268+
1269+
</row>
1270+
1271+
</tbody>
1272+
1273+
</tgroup>
1274+
1275+
</table>
1276+
1277+
</listitem>
1278+
</varlistentry>
1279+
12031280
<varlistentry id="pronoun">
12041281
<term>Pronouns</term>
12051282
<listitem>

‎en-US/O.xml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,12 @@
9494
<para>
9595
Use only to mean "one time". Do not use as a conjunction to mean "after" or "when".
9696
</para>
97+
<para>
98+
Example 1: Instead of "Once the name is set for a network interface on the system, the name of the interface does not change", use "When the name is set for a network interface on the system, the name of the interface does not change".
99+
</para>
100+
<para>
101+
Example 2: Instead of "Once you generate the SSH keys, you can find them by default in the <filename>.ssh/</filename> directory", use "After you generate the SSH keys, you can find them by default in the <filename>.ssh/</filename> directory".
102+
</para>
97103

98104
</listitem>
99105

‎en-US/Punctuation.xml

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,37 @@
422422
If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside.
423423
</para>
424424

425+
<para>
426+
Do not use "(s)" in parentheses to denote a plural. If something can be singular or plural, make it plural.
427+
</para>
428+
429+
430+
<table>
431+
<title></title>
432+
<tgroup cols="2" colsep="1" rowsep="1">
433+
<colspec colname="c1"></colspec>
434+
<colspec colname="c2"></colspec>
435+
<thead>
436+
<row>
437+
<entry> Example </entry>
438+
<entry> Improvement </entry>
439+
440+
</row>
441+
442+
</thead>
443+
<tbody>
444+
<row>
445+
<entry> Choose the item(s). </entry>
446+
<entry> Choose the items. </entry>
447+
448+
</row>
449+
450+
</tbody>
451+
452+
</tgroup>
453+
454+
</table>
455+
425456
</section>
426457
<section id="slashes">
427458
<title>Slashes</title>
@@ -446,7 +477,11 @@
446477
<para>
447478
Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside.
448479
</para> -->
449-
480+
<para>
481+
When indicating the start or end of a direct quotation, use curly quotation marks.
482+
In all other contexts, such as when writing code samples, code syntax, hexadecimal numbers, or hypertext links, use straight quotation marks.
483+
Refer to the "Typographical Considerations" section in the "Quotation Marks" topic in the <citetitle>IBM Style Guide</citetitle>.
484+
</para>
450485
<para>
451486
In technical documentation, place punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons inside the quotation marks if they are part of the quotation or part of a programming element that uses quotation marks; if not, place punctuation marks outside the quotation marks.
452487
If a sentence ends with a quotation, use only one punctuation mark to end the sentence, and place it inside the closing quotation mark if it is part of the quotation, or outside if it is not.

0 commit comments

Comments
 (0)