Skip to content

Commit ae704b2

Browse files
julian-cabledaobriendaobrienmweetman-redhatCBID2
authored
Merge commits from dev to master branch for 6.2 release (#565)
* Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) * 6.2 quick fixes (#544) * Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes * Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix * Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit * Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review * Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry * Reworked entries for tar, tarball, untar, unzip, zip (#552) * Clarify capitalization for table titles (#553) * Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments * Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks * Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' * Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable <jcable@redhat.com> * fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable <jcable@redhat.com> * Corrected some titles to use title case (#563) * Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix --------- Co-authored-by: daobrien <noreply@solaris.milky.way> Co-authored-by: David O'Brien <daobrien@users.noreply.github.com> Co-authored-by: mweetman-redhat <mweetman@redhat.com> Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Harpal Singh <52556240+harpasin@users.noreply.github.com> Co-authored-by: Alex Corcoles <alex@pdp7.net>
1 parent 4c54b6d commit ae704b2

36 files changed

+926
-288
lines changed

‎README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,19 @@ The Red&nbsp;Hat Style Guide and Word Usage Dictionary is a joint effort by vari
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

1010
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.
11+
12+
Dependencies:
13+
14+
```
15+
$ sudo dnf install publican
16+
```
17+
18+
Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that.
19+
20+
To build:
21+
22+
```
23+
$ publican build --langs=en-US --formats html
24+
```
25+
26+
Generates `tmp/en-US/html/index.html`.

‎build

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/bin/sh
2+
3+
publican build --langs en-US --formats html

‎en-US/0-9.xml

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
<term>2-track (IT)</term>
2222
<listitem>
2323
<para>
24-
<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. Refer to <xref linkend="bimodal-it" />.
2525
</para>
2626

2727
</listitem>
@@ -38,6 +38,77 @@
3838

3939
</varlistentry>
4040

41+
<varlistentry id="a64-bit">
42+
<term role="true">64-bit ARM</term>
43+
<listitem>
44+
<para>
45+
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
46+
This term can refer to both AArch66/`aarch64` and to ARM64/`arm64`.
47+
</para>
48+
<para>
49+
Use this format in general cases to refer to names of the architecture for various cloud providers.
50+
</para>
51+
<para>
52+
Cloud providers might use different formats of this term to refer to architectures.
53+
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
54+
</para>
55+
<para>
56+
Examples:
57+
</para>
58+
<itemizedlist>
59+
<listitem>
60+
<para>
61+
Amazon Web Services (AWS) on 64-bit ARM systems
62+
</para>
63+
</listitem>
64+
<listitem>
65+
<para>
66+
Machine types for Microsoft Azure on 64-bit ARM infrastructures
67+
</para>
68+
</listitem>
69+
</itemizedlist>
70+
<para>
71+
Refer also to <xref linkend="a64-bit-x86"/>, <xref linkend="aarch64"/>, <xref linkend="AMD64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
72+
</para>
73+
74+
</listitem>
75+
76+
</varlistentry>
77+
<varlistentry id="a64-bit-x86">
78+
<term role="true">64-bit x86</term>
79+
<listitem>
80+
<para>
81+
<emphasis>n.</emphasis> A 64-bit version of the x86 architecture.
82+
This term is a synonym of x86_64.
83+
Use this format in general cases to refer to names of the architecture for various cloud providers.
84+
</para>
85+
<para>
86+
Cloud providers might use different formats of this term to refer to architectures.
87+
If you are documenting code, commands or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
88+
</para>
89+
<para>
90+
Examples:
91+
</para>
92+
<itemizedlist>
93+
<listitem>
94+
<para>
95+
Amazon Web Services (AWS) on 64-bit x86 systems
96+
</para>
97+
</listitem>
98+
<listitem>
99+
<para>
100+
Machine types for Microsoft Azure on 64-bit x86 infrastructures
101+
</para>
102+
</listitem>
103+
</itemizedlist>
104+
<para>
105+
Refer also to <xref linkend="a64-bit"/>, <xref linkend="aarch64"/>, <xref linkend="AMD64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
106+
</para>
107+
108+
</listitem>
109+
110+
</varlistentry>
111+
41112
</variablelist>
42113
</chapter>
43114

‎en-US/A.xml

Lines changed: 114 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@
6969
<emphasis>v.</emphasis> "Alternate" as a verb means to change between two states or options.
7070
</para>
7171
<para>
72-
See also <xref linkend="alternative"/>.
72+
Refer also to <xref linkend="alternative"/>.
7373
</para>
7474

7575
</listitem>
@@ -84,7 +84,7 @@
8484
"Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something", use "an alternative method is to ...".
8585
</para>
8686
<para>
87-
See also <xref linkend="alternate"/>.
87+
Refer also to <xref linkend="alternate"/>.
8888
</para>
8989

9090
</listitem>
@@ -97,38 +97,140 @@
9797
For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11&nbsp;AM".
9898
</para>
9999
<para>
100-
See also <xref linkend="pm"/>.
100+
Refer also to <xref linkend="pm"/>.
101+
</para>
102+
103+
</listitem>
104+
105+
</varlistentry>
106+
<varlistentry id="aarch64">
107+
<term role="true">AArch64, aarch64</term>
108+
<listitem>
109+
<para>
110+
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
111+
Use this term when referring to operating systems and server instances, for example Red&nbsp;Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions.
112+
</para>
113+
<para>
114+
Use the uppercase (AArch64) format in general cases when referring to system architecture.
115+
Use the lowercase (aarch64) format only when referring to objects or parameters.
116+
It can be styled as code (monospace font or a code-styled block) when referring to code.
117+
</para>
118+
<para>
119+
Cloud providers might use different formats of this term to refer to architectures.
120+
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
121+
</para>
122+
<para>
123+
Examples:
124+
</para>
125+
<itemizedlist>
126+
<listitem>
127+
<para>
128+
When running Red&nbsp;Hat Enterprise Linux with an AArch64 system, run the following commands:
129+
</para>
130+
</listitem>
131+
<listitem>
132+
<para>
133+
Specify the system architecture of your cluster, such as <code>x86_64</code> or <code>aarch64</code>.
134+
</para>
135+
</listitem>
136+
</itemizedlist>
137+
<para>
138+
Refer also to <xref linkend="a64-bit"/>, <xref linkend="a64-bit-x86"/>, <xref linkend="AMD64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
101139
</para>
102140

103141
</listitem>
104142

105143
</varlistentry>
106144
<varlistentry id="AMD64">
107-
<term role="true">AMD64</term>
145+
<term role="true">AMD64, amd64</term>
108146
<listitem>
109147
<para>
110-
Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86" or other variations as the name of this architecture.
148+
<emphasis>n.</emphasis> The AMD 64-bit version of the x86 architecture.
149+
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), or command-line interface (CLI) objects.
111150
</para>
112151
<para>
113-
The correct term for AMD's implementation of this architecture is "AMD64".
114-
When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically.
152+
Use the uppercase format (AMD64) in general sentences when referring to Red&nbsp;Hat OpenShift Container Platform features.
153+
Use the lowercase format (amd64) only when referring to objects or parameters.
154+
It can be styled as code (monospace font or a code-styled block) when referring to code.
155+
</para>
156+
<para>
157+
Cloud providers might use different formats of this term to refer to architectures.
158+
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
159+
</para>
160+
<para>
161+
Examples:
115162
</para>
163+
<itemizedlist>
164+
<listitem>
165+
<para>
166+
This operator is supported on AMD64 and ARM64 platforms.
167+
</para>
168+
</listitem>
169+
<listitem>
170+
<para>
171+
In this scenario, <code>amd64</code> is a valid value for X.
172+
</para>
173+
</listitem>
174+
</itemizedlist>
175+
<!-- <para>
176+
The correct term for AMD's implementation of this architecture is "AMD64".
177+
When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically.
178+
</para> -->
116179
<para>
117-
See also <xref linkend="Intel64"/>.
180+
Refer also to <xref linkend="a64-bit"/>, <xref linkend="a64-bit-x86"/>, <xref linkend="aarch64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
118181
</para>
119-
<note>
182+
<!-- <note>
120183
<para>
121-
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" />.
184+
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, refer to the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />.
122185
</para>
123186
<para>
124-
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" />.
187+
For more information about Intel&reg; trademarks, refer to <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" />.
125188
</para>
126189
127-
</note>
190+
</note> -->
191+
192+
</listitem>
193+
194+
</varlistentry>
195+
<varlistentry id="ARM64">
196+
<term role="true">ARM64, arm64</term>
197+
<listitem>
198+
<para>
199+
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
200+
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), and command-line interface (CLI) objects.
201+
</para>
202+
<para>
203+
Use the uppercase format (ARM64) in general sentences when referring to Red&nbsp;Hat OpenShift Container Platform features.
204+
Use lowercase format (arm64) only when referring to objects or parameters.
205+
It can be styled as code (monospace font or a code-styled block) when referring to code.
206+
</para>
207+
<para>
208+
Cloud providers might use different formats of this term to refer to architectures.
209+
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
210+
</para>
211+
<para>
212+
Examples:
213+
</para>
214+
<itemizedlist>
215+
<listitem>
216+
<para>
217+
In this exercise, you create an ARM64 compute machine set.
218+
</para>
219+
</listitem>
220+
<listitem>
221+
<para>
222+
In this scenario, <code>arm64</code> is a valid value for X.
223+
</para>
224+
</listitem>
225+
</itemizedlist>
226+
<para>
227+
Refer also to <xref linkend="a64-bit"/>, <xref linkend="a64-bit-x86"/>, <xref linkend="aarch64"/>, <xref linkend="AMD64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
228+
</para>
128229

