more explanation of screen tag per bug #131647, tweak replaceable entry

1 files changed, 145 insertions, 53 deletions

diff --git a/docs-xml-tags-en.xml b/docs-xml-tags-en.xml
index c4259e3..87b77d4 100644
--- a/docs-xml-tags-en.xml
+++ b/docs-xml-tags-en.xml
@@ -1,4 +1,4 @@
-<!-- $Id: docs-xml-tags-en.xml,v 1.10 2004/08/31 15:46:17 tfox Exp $ -->
+<!-- $Id: docs-xml-tags-en.xml,v 1.11 2004/09/13 02:02:12 tfox Exp $ -->
 
   <chapter id="ch-xml-tags">
     <title>DocBook XML Tags</title>
@@ -191,7 +191,7 @@ browser.
 
 <screen>
 <computeroutput>
-&lt;!--$Id: docs-xml-tags-en.xml,v 1.10 2004/08/31 15:46:17 tfox Exp $ --&gt;
+&lt;!--$Id: docs-xml-tags-en.xml,v 1.11 2004/09/13 02:02:12 tfox Exp $ --&gt;
 
   &lt;chapter id="ch-sample"&gt;
     &lt;title&gt;Sample Chapter&lt;/title&gt;
@@ -1747,7 +1747,7 @@ At the &lt;prompt&gt;C:\>&lt;/prompt&gt; prompt, type ....
 	<title>Note</title> 
 	<para>
 	  When showing example computer output (usually in
-	  <command>screen</command> tags), do you include the prompt or command
+	  <command>screen</command> tags), do not include the prompt or command
 	  (unless the command or prompt is the actually computer output you want
 	  to show).</para>
       </note>
@@ -1762,27 +1762,26 @@ At the &lt;prompt&gt;C:\>&lt;/prompt&gt; prompt, type ....
       </indexterm>
       
       <para>
-	To create replaceable text, you use the tags
+	To create replaceable text, use the tags
 	<command>&lt;replaceable&gt;</command> and
 	<command>&lt;/replaceable&gt;</command> around the text you want to use as a
 	variable.
       </para>
       <para>
-	This example shows the ISBN of our boxed sets with variables:
+	This example demonstrates how to use the <command>replaceable</command>
+	tags when referencing the name of an RPM file:
       </para>
 <screen>
-<computeroutput>
-1-58569-&lt;replaceable&gt;xx&lt;/replaceable&gt;-&lt;replaceable&gt;y&lt;/replaceable&gt;
-</computeroutput>
+foo-&lt;replaceable&gt;version-number&lt;/replaceable&gt;.&lt;replaceable&gt;arch&lt;/replaceable&gt;.rpm
 </screen>
 
       <para>
 	The output:
       </para>
 
-      <para>
-	1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable>
-      </para>
+<screen>
+foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rpm
+</screen>
     </sect1>
 
     <sect1 id="s1-xml-tags-screen">
@@ -1792,73 +1791,166 @@ At the &lt;prompt&gt;C:\>&lt;/prompt&gt; prompt, type ....
 	<secondary>screen</secondary>
       </indexterm>
       
+    <para>
+      The <command>&lt;screen&gt;</command> command is used to format text
+      within a document and is great for adding emphasis to show examples of
+      code, computer output, and more. In HTML with the Fedora CSS file, this
+      appears in box with a grey background. To use this command you only need
+      the opening <command>&lt;screen&gt;</command> and closing
+      <command>&lt;/screen&gt;</command> tags around the text you are
+      emphasizing.
+    </para>
+
+    <important>
+      <title>Important</title> 
       <para>
-	The <command>&lt;screen&gt;</command> command is used to format text
-	within a document and is great for adding emphasis to show examples of
-	code, computer output, and more. In HTML, this appears in a grey
-	background. To use this command you only need the opening
-	<command>&lt;screen&gt;</command> and closing
-	<command>&lt;/screen&gt;</command> tags around the text you are
-	emphasizing.
+	When using the <command>&lt;screen&gt;</command> tag, you must set
+	everything within that screen, including the
+	<command>&lt;screen&gt;</command> tags themselves, to flush left. This
+	must be done so that when it is converted to HTML, it will not have
+	extra blank space in front of it inside the gray background.
       </para>
+    </important>
 
-      <important>
-	<title>Important</title> <para>When using the
-	  <command>&lt;screen&gt;</command> tag, you must set everything within
-	  that screen, including the <command>&lt;screen&gt;</command> tags
-	  themselves, to flush left. This must be done so that when it is
-	  converted to HTML, it will not have extra blank space in front of it
-	  inside the gray background.</para>
-      </important>
+    <para>
+      The <command>&lt;screen&gt;</command> tag set may contain other inline
+      tags, such as <command>&lt;computeroutput&gt;</command>,
+      <command>&lt;userinput&gt;</command>, or
+      <command>&lt;replaceable&gt;</command>. Additional inline tags are not
+      required by definition. The <command>&lt;screen&gt;</command> tags by
+      themselves may provide sufficient context, especially for simple examples
+      or file listings. Consider the context of the example, and use inline tags
+      if they are helpful to the reader.
+    </para>
 
+    <para>
+      If you use inline tags, remember that line breaks inside
+      <command>&lt;screen&gt;</command> tags create line breaks in any rendered
+      output. Place any inline tags <emphasis>on the same line</emphasis> as
+      their content. Do not overuse tagging within a
+      <command>&lt;screen&gt;</command> tag set.
+    </para>
+
+    <para>
+      An example of <command>&lt;screen&gt;</command> is the following:
+    </para>
 
