Merge commits from dev to master branch for 7.0 release

.gitignore

@@ -0,0 +1,12 @@
+*~
+.DS_Store
+.idea
+
+# editor swap files
+.*.sw?
+
+# databases
+*.db
+
+# tmp directory
+tmp

README.md

@@ -1,21 +1,22 @@
 WritingStyleGuide
 =================
 
-A guide to writing clear, concise, and consistent technical documentation.
+This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated.
+Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at https://redhat-documentation.github.io/supplementary-style-guide/ instead of this Red Hat Technical Writing Style Guide.
 
-The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat.
+The Red 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.
 
-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.
+This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed. 
 
-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.
+Other resources for technical writing are listed in the "Resources" section of the guide.
 
 Dependencies:
 
 ```
 $ sudo dnf install publican
 ```
 
-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.
+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.
 
 To build:
 

en-US/Audience.xml

@@ -7,16 +7,34 @@
 	<title>Audience</title>
 	 <para>
 		This guide is the official style guide for Red&nbsp;Hat training and certification content, and for all other technical documentation except as stated.
-		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.
+		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 guide.
 	</para>
 	 <para>
-		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.        
+		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.        
 	</para>
 	 <para>
-		This guide is a public guide. It is reviewed and maintained by Red&nbsp;Hat. Contributions from the wider community are always welcomed.        
+		This guide is a public and open source guide.
+		It is reviewed and maintained primarily by Red&nbsp;Hat.
+		Contributions from the wider community are always welcome.        
 	</para>
 	<para>
         Other resources for technical writing are listed in <xref linkend="resources"/>.
+		Of these resources, 
+		<ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon> 
+		is available for Red&nbsp;Hat employees to access online, but does not have a wider circulation.
+		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
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>.
     </para>	
 
 </section>

en-US/B.xml

@@ -152,7 +152,7 @@
 			<term>big data</term>
 			 <listitem>
 				<para>
-					<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.
+					<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.
 				</para>
 
 			</listitem>
@@ -227,7 +227,13 @@
 					Correct. Named after George Boole, who first developed the concept.
 				</para>
 				 <para>
-					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.
+					According to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>, 
+		  			it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type.
 				</para>
 				 <para>
 					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 @@
 
 		</varlistentry>
     <varlistentry id="breadcrumb-trail">
-      <term>breadcrumb trail</term>
+      <term>breadcrumb, breadcrumb trail</term>
       <listitem>
         <para>
-          Refer to the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
+          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>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>.
         </para>
         <note>
           <para>

en-US/Book_Design.xml

@@ -64,7 +64,7 @@
 	 <section id="prefaces">
 		<title>Prefaces</title>
 		 <para>
-			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.
+			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.
 		</para>
 
 	</section>
@@ -136,7 +136,7 @@
 		 <formalpara id="overview">
 			<title>Overview</title>
 			 <para>
-				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.
+				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.
 			</para>
 
 		</formalpara>

en-US/Book_Info.xml

@@ -8,7 +8,7 @@
 	<!-- Change title to "The Red Hat Style Guide" -->
 	 <productname>Red&nbsp;Hat Technical Writing Style&nbsp;Guide</productname>
 	 <productnumber></productnumber>
-	 <edition>6.2</edition>
+	 <edition>7.0</edition>
 	 <pubsnumber>1</pubsnumber>
 	 <abstract>
 		<para>

en-US/C.xml

@@ -6,6 +6,23 @@
 <chapter id="c">
 	<title>C</title>
 	 <variablelist>
+		 <varlistentry id="called">
+ 			<term>call, called</term>
+ 			 <listitem>
+ 				<para>
+					Use to refer to code, programs, or scripts that invoke functions or methods.
+					For example, "A liveness probe is called throughout the lifetime of the application."
+ 				</para>
+				 <para>
+					On the other hand, when referring to the designation of files, objects, or entities within documentation, use the term "named" instead of "called". 
+					This choice promotes clarity and precision in technical content.
+ 				</para>
+				 <para>
+					Refer also to <xref linkend="named" />.
+				</para>
+ 			</listitem>
+
+ 		</varlistentry>
 		<varlistentry id="can-may">
 			<term>can, may</term>
 			 <listitem>
@@ -46,7 +63,12 @@
 					When referring to a compact disk, use "CD". For example, "Insert the CD into the CD drive". The plural is "CDs".
 				</para>
 				 <para>
-					Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information.
+					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>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>.
 				</para>
 
 			</listitem>