129230
</listitem>
130231

131232
</varlistentry>
233+
132234
<varlistentry id="andor">
133235
<term role="false">and/or</term>
134236
<listitem>

‎en-US/B.xml

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
Use the one-word form only if it is part of the established product terminology, for example "Mobile Backend-as-a-Service", and when it is not being used to describe a generic process.
2020
</para>
2121
<para>
22-
See also <xref linkend="front-end" />
22+
Refer also to <xref linkend="front-end" />
2323
</para>
2424

2525
</listitem>
@@ -73,7 +73,7 @@
7373
<term>backwards compatible</term>
7474
<listitem>
7575
<para>
76-
Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also <xref linkend="forwards-compatible" />.
76+
Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. Refer also to <xref linkend="forwards-compatible" />.
7777
</para>
7878

7979
</listitem>
@@ -106,7 +106,7 @@
106106
<term>basically</term>
107107
<listitem>
108108
<para>
109-
Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also <xref linkend="simply" />.
109+
Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." Refer also to <xref linkend="simply" />.
110110
</para>
111111

112112
</listitem>
@@ -152,7 +152,7 @@
152152
<term>big data</term>
153153
<listitem>
154154
<para>
155-
<emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red&nbsp;Hat product, service, solution, or business unit name. See also <xref linkend="cloud" />. Big data is also never hyphenated, per AP style, even when used as a complex adjective.
155+
<emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red&nbsp;Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, per AP style, even when used as a complex adjective.
156156
</para>
157157

