Skip to content

Commit 988a010

Browse files
daobriendaobrien
authored
Merge pull request #276 from StyleGuides/dev
Merge dev to master for 5.0 release
2 parents 819f895 + 5b27ae5 commit 988a010

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+3293
-2052
lines changed

‎LICENSE‎

Lines changed: 427 additions & 116 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various g
77

88
It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases.
99

10-
It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Collegiate Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions.
10+
It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions.

‎en-US/0-9.xml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
<!ENTITY % BOOK_ENTITIES SYSTEM "Conventions_for_Writers_and_Editors.ent">
44
%BOOK_ENTITIES;
55
]>
6+
<!-- Suggest not to use numbered chapters for these group separator headings. -->
67
<chapter id="a0-9">
78
<title>0-9</title>
89
<variablelist>
@@ -20,7 +21,7 @@
2021
<term>2-track (IT)</term>
2122
<listitem>
2223
<para>
23-
<emphasis>adj.</emphasis> A less common way to refer to bimodal or hybrid IT. See <xref linkend="bimodal-it" />
24+
<emphasis>adj.</emphasis> A less common way to refer to bimodal or hybrid IT. See <xref linkend="bimodal-it" />.
2425
</para>
2526

2627
</listitem>
@@ -30,7 +31,7 @@
3031
<term>3-D</term>
3132
<listitem>
3233
<para>
33-
<emphasis>adj., n.</emphasis>. Correct. Do not use 3D, 3-d, or other variations.
34+
<emphasis>adj., n.</emphasis> Correct. Do not use 3D, 3-d, or other variations.
3435
</para>
3536

3637
</listitem>

‎en-US/A.xml‎

Lines changed: 104 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,32 @@
55
]>
66
<chapter id="a">
77
<title>A</title>
8+
<!-- Some of the entries were not listed in alphabetical order. -->
89
<variablelist>
10+
<!-- Entries previously used a mixture of "v." and "vb." to denote a verb. Changed all occurrences to "v." -->
911
<varlistentry id="amp-and-">
1012
<term>"&amp;" and "+"</term>
1113
<listitem>
1214
<para>
13-
Ampersands or plus signs can be used in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy.
15+
Ampersands or plus signs can be used instead of the word "and" in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy.
16+
</para>
17+
</listitem>
18+
19+
</varlistentry>
20+
<varlistentry id="above">
21+
<term role="caution">above</term>
22+
<listitem>
23+
<para>
24+
Do not use to refer to information that was mentioned previously.
25+
When documents are converted to online format, the information might no longer be "above."
26+
Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead.
1427
</para>
1528

1629
</listitem>
1730

1831
</varlistentry>
32+
<!-- Removed "acronyms" entry (as it is not a literal term) and added this content instead to section 3.6. -->
33+
1934
<varlistentry id="agile-development">
2035
<term role="true">agile</term>
2136
<term role="true">agile development</term>
@@ -37,128 +52,83 @@
3752

3853
</listitem>
3954

40-
</varlistentry>
41-
<varlistentry id="am">
42-
<term role="true">a.m.</term>
43-
<term role="false">am</term>
44-
<listitem>
45-
<para>
46-
Correct. Use the lowercase form and include the periods, and use a preceding space.
47-
</para>
48-
<para>
49-
See also <xref linkend="pm"/>.
50-
</para>
51-
<para>
52-
See <citetitle>The IBM Style Guide</citetitle> for a full discussion of how to represent times.
53-
</para>
54-
55-
</listitem>
56-
5755
</varlistentry>
5856
<varlistentry id="all-in-one">
5957
<term role="true">all-in-one</term>
6058
<term role="false">allinone</term>
6159
<listitem>
6260
<para>
63-
<emphasis>n., adj.</emphasis> Correct. Hyphenate in both cases. Do not use "allinone" or other variations.
61+
<emphasis>n., adj.</emphasis> Hyphenate in both places. Do not use "allinone" or other variations.
6462
</para>
6563

6664
</listitem>
6765

