Merge pull request #350 from StyleGuides/dev

Merge dev to master for 5.1 release

Author: daobrien

README.md

@@ -3,7 +3,7 @@ WritingStyleGuide
 
 A guide to writing clear, concise, and consistent technical documentation.
 
-The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat.
+The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat.
 
 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.
 

en-US/A.xml

@@ -22,7 +22,7 @@
 			 <listitem>
 				<para>
 					Do not use to refer to information that was mentioned previously.
-          When documents are converted to online format, the information might no longer be "above."
+          When documents are converted to online format, the information might no longer be "above".
           Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead.
 				</para>
 
@@ -47,7 +47,7 @@
       <term role="false">air wall</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Use "air gap" to describe systems that are separated, not by software, but physically. Do not use "air wall." "Air gap" is preferred in technical publications because there is no actual wall that you need to breach, but rather a gap that you need to bridge. You cannot break through something that does not exist.
+					<emphasis>n.</emphasis> Use "air gap" to describe systems that are separated, not by software, but physically. Do not use "air wall". "Air gap" is preferred in technical publications because there is no actual wall that you need to breach, but rather a gap that you need to bridge. You cannot break through something that does not exist.
 				</para>
 
 			</listitem>
@@ -84,7 +84,7 @@
 			 <listitem>
 				<para>
 					<emphasis>adj.</emphasis> Describes another way or method of doing something.
-          "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..."
+          "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something", use "an alternative method is to ...".
 				</para>
         <para>
           See also <xref linkend="alternate"/>.
@@ -110,10 +110,10 @@
 			<term role="true">AMD64</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture.
+					Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86" or other variations as the name of this architecture.
 				</para>
 				 <para>
-					The correct term for AMD's implementation of this architecture is "AMD64."
+					The correct term for AMD's implementation of this architecture is "AMD64".
           When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically.
 				</para>
         <para>
@@ -152,7 +152,7 @@
 			<term>appendixes</term>
 			 <listitem>
 				<para>
-					Correct. This is the correct plural form for US English spelling. Do not use "appendices."
+					Correct. This is the correct plural form for US English spelling. Do not use "appendices".
 				</para>
 
 			</listitem>
@@ -165,7 +165,7 @@
 			 <listitem>
 				<para>
 					When used as a proper name, use the capitalization of the product, such as GNUPro, Source-Navigator, and Red&nbsp;Hat Enterprise&nbsp;Linux.
-          When used as a command, use lowercase as appropriate, such as "To start GCC, type gcc."
+          When used as a command, use lowercase as appropriate, such as "To start GCC, type gcc".
 				</para>
 				 <note>
 					<para>
@@ -186,7 +186,7 @@
 			 <listitem>
 				<para>
 					"Applixware" is correct.
-          Do not use "Applix" or "ApplixWare."
+          Do not use "Applix" or "ApplixWare".
 				</para>
 
 			</listitem>
@@ -198,17 +198,17 @@
         <para>
           Do not use as a verb.
           Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience.
-          Use "design," "build," "create," or another descriptive verb instead.
+          Use "design", "build", "create", or another descriptive verb instead.
           Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning.
-          For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding."
+          For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding".
         </para>
       </listitem>
     </varlistentry>
 		 <varlistentry id="as-well-as">
 			<term role="caution">as well as</term>
 			 <listitem>
 				<para>
-					Not interchangeable with "and."
+					Not interchangeable with "and".
           "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series.
           For example, "We sell kitchen electronics and china, as well as some gourmet foods."
           But "We sell kitchen electronics, china, and silverware."
@@ -345,7 +345,7 @@
 			<term>auto-detect</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "autodetect."
+					Correct. Do not use "autodetect".
 				</para>
 
 			</listitem>

en-US/B.xml

@@ -7,16 +7,16 @@
 	<title>B</title>
 	 <variablelist>
 		<varlistentry id="back-end">
-			<term>back end, back-end</term>
+			<term>back end, back-end, backend</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls."
+					<emphasis>n.</emphasis> Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls".
 				</para>
 				 <para>
 					<emphasis>adj.</emphasis> Hyphenate. For example, "when the back-end database processes a search operation …"
 				</para>
 				 <para>
