Skip to content

Commit deb0734

Browse files
author
daobrien
committed
Merge branch 'dev'
Merge all the dev changes ready for release.
2 parents 649bc24 + c03cb99 commit deb0734

13 files changed

Lines changed: 92 additions & 45 deletions

File tree

‎en-US/Conventions_for_Writers_and_Editors.ent‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
<!ENTITY PRODUCT "Red Hat Style Guide">
22
<!ENTITY BOOKID "Writing_Style_Guide">
3-
<!ENTITY YEAR "2019">
3+
<!ENTITY YEAR "2020">
44
<!ENTITY HOLDER "Red Hat, Inc">

‎en-US/Design.xml‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -256,10 +256,10 @@ $ vi myFile.txt
256256
<title>Documenting Long Commands</title>
257257

258258
<screen># tar --selinux -czvf config_files.tar.gz /etc/katello \
259-
> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \
260-
> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \
261-
> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \
262-
> /root/ssl–build /var/www/html/pub/* /var/lib/katello
259+
> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \
260+
> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \
261+
> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \
262+
> /root/ssl–build /var/www/html/pub/* /var/lib/katello
263263

264264
# cd /var/lib/katello
265265

@@ -721,6 +721,38 @@ $ vi myFile.txt
721721
</para>
722722

723723
</section>
724+
725+
<section id="making-recommendations">
726+
<title>Making Recommendations</title>
727+
<para>
728+
When making a recommendation, the preferred verbiage is "Red&nbsp;Hat recommends..." instead of the common but indirect "It is recommended...".
729+
Recommendations can include best practices, recommended practices, and product-specific suggestions.
730+
Refer to <xref linkend="avoiding-confusing-language"/> for information on using the terms "best practices" and "recommended practices" in Red&nbsp;Hat documentation.
731+
</para>
732+
<example>
733+
<title>
734+
(incorrect)
735+
</title>
736+
<para>
737+
"Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project."
738+
</para>
739+
<para>
740+
"It is recommended to generate a service account for each microservice in your project."
741+
</para>
742+
</example>
743+
<example>
744+
<title>
745+
(correct)
746+
</title>
747+
<para>
748+
"Although the attack surface is reduced to the same-project traffic, Red&nbsp;Hat recommends creating multiple service accounts within a project."
749+
</para>
750+
<para>
751+
"Red&nbsp;Hat recommends that you generate a service account for each microservice in your project."
752+
</para>
753+
</example>
754+
</section>
755+
724756
<section id="citing-other-works">
725757
<title>Citing Other Works</title>
726758
<formalpara id="other-books">
@@ -779,6 +811,7 @@ $ vi myFile.txt
779811
</itemizedlist>
780812

781813
</section>
814+
782815
<section id="other-authors">
783816
<title>Citing Other Authors</title>
784817
<para>
@@ -794,4 +827,3 @@ $ vi myFile.txt
794827
</section>
795828

796829
</chapter>
797-

‎en-US/F.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@
9494
<term>file extensions (general usage)</term>
9595
<listitem>
9696
<para>
97-
Write file extensions in all caps and without periods (for example, "a PDF file"), unless the file name is also referenced (for example, "Save as example.pdf").
97+
See <citetitle>File names, file types, and directory names</citetitle> in <citetitle>The IBM Style Guide</citetitle>.
9898
</para>
9999

100100
</listitem>

‎en-US/Grammar.xml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -752,4 +752,3 @@
752752
</section>
753753

754754
</chapter>
755-

‎en-US/K.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
<term>kerberize</term>
3434
<listitem>
3535
<para>
36-
Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "kerberos-aware" or "Kerberos-enabled," or rewrite the sentence.
36+
Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence.
3737
</para>
3838

3939
</listitem>

‎en-US/N.xml‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,7 @@
2626
</listitem>
2727

2828
</varlistentry>
29-
<varlistentry id="neighbor">
30-
<term>neighbor</term>
31-
<listitem>
32-
<para>
33-
Correct. Do not use "neighbour."
34-
</para>
35-
36-
</listitem>
37-
38-
</varlistentry>
29+
3930
<varlistentry id="net">
4031
<term>.NET</term>
4132
<listitem>

‎en-US/O.xml‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,16 @@
8383
</para>
8484
</listitem>
8585

86+
</varlistentry>
87+
<varlistentry id="once">
88+
<term>once</term>
89+
<listitem>
90+
<para>
91+
Use only to mean "one time." Do not use as a conjunction to mean "after" or "when."
92+
</para>
93+
94+
</listitem>
95+
8696
</varlistentry>
8797
<varlistentry id="online">
8898
<term>online</term>
@@ -180,7 +190,8 @@
180190
<term>open source</term>
181191
<listitem>
182192
<para>
183-
Correct. Do not use "OpenSource," "opensource," or "open-source" (obviously, capitalize the "o" in "open source" at the beginning of a sentence).
193+
Correct. Do not use "OpenSource," "opensource," or "open-source."
194+
Only capitalize the "o" in "open source" at the beginning of a sentence.
184195
</para>
185196

186197
</listitem>
@@ -252,4 +263,3 @@
252263

253264
</variablelist>
254265
</chapter>
255-

‎en-US/R.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@
142142
<term>remote access server</term>
143143
<listitem>
144144
<para>
145-
A server that is dedicated to handling users that are not on a LAN but need remote access to it. The remote access server allows users to gain access to files and print services on the LAN from a remote location. For example, a user who dials into a network from home using an analog modem or an ISDN connection will dial into a remote access server. Once the user is authenticated they can access shared drives and printers as if they were physically connected to the office LAN.
145+
A server that is dedicated to handling users that are not on a LAN but need remote access to it. The remote access server allows users to gain access to files and print services on the LAN from a remote location. For example, a user who dials into a network from home using an analog modem or an ISDN connection will dial into a remote access server. After the user is authenticated they can access shared drives and printers as if they were physically connected to the office LAN.
146146
</para>
147147

148148
</listitem>
@@ -237,4 +237,3 @@
237237

238238
</variablelist>
239239
</chapter>
240-

‎en-US/S.xml‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,9 @@
138138
<term>SELinux</term>
139139
<listitem>
140140
<para>
141-
Short for Security-Enhanced Linux, SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies. Do not use alternatives such as "SLinux," "E Linux," or "SE Linux."
141+
Abbreviation of Security-Enhanced Linux.
142+
SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies.
143+
Do not use any other alternatives.
142144
</para>
143145

144146
</listitem>
@@ -374,7 +376,7 @@
374376
</para>
375377
</listitem>
376378
</varlistentry>
377-
379+
378380
<varlistentry id="smart-card">
379381
<term>smart card</term>
380382
<listitem>
@@ -385,7 +387,7 @@
385387
</listitem>
386388

387389
</varlistentry>
388-
390+
389391
<varlistentry id="socks">
390392
<term>SOCKS</term>
391393
<listitem>
@@ -523,10 +525,20 @@ a programming and technical sense this also means "Run the <command>source</comm
523525
<para>
524526
Initialism for Secure Shell, a network protocol that allows data exchange using a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use <command>ssh</command>.
525527
</para>
526-
<para>
527-
Do not use as a verb. For example, instead of "ssh to the remote server," write "Use SSH to connect to the remote server," "Open an SSH connection," or something similar.
528+
<para>
529+
Do not use as a verb.
530+
</para>
531+
<example>
532+
<title>
533+
Example Use of "SSH"
534+
</title>
535+
<para>
536+
Incorrect: To begin, "ssh to the remote server."
528537
</para>
529-
538+
<para>
539+
Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar.
540+
</para>
541+
</example>
530542
</listitem>
531543

532544
</varlistentry>
@@ -719,4 +731,3 @@ a programming and technical sense this also means "Run the <command>source</comm
719731

720732
</variablelist>
721733
</chapter>
722-

‎en-US/Slang.xml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,10 @@
2323
<para>
2424
This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red&nbsp;Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices."
2525
</para>
26-
27-
</listitem>
26+
<para>
27+
See the section <xref linkend="making-recommendations" /> for additional information about recommendations in Red&nbsp;Hat documentation.
28+
</para>
29+
</listitem>
2830

2931
</varlistentry>
3032
<varlistentry id="first-come-first-served">
@@ -872,4 +874,3 @@
872874
</section>
873875

874876
</chapter>
875-

0 commit comments

Comments
 (0)