6866
</varlistentry>
69-
<varlistentry id="AMD64">
70-
<term role="true">AMD64</term>
67+
68+
<varlistentry id="alternate">
69+
<term role="true">alternate</term>
7170
<listitem>
7271
<para>
73-
Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture.
74-
</para>
75-
<para>
76-
The correct term for AMD's implementation of this architecture is "AMD64."
77-
When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically.
72+
<emphasis>v.</emphasis> "Alternate" as a verb means to change between two states or options.
7873
</para>
7974
<para>
80-
See also <xref linkend="Intel64"/>.
75+
See also <xref linkend="alternative"/>.
8176
</para>
82-
<note>
83-
<para>
84-
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="http://www.amd.com/us/aboutamd/Pages/trademarks.aspx" />.
85-
</para>
86-
<para>
87-
For more information about Intel&reg; trademarks, see <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />.
88-
</para>
89-
90-
</note>
9177

9278
</listitem>
9379

9480
</varlistentry>
95-
<varlistentry id="atm">
96-
<term role="true">ATM</term>
81+
82+
<varlistentry id="alternative">
83+
<term role="true">alternative</term>
9784
<listitem>
9885
<para>
99-
Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size.
100-
The cell size used with ATM is relatively small compared to units used with older technologies.
86+
<emphasis>adj.</emphasis> Describes another way or method of doing something.
87+
"Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..."
10188
</para>
89+
<para>
90+
See also <xref linkend="alternate"/>.
91+
</para>
10292

10393
</listitem>
10494

10595
</varlistentry>
106-
<varlistentry id="above">
107-
<term role="caution">above</term>
96+
<varlistentry id="am">
97+
<term role="true">AM</term>
10898
<listitem>
10999
<para>
110-
Do not use to refer to information mentioned previously.
111-
When documents are converted to online format, the information may no longer be "above."
112-
Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead.
113-
</para>
100+
For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11&nbsp;AM".
101+
</para>
102+
<para>
103+
See also <xref linkend="pm"/>.
104+
</para>
114105

115106
</listitem>
116107

117108
</varlistentry>
118-
<varlistentry id="acronyms">
119-
<term>acronyms</term>
109+
<varlistentry id="AMD64">
110+
<term role="true">AMD64</term>
120111
<listitem>
121112
<para>
122-
An acronym is a word formed from the initial letters of a name, such as ROM for <emphasis>R</emphasis>ead <emphasis>O</emphasis>nly <emphasis>M</emphasis>emory, or by combining initial letters or part of a series of words, such as LILO for <emphasis>LI</emphasis>nux <emphasis>LO</emphasis>ader.
123-
Note that an acronym is pronounced as a word.
124-
Compare this to an initialism, which is also formed in a similar fashion to an acronym, but in which each letter is pronounced separately.
125-
</para>
126-
<para>
127-
Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK)..."
128-
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version - for example, "central processing unit (CPU)."
129-
Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML.
113+
Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture.
130114
</para>
131115
<para>
132-
To form the plural of an acronym, add a trailing, lowercase "s," or "es," for example, ROMs, PINs, BIOSes.
133-
</para>
134-
135-
</listitem>
136-
137-
</varlistentry>
138-
<varlistentry id="alternate">
139-
<term role="true">alternate</term>
140-
<listitem>
141-
<para>
142-
<emphasis>vb.</emphasis> "Alternate" as a verb means to change between two states or options.
116+
The correct term for AMD's implementation of this architecture is "AMD64."
117+
When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically.
143118
</para>
144119
<para>
145-
See also <xref linkend="alternative"/>.
120+
See also <xref linkend="Intel64"/>.
146121
</para>
122+
<note>
123+
<para>
124+
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />.
125+
</para>
126+
<!-- Updated URL for AMD trademarks. -->
127+
<para>
128+
For more information about Intel&reg; trademarks, see <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />.
129+
</para>
147130

148-
</listitem>
149-
150-
</varlistentry>
151-
152-
<varlistentry id="alternative">
153-
<term role="true">alternative</term>
154-
<listitem>
155-
<para>
156-
<emphasis>adj.</emphasis> Used to describe another way or method of doing something.
157-
"Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to..."
158-
</para>
159-
<para>
160-
See also <xref linkend="alternate"/>.
161-
</para>
131+
</note>
162132

163133
</listitem>
164134

@@ -170,12 +140,26 @@
170140
Avoid if possible.
171141
Try to rewrite to make the available options explicit and clear.
172142
Do not write <emphasis>this and/or that</emphasis>.
173-
Write <emphasis>this or that or both</emphasis>.
143+
Write <emphasis>this or that, or both</emphasis>.
174144
</para>
175145

176146
</listitem>
177147