-					Do not use "backend."
+					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.
 				</para>
 				 <para>
 					See also <xref linkend="front-end" />
@@ -35,26 +35,26 @@
 				 <itemizedlist>
 					<listitem>
 						<para>
-							<emphasis>adj.</emphasis> One word. For example, "store the backup copies of important files in a secure location."
+							<emphasis>adj.</emphasis> One word. For example, "store the backup copies of important files in a secure location".
 						</para>
 
 					</listitem>
 					 <listitem>
 						<para>
-							<emphasis>n.</emphasis> One word. For example, "create a backup of your important files."
+							<emphasis>n.</emphasis> One word. For example, "create a backup of your important files".
 						</para>
 
 					</listitem>
 					 <listitem>
 						<para>
-							<emphasis>v.</emphasis> Two words. For example, "always back up important files."
+							<emphasis>v.</emphasis> Two words. For example, "always back up important files".
 						</para>
 
 					</listitem>
 
 				</itemizedlist>
 				 <para>
-					Do not use the hyphenated form, "back-up."
+					Do not use the hyphenated form, "back-up".
 				</para>
 
 			</listitem>
@@ -64,7 +64,7 @@
 			<term>backtrace</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace.
+					<emphasis>n.</emphasis> "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback", possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace.
 				</para>
 
 			</listitem>
@@ -127,7 +127,7 @@
 			<term>below</term>
 			 <listitem>
 				<para>
-					Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below." Use a cross-reference instead.
+					Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below". Use a cross-reference instead.
 				</para>
 
 			</listitem>
@@ -137,13 +137,13 @@
 			<term>biannual, bimonthly, biweekly, semiweekly, semimonthly</term>
 			 <listitem>
 				<para>
-					People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication.
+					People have trouble remembering whether biweekly means "every two weeks" or "twice a week". "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication.
 				</para>
 				 <para>
-					Instead of biweekly, write "every two weeks" or "every other week."
+					Instead of biweekly, write "every two weeks" or "every other week".
 				</para>
 				 <para>
-					Instead of semiweekly, write "twice a week."
+					Instead of semiweekly, write "twice a week".
 				</para>
 
 			</listitem>
@@ -202,7 +202,7 @@
 			<term>bit rate</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "bitrate."
+					Correct. Do not use "bitrate".
 				</para>
 
 			</listitem>
@@ -244,7 +244,7 @@
 					<emphasis>n.</emphasis> Refers to starting up a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running.
 				</para>
 				 <para>
-					Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps." Similarly, bootstrap utilities help the computer to get started.
+					Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps". Similarly, bootstrap utilities help the computer to get started.
 				</para>
 
 			</listitem>
@@ -254,7 +254,7 @@
 			<term>boot disk</term>
 			 <listitem>
 				<para>
-					Two words. Do not use "boot diskette."
+					Two words. Do not use "boot diskette".
 				</para>
 
 			</listitem>
@@ -264,7 +264,7 @@
 			<term>boot loader</term>
 			 <listitem>
 				<para>
-					Two words. Do not use "bootloader."
+					Two words. Do not use "bootloader".
 				</para>
 
 			</listitem>
@@ -274,7 +274,7 @@
 			<term>bottleneck</term>
 			 <listitem>
 				<para>
-					One word. Do not use "bottle neck" or "bottle-neck."
+					One word. Do not use "bottle neck" or "bottle-neck".
 				</para>
 				 <para>
 					A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information that is being relayed at the speed that it is being processed. However, many factors can create a bottleneck in a system.
@@ -287,7 +287,7 @@
 			<term>bpp</term>
 			 <listitem>
 				<para>
-					Initialism for bits per pixel. All letters are lowercase, unless at the beginning of a sentence. Use a non-breaking space between the numeral and the units. For example, "16&nbsp;bpp," not "16bpp."
+					Initialism for bits per pixel. All letters are lowercase, unless at the beginning of a sentence. Use a non-breaking space between the numeral and the units. For example, "16&nbsp;bpp", not "16bpp".
 				</para>
 
 			</listitem>