@@ -95,23 +117,12 @@
 					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.
 				</para>
 				 <para>
-					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.
-				</para>
-
-			</listitem>
-
-		</varlistentry>
-		 <varlistentry id="check">
-			<term>check</term>
-			 <listitem>
-				<para>
-					Avoid. Use "verify", "ensure", or "read", depending on the context.
+					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.
 				</para>
 
 			</listitem>
 
 		</varlistentry>
-
 		 <varlistentry id="chip-set">
 			<term>chipset</term>
 			 <listitem>
@@ -153,7 +164,12 @@
 				</para>
 <!-- Added comment about "click on". -->
 				 <para>
-					Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information.
+					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>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>.
 				</para>
 
 			</listitem>
@@ -244,10 +260,16 @@
 
 		</varlistentry>
 		 <varlistentry id="combo-box">
-			<term>combo-box</term>
+			<term>combo box</term>
 			 <listitem>
 				<para>
-					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.
+					Do not use as an abbreviation for "combination box". 
+					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>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>.
 				</para>
 
 			</listitem>
@@ -310,10 +332,22 @@
 
 		</varlistentry>
 		 <varlistentry id="command-line">
-			<term>command line, command prompt, command-line</term>
+			<term>command line, command-line, command prompt</term>
 			 <listitem>
 				<para>
-					Refer to the appropriate entries in the <citetitle>IBM Style Guide</citetitle> for an explanation of how to use these terms.
+					Use "command line" to refer to the place where commands are entered.
+					Use "command line" as a noun, and use "command-line" as an adjective.
+				</para>
+				 <para>
+					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>
+         	<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/padlock.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>.
+				</para>
+				<para>
+				Refer also to <xref linkend="shell-prompt"/> and to <xref linkend="terminal"/>.
 				</para>
 
 			</listitem>
@@ -454,8 +488,8 @@
 			<term>cookie</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> A message given to a web browser by a web server.
-          The browser stores the message in a text file named <filename>cookie.txt</filename>.
+					<emphasis>n.</emphasis> Data that is given to a web browser by a web server.
+          The browser stores the message in a text file that might be named <filename>cookie.txt</filename>.
           The message is then sent back to the server each time the browser requests a page from the server.
 				</para>
 

en-US/D.xml

@@ -23,7 +23,9 @@
 			<term>dash</term>
 			 <listitem>
 				<para>
-					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.
+					Use a dash to show a range, such as for page numbers, letters, pages, or dates.
+					Otherwise, do not use dashes in technical content.
+					Instead, use other punctuation marks, such as commas, parentheses, or a colon. 
 				</para>
 
 			</listitem>
@@ -35,13 +37,13 @@
 				<para>
 					<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.
 				</para>
-				 <warning>
+				 <!-- <warning>
 					<title>Marketing Publications Exception</title>
 					 <para>
 						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.
 					</para>
 
-				</warning>
+				</warning> -->
 
 			</listitem>
 
@@ -62,13 +64,13 @@
 				<para>
 					<emphasis>n.</emphasis> Use the two-word form.
 				</para>
-				 <warning>
+				 <!-- <warning>
 					<title>Marketing Publications Exception</title>
 					 <para>
 						In marketing publications, the one-word form is recommended.
 					</para>
 
-				</warning>
+				</warning> -->
 
 			</listitem>
 
@@ -87,15 +89,8 @@
 			<term>data store, datastore</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Use the two-word form.
+					<emphasis>n.</emphasis> Write as two words, except in a VMware context where the one-word form is required.
 				</para>
-				 <warning>
-					<title>Marketing Publications Exception</title>
-					 <para>
-						In marketing publications, the one-word form is recommended.
-					</para>
-
-				</warning>
 
 			</listitem>
 
@@ -189,7 +184,13 @@
 			<term>dialog box</term>
 			 <listitem>
 				<para>
-					Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for usage information related to this and similar terms.
+					<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.
+				</para>					
+				<para>
+					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.
+				</para>
+				<para>
+					For example: "In the <guilabel>Subscriptions</guilabel> window, click <guilabel>Register</guilabel> to open the <guilabel>Register System</guilabel> dialog box."
 				</para>
 
 			</listitem>
@@ -231,7 +232,7 @@
 			<term>disk, disc</term>
 			 <listitem>
 				<para>
-					Use "compact disc" or "hard disk". Refer to the <citetitle>IBM Style Guide</citetitle> for more information and example use cases.
+					Use "compact disc" or "hard disk".
 				</para>
 <!-- Removed reference to "diskette". -->