158158
</listitem>
@@ -227,9 +227,18 @@
227227
Correct. Named after George Boole, who first developed the concept.
228228
</para>
229229
<para>
230-
According to the <citetitle>IBM Style Guide</citetitle>, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type.
230+
According to the <citetitle>IBM Style Guide</citetitle>, it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type.
231231
</para>
232-
232+
<para>
233+
To set Boolean values in YAML files, use <varname>true</varname> or <varname>false</varname>, written lowercase, rather than <varname>yes</varname> or <varname>no</varname>, because YAML&nbsp;1.2 and later versions do not support the latter syntax.
234+
</para>
235+
<para>
236+
For example, the following scenario specifies that a task is run only one time:
237+
</para>
238+
<screen>- name: Pause 30 seconds
239+
ansible.builtin.pause:
240+
seconds: 30
241+
<userinput>run_once: true</userinput></screen>
233242
</listitem>
234243

235244
</varlistentry>
@@ -296,7 +305,7 @@
296305
<term>Bps, bps</term>
297306
<listitem>
298307
<para>
299-
The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also <xref linkend="bandwidth" />.
308+
The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. Refer also to <xref linkend="bandwidth" />.
300309
</para>
301310

302311
</listitem>
@@ -306,7 +315,7 @@
306315
<term>breadcrumb trail</term>
307316
<listitem>
308317
<para>
309-
See the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
318+
Refer to the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
310319
</para>
311320
<note>
312321
<para>
@@ -379,10 +388,10 @@
379388
A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities.
380389
</para>
381390
<para>
382-
See <ulink url="http://en.wikipedia.org/wiki/Btrfs" /> for more information on this file system.
391+
Refer to <ulink url="http://en.wikipedia.org/wiki/Btrfs" /> for more information on this file system.
383392
</para>
384393
<para>
385-
See <ulink url="http://en.wikipedia.org/wiki/List_of_file_systems" /> for a list of file-system names and how to present them.
394+
Refer to <ulink url="http://en.wikipedia.org/wiki/List_of_file_systems" /> for a list of file-system names and how to present them.
386395
</para>
387396

388397
</listitem>
@@ -428,7 +437,7 @@
428437
Ordinarily you would not include the text "button" in a procedure or description. For example, "Click <guibutton>OK</guibutton> to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the <guibutton>Download</guibutton> link".
429438
</para>
430439
<para>
431-
See also <xref linkend="documenting-ui"/>.
440+
Refer also to <xref linkend="documenting-ui"/>.
432441
</para>
433442

434443
</listitem>

0 commit comments

Comments
 (0)