@@ -334,7 +334,7 @@
         <term>break</term>
         <listitem>
           <para>
-            (<emphasis>v.</emphasis>) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such as "cause the system to fail."
+            (<emphasis>v.</emphasis>) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system". Choose an alternative such as "cause the system to fail".
           </para>
         </listitem>
       </varlistentry>
@@ -352,7 +352,7 @@
 			<term>Britain</term>
 			 <listitem>
 				<para>
-					If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland.
+					If referring to the language, say "English". If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland.
 				</para>
 
 			</listitem>
@@ -393,7 +393,7 @@
 			<term>bug fix</term>
 			 <listitem>
 				<para>
-					Two words. Do not use "bugfix."
+					Two words. Do not use "bugfix".
 				</para>
 
 			</listitem>
@@ -423,10 +423,10 @@
 			<term>button</term>
 			 <listitem>
 				<para>
-					Describe a GUI button as a "button," not a "pushbutton" or "push-button."
+					Describe a UI button as a "button", not a "pushbutton" or "push-button".
 				</para>
 				 <para>
-					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."
+					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".
 				</para>
         <para>
           See also <xref linkend="documenting-ui"/>.

en-US/Book_Design.xml

@@ -65,7 +65,7 @@
 	 <section id="abstracts">
 		<title>Abstracts</title>
 		 <para>
-			Abstracts for Red&nbsp;Hat technical documentation typically fall under the heading of a "descriptive abstract." From Wikipedia, "The descriptive abstract, also known as the limited abstract or the indicative abstract, provides a description of what the paper covers without delving into its substance. A descriptive abstract is akin to a table of contents in paragraph form."<footnote> <para>
+			Abstracts for Red&nbsp;Hat technical documentation typically fall under the heading of a "descriptive abstract". From Wikipedia, "The descriptive abstract, also known as the limited abstract or the indicative abstract, provides a description of what the paper covers without delving into its substance. A descriptive abstract is akin to a table of contents in paragraph form."<footnote> <para>
 				<ulink url="http://en.wikipedia.org/wiki/Abstract_%28summary%29#Descriptive" />
 			</para>
 			 </footnote>
@@ -112,11 +112,18 @@
 			The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red&nbsp;Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product.
 		</para>
 
+	</section>
+	 <section id="heading-placement">
+		<title>Placement of Headings</title>
+		 <para>
+			Do not include two consecutive headings without intervening text. Each heading must be followed by one or more paragraphs of text. If it is difficult to provide meaningful intervening text, then consider whether one of the headings is unnecessary.
+		</para>
+
 	</section>
 	 <section id="unused-heading-titles">
 		<title>Unused Heading Titles</title>
-		 <para>
-			This section lists various heading titles that might be  used in Red&nbsp;Hat technical documentation, but that should be avoided except in specific circumstances.
+		 <para>		
+			This section lists various heading titles that might be used in Red&nbsp;Hat technical documentation, but that should be avoided except in specific circumstances.
 		</para>
 		 <formalpara id="overview">
 			<title>Overview</title>
@@ -128,7 +135,7 @@
 		 <formalpara id="about">
 			<title>About</title>
 			 <para>
-				Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview."
+				Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview".
 			</para>
 
 		</formalpara>

en-US/Book_Info.xml

@@ -1,14 +1,14 @@
 <?xml version='1.0' encoding='utf-8' ?>
 <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Conventions_for_Writers_and_Editors.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Style_Conventions_for_Writers_and_Editors.ent">
 %BOOK_ENTITIES;
 ]>
 <bookinfo id="conventions">
 	<title>Style Conventions for Writers and Editors</title>
 	<!-- Change title to "The Red Hat Style Guide" -->
 	 <productname>Red&nbsp;Hat Technical Writing Style&nbsp;Guide</productname>
 	 <productnumber></productnumber>
-	 <edition>5.0</edition>
+	 <edition>5.1</edition>
 	 <pubsnumber>1</pubsnumber>
 	 <abstract>
 		<para>