-      <para>
-	An example of <command>&lt;screen&gt;</command> is the following:
-      </para>
 <screen>
-<computeroutput>
-&lt;screen&gt;
-&lt;computeroutput&gt;
-This is an example of a screen. You do not need &lt;para&gt; tags 
+<computeroutput>&lt;screen&gt;
+This is an example of a screen. You do not need &amp;lt;para&amp;gt; tags
 within this command.
-&lt;/computeroutput&gt;
-&lt;/screen&gt;
-</computeroutput>
+&lt;/screen&gt;</computeroutput>
 </screen>
 	  
+    <para>
+      The output:
+    </para>
+
+<screen>
+This is an example of a screen.  You do not need &lt;para&gt; tags
+within this command.
+</screen>
+
+    <sect2 id="s2-xml-tags-screen-inline-tags">
+      <title>Using Inline Tags with <command>screen</command></title>
       <para>
-	The output:
+	If you choose to use inline tags inside a
+	<command>&lt;screen&gt;</command> section, follow these guidelines for
+	consistency. If the content in the screen is a listing of a
+	configuration file or the output of a program, use the
+	<command>&lt;computeroutput&gt;</command> tag set around the entire
+	output. If the user should type the example on the command line or in
+	a configuration file, use the <command>&lt;userinput&gt;</command> tag
+	set. Separate input and output with a short sentence of narrative, as
+	below:
       </para>
 
 <screen>
-<computeroutput>
-This is an example of a screen.  You do not need <command>&lt;para&gt;</command>
-tags within this command.
-</computeroutput>
+	<command>&lt;para&gt;</command>
+	  Type the following command:
+	<command>&lt;/para&gt;</command>
+
+<command>&lt;screen&gt;</command>
+<command>&lt;userinput&gt;</command>command -sw file1<command>&lt;/userinput&gt;</command>
+<command>&lt;/screen&gt;</command>
+
+	<command>&lt;para&gt;</command>
+	  You should see the following output:
+	<command>&lt;/para&gt;</command>
+
+<command>&lt;screen&gt;</command>
+<command>&lt;computeroutput&gt;</command>Completed, time = 0.12 sec<command>&lt;/computeroutput&gt;</command>
+<command>&lt;/screen&gt;</command>
 </screen>
 
-      <note>
-	<title>Note</title> <para>To properly use the
-	  <command>&lt;screen&gt;</command> tag set, you also need to properly
-	  tag the content within the screen. If the content in the screen is a
-	  configuration file or the output of a program, it needs the
-	  <command>&lt;computeroutput&gt;</command> tag set. If it is a command,
-	  it needs the <command>&lt;command&gt;</command> tag set.  If it is a
-	  command with user input, it may require a construction like the one
-	  below:</para>
+	<para>
+	  The output looks like:
+	</para>
+
+	<para>
+	  Type the following command:
+	</para>
+
 <screen>
-<command>&lt;command&gt;</command>command <command>&lt;userinput&gt;</command>input<command>&lt;/userinput&gt;</command><command>&lt;/command&gt;</command>
+<userinput>command -sw file1</userinput>
 </screen>
 
 	<para>
-	  The output looks like:
+	  You should see the following output:
 	</para>
 
 <screen>
-<command>command <userinput>input</userinput></command>	  
+<computeroutput>Completed, time = 0.12 sec</computeroutput>
 </screen>
+
+	<note>
+	  <title>Note</title>
+	  <para>
+	    When showing a command or series of commands inside
+	    <command>screen</command> tags, do not show the prompt.
+	  </para>
 	</note>
 
+	<para>
+	  If the <command>&lt;screen&gt;</command> shows the reader how to
+	  change only <emphasis>part</emphasis> of a line, mark the change with
+	  an inline <command>&lt;userinput&gt;</command> tag set. You may use
+	  the <command>&lt;userinput&gt;</command> tag set inside a larger area
+	  that is already marked inline with
+	  <command>&lt;computeroutput&gt;</command>. Do not include any extra
+	  lines of context in this case, unless excluding them would confuse the
+	  reader. The following example illustrates these guidelines:
+	</para>
+
+<screen>
+	<command>&lt;para&gt;</command>
+	  Edit the <command>&lt;filename&gt;</command>/etc/sysconfig/init<command>&lt;/filename&gt;</command> file as follows:
+	<command>&lt;/para&gt;</command>
+
+<command>&lt;screen&gt;</command>
+GRAPHICAL=<command>&lt;userinput&gt;</command>yes<command>&lt;/userinput&gt;</command> 
+<command>&lt;/screen&gt;</command>
+</screen>
+
+	<para>
+  	The output looks like:
+	</para>
+
+	<para>
+	  Edit the <filename>/etc/sysconfig/init</filename> file as follows:
+	</para>
+
+<screen>
+GRAPHICAL=<userinput>yes</userinput>
+</screen>
+
+	<para>
+	  For an explanation of how to use the <command>replaceable</command>
+	  tags within a set of <command>screen</command> tags, refer to <xref
+	  linkend="s1-xml-tags-replaceable"></xref>.
+	</para>
+
+      </sect2>
     </sect1>
 
       <sect1 id="s1-xml-tags-sections">