Merge dev to master for new release

en-US/B.xml

@@ -419,8 +419,11 @@
 					Describe a GUI 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 may be necessary to distinguish between buttons and links; for example, "Click the <guibutton>Unload</guibutton> button."
+					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 may be necessary to distinguish between buttons and links; for example, "Click the <guibutton>Download</guibutton> link."
 				</para>
+        <para>
+          See also <xref linkend="documenting-ui"/>.
+        </para>
 
 			</listitem>
 

en-US/Conventions_for_Writers_and_Editors.xml

@@ -27,7 +27,7 @@
 		<title>Usage Dictionary</title>
 		 <partintro>
 			<para>
-				The Usage Dictionary provides guidelines for the correct use of common terms in Red&nbsp;Hat documentation, which terms to avoid, and the preferred spelling if variations exist.
+				The Usage Dictionary provides guidelines for the correct use of common terms in Red&#160;Hat documentation, which terms to avoid, and the preferred spelling if variations exist.
 			</para>
 
 		</partintro>

en-US/Design.xml

@@ -81,13 +81,42 @@
       The following sections highlight exceptions or cases that might otherwise cause confusion.
 		</para>
 		 <section id="gui-elements-punctuation">
-			<title>GUI Elements and Punctuation</title>
+			<title>GUI Elements, Punctuation, and Symbols</title>
 			 <para>
-				Do not include punctuation that appears on GUI elements, unless omission of that punctuation might lead to confusion.
+				When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion.
 			</para>
 			 <para>
 				For example, for a button labeled <guibutton>Save As...</guibutton>, do not include the ellipsis in the documentation.
 			</para>
+      <para>
+        In most cases, do not include the object type in instructions.
+        For example, rather than "Click the <guibutton>Save</guibutton> button," write "Click <guibutton>Save</guibutton>."
+      </para>
+      <para>
+        In some cases it is preferred practice to include the object type for the sake of clarity.
+        Consider the following:
+      </para>
+      <example><title>Preferred Style for Documenting Symbols and Other Special Characters</title>
+        <para>
+          Click the <guibutton>+</guibutton> sign.
+        </para>
+        <para>
+          Click the <guibutton>^</guibutton> symbol.
+        </para>
+      </example>
+      <para>
+        If you cannot easily reproduce the symbol, include a screen capture and/or a succinct description of the object type.
+        Use this approach for icons, especially when they have no tooltip or other help text.
+      </para>
+      <example><title>Preferred Style for Documenting Icons</title>
+        <para>
+          Click the <guiicon>Upload</guiicon> (<guiicon><inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="images/reload.png"/>
+            </imageobject>
+          </inlinemediaobject></guiicon>) icon to upload the files to the server.
+        </para>
+      </example>
 			 <para>
 				See the <citetitle>Computer Interfaces</citetitle> chapter in <citetitle>The IBM Style Guide</citetitle> for more information.
 			</para>
@@ -310,7 +339,7 @@ $ vi myFile.txt
             You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required.
             You can use this option for either of the two designs mentioned above.
           </para>
-          
+
 				 <example>
 					<title>Wrapping Long Commands with Continuation Characters</title>
           <para>
@@ -338,6 +367,7 @@ $ vi myFile.txt
 				</example>
 
 			</section>
+
       <section id="replaceable-paths">
         <title>Referring to Replaceable Paths</title>
           <para>
@@ -371,6 +401,89 @@ $ vi myFile.txt
         </section>
 
 		</section>
+    <section><title>Using Escalated Privileges Correctly</title>
+      <note>
+        <para>
+          This section is aimed primarily at Red&nbsp;Hat Training course material, but the principles and guidelines apply equally in any environment.
+        </para>
+      </note>
+      <para>
+        The term <firstterm>escalated privileges</firstterm> refers to changing to a user whose privileges allow operations that a normal user cannot access.
+        It also refers to temporarily changing the privileges of the current user to perfom those operations without actually changing user accounts.
+      </para>
+      <note><title>Classroom Exceptions</title>
+        <para>
+          Although security is important, it is more important to not have unnecessary classroom security distract from the immediate topic being taught.
+        </para>
+      </note>
+      <section><title>General Recommendations</title>
+        <note>
+          <para>
+            These are recommendations, not rules.
+            As with most things, consistency is important.
+            Do not swap between different approaches without reason.
+            Choose which approach works best for your situation and use it consistently.
+          </para>
+        </note>
+        <itemizedlist>
+          <listitem>
+            <para>
+              In all cases, use the minimum privilege level required to achieve the task.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              In exercises, use <command>sudo</command> and <command>sudo -i</command> and set this up to work throughout all relevant systems in the classroom.
+              Do not use <command>su -</command> without good cause.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              When there is a scattered minority of privileged commands in a mostly unprivileged exercise, use <command>sudo</command> on a per-command basis.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              When the exercise is majority privileged, or has a significant number of privileged commands, use <command>sudo -i</command> either at the beginning of the exercise, or at an appropriate step where the privileged commands begin.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              In the narrative, do not show the use of <command>su</command> or <command>sudo</command>, but always show privileged commands with the correct prompt.
+              See <xref linkend="exam-documenting-command-syntax"/> for information about command prompts.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </section>
+      <section><title>Exceptions</title>
+        <para>
+          Some courses are specifically designed to teach <command>sudo</command> and its variations, the use of the related files, such as <filename>/etc/sudoers</filename> and so on.
+          For these courses, use the required variation for the topic being taught.
+        </para>
+        <section><title>Ansible Courses</title>
+          <itemizedlist>
+            <listitem>
+              <para>
+                Ansible courses typically use a <systemitem>devops</systemitem> user with passwordless sudo access (<code>devops	ALL=(ALL)	NOPASSWD: ALL</code>) on managed nodes to enable the use of <command>become</command> without a <command>become</command> password as <systemitem>root</systemitem> to do anything.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                As much as possible, leave the system-wide default as <varname>become: false</varname> or <varname>become: no</varname> and if a single task needs privileges, set <varname>become: true</varname> or <varname>become: yes</varname> on that task.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                If most tasks in a play require escalated privileges, set the entire play to <varname>become: true</varname> or <varname>become: yes</varname> and possibly selectively set individual tasks to <varname>become: false</varname> or <varname>become: no</varname>.
+              </para>
+            </listitem>
+          </itemizedlist>
+          </section>
+      </section>
+
+
+    </section>
+
 		 <section id="view-edit-files">
 			<title>Describing How to View and Edit Files</title>
 			 <para>

en-US/L.xml

@@ -100,9 +100,6 @@
 				 <para>
 					<emphasis>adj.</emphasis> Hyphenate.
 				</para>
-				 <para>
-					See <citetitle>The IBM Style Guide</citetitle> for more information.
-				</para>
 
 			</listitem>