Skip to content

Commit a12ef03

Browse files
julian-cabledaobriendaobrienmweetman-redhatCBID2
authored
Merge commits from dev to master branch for 7.0 release (#622)
* 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 * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback --------- 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> Co-authored-by: Ashley D'Andrea <jdandrea@gmail.com> Co-authored-by: Steven Bonneville <sbonnevi@redhat.com> Co-authored-by: Rachel Lee <ralee@redhat.com>
1 parent ae704b2 commit a12ef03

32 files changed

+772
-179
lines changed

‎.gitignore

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
*~
2+
.DS_Store
3+
.idea
4+
5+
# editor swap files
6+
.*.sw?
7+
8+
# databases
9+
*.db
10+
11+
# tmp directory
12+
tmp

‎README.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,22 @@
11
WritingStyleGuide
22
=================
33

4-
A guide to writing clear, concise, and consistent technical documentation.
4+
This guide is the official style guide for Red&nbsp;Hat training and certification content, and for all other technical documentation except as stated.
5+
Red&nbsp;Hat product documentation by Customer Content Services (CCS) follows the Red&nbsp;Hat supplementary style guide at https://redhat-documentation.github.io/supplementary-style-guide/ instead of this Red&nbsp;Hat Technical Writing Style Guide.
56

6-
The Red&nbsp;Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat.
7+
The Red&nbsp;Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary.
78

8-
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.
9+
This guide is a public guide. It is reviewed and maintained by Red&nbsp;Hat. Contributions from the wider community are always welcomed.
910

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.
11+
Other resources for technical writing are listed in the "Resources" section of the guide.
1112

1213
Dependencies:
1314

1415
```
1516
$ sudo dnf install publican
1617
```
1718

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+
Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red&nbsp;Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that.
1920

2021
To build:
2122

‎en-US/Audience.xml

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,34 @@
77
<title>Audience</title>
88
<para>
99
This guide is the official style guide for Red&nbsp;Hat training and certification content, and for all other technical documentation except as stated.
10-
Red&nbsp;Hat product documentation by Customer Content Services (CCS) follows the Red&nbsp;Hat supplementary style guide at <ulink url="https://redhat-documentation.github.io/supplementary-style-guide/" /> instead of this Red&nbsp;Hat Technical Writing Style Guide.
10+
Red&nbsp;Hat product documentation
11+
<!-- by Customer Content Services (CCS) -->
12+
follows the Red&nbsp;Hat supplementary style guide at <ulink url="https://redhat-documentation.github.io/supplementary-style-guide/" /> instead of this guide.
1113
</para>
1214
<para>
13-
The Red&nbsp;Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary.
15+
The Red&nbsp;Hat Technical Writing Style Guide includes guidance for everyday punctuation and grammar, common mistakes and how to avoid them, strategies for translation and global audiences, content design guidance, and a word usage dictionary.
1416
</para>
1517
<para>
16-
This guide is a public guide. It is reviewed and maintained by Red&nbsp;Hat. Contributions from the wider community are always welcomed.
18+
This guide is a public and open source guide.
19+
It is reviewed and maintained primarily by Red&nbsp;Hat.
20+
Contributions from the wider community are always welcome.
1721
</para>
1822
<para>
1923
Other resources for technical writing are listed in <xref linkend="resources"/>.
24+
Of these resources,
25+
<ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
26+
<guiicon><inlinemediaobject>
27+
<imageobject>
28+
<imagedata fileref="images/padlock.png"/>
29+
</imageobject>
30+
</inlinemediaobject></guiicon>
31+
is available for Red&nbsp;Hat employees to access online, but does not have a wider circulation.
32+
Links in this guide to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink> are denoted by a padlock icon
33+
<guiicon><inlinemediaobject>
34+
<imageobject>
35+
<imagedata fileref="images/padlock.png"/>
36+
</imageobject>
37+
</inlinemediaobject></guiicon>.
2038
</para>
2139

2240
</section>

‎en-US/B.xml

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -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. Refer also to <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, even when used as a compound modifier.
156156
</para>
157157

158158
</listitem>
@@ -227,7 +227,13 @@
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" (lowercase) in API programming information when it refers to a primitive return type.
230+
According to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
231+
<guiicon><inlinemediaobject>
232+
<imageobject>
233+
<imagedata fileref="images/padlock.png"/>
234+
</imageobject>
235+
</inlinemediaobject></guiicon>,
236+
it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type.
231237
</para>
232238
<para>
233239
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.
@@ -312,10 +318,15 @@
312318

313319
</varlistentry>
314320
<varlistentry id="breadcrumb-trail">
315-
<term>breadcrumb trail</term>
321+
<term>breadcrumb, breadcrumb trail</term>
316322
<listitem>
317323
<para>
318-
Refer to the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
324+
For initial guidance on how to use this term, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
325+
<guiicon><inlinemediaobject>
326+
<imageobject>
327+
<imagedata fileref="images/padlock.png"/>
328+
</imageobject>
329+
</inlinemediaobject></guiicon>.
319330
</para>
320331
<note>
321332
<para>

‎en-US/Book_Design.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@
6464
<section id="prefaces">
6565
<title>Prefaces</title>
6666
<para>
67-
The brands that form part of Publican contain a preface as part of the common content. Whether your publication is for external Red&nbsp;Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update.
67+
The brands that form part of Publican (<ulink url="https://fedorahosted.org/publican/" />) contain a preface as part of the common content. Whether your publication is for external Red&nbsp;Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update.
6868
</para>
6969

7070
</section>
@@ -136,7 +136,7 @@
136136
<formalpara id="overview">
137137
<title>Overview</title>
138138
<para>
139-
Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles.
139+
Use "Overview" in a title only sparingly, and do not use "Overview" as a title on its own. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles.
140140
</para>
141141

142142
</formalpara>

‎en-US/Book_Info.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<!-- Change title to "The Red Hat Style Guide" -->
99
<productname>Red&nbsp;Hat Technical Writing Style&nbsp;Guide</productname>
1010
<productnumber></productnumber>
11-
<edition>6.2</edition>
11+
<edition>7.0</edition>
1212
<pubsnumber>1</pubsnumber>
1313
<abstract>
1414
<para>

‎en-US/C.xml

Lines changed: 54 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,23 @@
66
<chapter id="c">
77
<title>C</title>
88
<variablelist>
9+
<varlistentry id="called">
10+
<term>call, called</term>
11+
<listitem>
12+
<para>
13+
Use to refer to code, programs, or scripts that invoke functions or methods.
14+
For example, "A liveness probe is called throughout the lifetime of the application."
15+
</para>
16+
<para>
17+
On the other hand, when referring to the designation of files, objects, or entities within documentation, use the term "named" instead of "called".
18+
This choice promotes clarity and precision in technical content.
19+
</para>
20+
<para>
21+
Refer also to <xref linkend="named" />.
22+
</para>
23+
</listitem>
24+
25+
</varlistentry>
926
<varlistentry id="can-may">
1027
<term>can, may</term>
1128
<listitem>
@@ -46,7 +63,12 @@
4663
When referring to a compact disk, use "CD". For example, "Insert the CD into the CD drive". The plural is "CDs".
4764
</para>
4865
<para>
49-
Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information.
66+
For more information, refer to the Word Usage section of <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
67+
<guiicon><inlinemediaobject>
68+
<imageobject>
69+
<imagedata fileref="images/padlock.png"/>
70+
</imageobject>
71+
</inlinemediaobject></guiicon>.
5072
</para>
5173

5274
</listitem>
@@ -95,23 +117,12 @@
95117
Do not use "characters" to mean "bytes". In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes.
96118
</para>
97119
<para>
98-
In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation.
99-
</para>
100-
101-
</listitem>
102-
103-
</varlistentry>
104-
<varlistentry id="check">
105-
<term>check</term>
106-
<listitem>
107-
<para>
108-
Avoid. Use "verify", "ensure", or "read", depending on the context.
120+
In computer software, a character is a symbol, such as a letter or number, that represents information. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation.
109121
</para>
110122

111123
</listitem>
112124

113125
</varlistentry>
114-
115126
<varlistentry id="chip-set">
116127
<term>chipset</term>
117128
<listitem>
@@ -153,7 +164,12 @@
153164
</para>
154165
<!-- Added comment about "click on". -->
155166
<para>
156-
Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information.
167+
For more information, refer to the Word Usage section of <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
168+
<guiicon><inlinemediaobject>
169+
<imageobject>
170+
<imagedata fileref="images/padlock.png"/>
171+
</imageobject>
172+
</inlinemediaobject></guiicon>.
157173
</para>
158174

159175
</listitem>
@@ -244,10 +260,16 @@
244260

245261
</varlistentry>
246262
<varlistentry id="combo-box">
247-
<term>combo-box</term>
263+
<term>combo box</term>
248264
<listitem>
249265
<para>
250-
Do not use as an abbreviation for "combination box". Refer to the relevant entry in the <citetitle>IBM Style Guide</citetitle> for further usage information.
266+
Do not use as an abbreviation for "combination box".
267+
For further usage information, refer to the relevant entry in <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
268+
<guiicon><inlinemediaobject>
269+
<imageobject>
270+
<imagedata fileref="images/padlock.png"/>
271+
</imageobject>
272+
</inlinemediaobject></guiicon>.
251273
</para>
252274

253275
</listitem>
@@ -310,10 +332,22 @@
310332

311333
</varlistentry>
312334
<varlistentry id="command-line">
313-
<term>command line, command prompt, command-line</term>
335+
<term>command line, command-line, command prompt</term>
314336
<listitem>
315337
<para>
316-
Refer to the appropriate entries in the <citetitle>IBM Style Guide</citetitle> for an explanation of how to use these terms.
338+
Use "command line" to refer to the place where commands are entered.
339+
Use "command line" as a noun, and use "command-line" as an adjective.
340+
</para>
341+
<para>
342+
For more details about how to use these terms, refer to the appropriate entries in <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
343+
<guiicon><inlinemediaobject>
344+
<imageobject>
345+
<imagedata fileref="images/padlock.png"/>
346+
</imageobject>
347+
</inlinemediaobject></guiicon>.
348+
</para>
349+
<para>
350+
Refer also to <xref linkend="shell-prompt"/> and to <xref linkend="terminal"/>.
317351
</para>
318352

319353
</listitem>
@@ -454,8 +488,8 @@
454488
<term>cookie</term>
455489
<listitem>
456490
<para>
457-
<emphasis>n.</emphasis> A message given to a web browser by a web server.
458-
The browser stores the message in a text file named <filename>cookie.txt</filename>.
491+
<emphasis>n.</emphasis> Data that is given to a web browser by a web server.
492+
The browser stores the message in a text file that might be named <filename>cookie.txt</filename>.
459493
The message is then sent back to the server each time the browser requests a page from the server.
460494
</para>
461495

‎en-US/D.xml

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@
2323
<term>dash</term>
2424
<listitem>
2525
<para>
26-
In technical publications, the <citetitle>IBM Style Guide</citetitle> recommends not to use em&nbsp;dashes or en&nbsp;dashes at all. Use a colon or other suitable punctuation.
26+
Use a dash to show a range, such as for page numbers, letters, pages, or dates.
27+
Otherwise, do not use dashes in technical content.
28+
Instead, use other punctuation marks, such as commas, parentheses, or a colon.
2729
</para>
2830

2931
</listitem>
@@ -35,13 +37,13 @@
3537
<para>
3638
<emphasis>n.</emphasis> Use the two-word form unless referring to a product name or other proper noun where the one-word form is used.
3739
</para>
38-
<warning>
40+
<!-- <warning>
3941
<title>Marketing Publications Exception</title>
4042
<para>
4143
In marketing publications, use the one-word form of this term unless referring to a product name or other proper noun where the two-word form is used.
4244
</para>
4345
44-
</warning>
46+
</warning> -->
4547

4648
</listitem>
4749

@@ -62,13 +64,13 @@
6264
<para>
6365
<emphasis>n.</emphasis> Use the two-word form.
6466
</para>
65-
<warning>
67+
<!-- <warning>
6668
<title>Marketing Publications Exception</title>
6769
<para>
6870
In marketing publications, the one-word form is recommended.
6971
</para>
7072
71-
</warning>
73+
</warning> -->
7274

7375
</listitem>
7476

@@ -87,15 +89,8 @@
8789
<term>data store, datastore</term>
8890
<listitem>
8991
<para>
90-
<emphasis>n.</emphasis> Use the two-word form.
92+
<emphasis>n.</emphasis> Write as two words, except in a VMware context where the one-word form is required.
9193
</para>
92-
<warning>
93-
<title>Marketing Publications Exception</title>
94-
<para>
95-
In marketing publications, the one-word form is recommended.
96-
</para>
97-
98-
</warning>
9994

10095
</listitem>
10196

@@ -189,7 +184,13 @@
189184
<term>dialog box</term>
190185
<listitem>
191186
<para>
192-
Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for usage information related to this and similar terms.
187+
<emphasis>n.</emphasis> Use "dialog box" (<emphasis>not</emphasis> "dialog", "dialogue", or "dialogue box"), to refer to an element that is displayed for a user to interact with a graphical user interface.
188+
</para>
189+
<para>
190+
Use this term regardless of whether a dialog box is <emphasis>modal</emphasis>, where the user must respond to a prompt before the main content of the interface is enabled again, or is <emphasis>non-modal</emphasis>, where the user can continue interacting with the main content when the dialog box is open.
191+
</para>
192+
<para>
193+
For example: "In the <guilabel>Subscriptions</guilabel> window, click <guilabel>Register</guilabel> to open the <guilabel>Register System</guilabel> dialog box."
193194
</para>
194195

195196
</listitem>
@@ -231,7 +232,7 @@
231232
<term>disk, disc</term>
232233
<listitem>
233234
<para>
234-
Use "compact disc" or "hard disk". Refer to the <citetitle>IBM Style Guide</citetitle> for more information and example use cases.
235+
Use "compact disc" or "hard disk".
235236
</para>
236237
<!-- Removed reference to "diskette". -->
237238

0 commit comments

Comments
 (0)