178148
</varlistentry>
149+
150+
<!-- Added "appendixes" entry. -->
151+
<varlistentry id="appendixes">
152+
<term>appendixes</term>
153+
<listitem>
154+
<para>
155+
Correct. This is the correct plural form for US English spelling. Do not use "appendices."
156+
</para>
157+
158+
</listitem>
159+
160+
</varlistentry>
161+
162+
<!-- Commenting out this entry as it is not a literal term entry. Consider moving elsewhere, such as to Section 3.7 and expand scope of that section?
179163
<varlistentry id="application">
180164
<term>application</term>
181165
<listitem>
@@ -193,13 +177,15 @@
193177
</listitem>
194178
195179
</varlistentry>
180+
-->
181+
196182
<varlistentry id="applixware">
197183
<term role="true">Applixware</term>
198184
<term role="false">Applix</term>
199185
<term role="false">ApplixWare</term>
200186
<listitem>
201187
<para>
202-
Correct.
188+
"Applixware" is correct.
203189
Do not use "Applix" or "ApplixWare."
204190
</para>
205191

@@ -211,9 +197,9 @@
211197
<listitem>
212198
<para>
213199
Do not use as a verb.
214-
Even though it might make sense in the correct context, using it as a verb can be jargon or unclear for your audience.
200+
Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience.
215201
Use "design," "build," "create," or another descriptive verb instead.
216-
Before replacing the verb form of "architect" during the editing process, check with the writer to find out the intended meaning.
202+
Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning.
217203
For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding."
218204
</para>
219205
</listitem>
@@ -235,7 +221,7 @@
235221
<term role="caution">as-a-Service</term>
236222
<listitem>
237223
<para>
238-
Be aware that there is a great deal of overlap in as-a-Service acronyms.
224+
Some as-a-Service acronyms overlap.
239225
To avoid confusion, always spell out the full term on first use.
240226
</para>
241227
<itemizedlist>
@@ -259,7 +245,7 @@
259245
</listitem>
260246
<listitem>
261247
<para>
262-
FaaS (Function[s]-as-a-Service)
248+
FaaS (Functions-as-a-Service)
263249
</para>
264250

265251
</listitem>
@@ -301,27 +287,28 @@
301287
<itemizedlist>
302288
<listitem>
303289
<para>
304-
Capitalize the noun (e.g., Platform, Software, Infrastructure) and Service, both when abbreviated and written out.
290+
Capitalize the noun (such as Platform, Software, Infrastructure) and Service, both when abbreviated and when written out.
305291
</para>
306292

307293
</listitem>
308294
<listitem>
309295
<para>
310-
When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (e.g., INTRODUCTION TO PaaS SOLUTIONS).
296+
When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS).
311297
</para>
298+
<!-- When would all capitals be used? -->
312299

313300
</listitem>
314301
<listitem>
315302
<para>
316303
Hyphenate when written out: Thing-as-a-Service.
317-
For two-word prefixes, do not include a hyphen between the first and second words: Mobile Backend-as-a-Service.
318-
Can be used as an adjective to describe multiple (e.g., when referring to an IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording).
304+
For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service.
305+
It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording.
319306
</para>
320307

321308
</listitem>
322309
<listitem>
323310
<para>
324-
Avoid an acronym if it could stand for more than one term in a single asset (e.g., if you're writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service).
311+
Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service.
325312
</para>
326313

327314
</listitem>
@@ -330,7 +317,30 @@
330317

331318
</listitem>
332319

320+
<!-- Suggested addition of "as long as" -->
333321
</varlistentry>
322+
<varlistentry id="as-long-as">
323+
<term role="caution">as long as</term>
324+
<listitem>
325+
<para>
326+
Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that".
327+
</para>
328+
329+
</listitem>
330+
331+
</varlistentry>
332+
<varlistentry id="atm">
333+
<term role="true">ATM</term>
334+
<listitem>
335+
<para>
336+
Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size.
337+
The cell size used with ATM is relatively small compared to units that are used with older technologies.
338+
</para>
339+
340+
</listitem>
341+
342+
</varlistentry>
343+
334344
<!--<varlistentry id="auto-detect">
335345
<term>auto-detect</term>
336346
<listitem>
@@ -346,7 +356,7 @@
346356
<listitem>
347357
<para>
348358
Always lowercase.
349-
This refers to the kernel-based automount utility.
359+
It refers to the kernel-based automount utility.
350360
No other forms are recognized.
351361
</para>
352362

0 commit comments

Comments
 (0)