From 8ae111640b7d92dac707b223aa55bb142721af15 Mon Sep 17 00:00:00 2001 From: Tammy Fox Date: Mon, 13 Sep 2004 02:02:12 +0000 Subject: more explanation of screen tag per bug #131647, tweak replaceable entry --- docs-xml-tags-en.xml | 198 +++++++++++++++++++++++++++++++++++++-------------- 1 file 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 @@ - + DocBook XML Tags @@ -191,7 +191,7 @@ browser. -<!--$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-sample"> <title>Sample Chapter</title> @@ -1747,7 +1747,7 @@ At the <prompt>C:\></prompt> prompt, type .... Note When showing example computer output (usually in - screen tags), do you include the prompt or command + screen tags), do not include the prompt or command (unless the command or prompt is the actually computer output you want to show). @@ -1762,27 +1762,26 @@ At the <prompt>C:\></prompt> prompt, type .... - To create replaceable text, you use the tags + To create replaceable text, use the tags <replaceable> and </replaceable> around the text you want to use as a variable. - This example shows the ISBN of our boxed sets with variables: + This example demonstrates how to use the replaceable + tags when referencing the name of an RPM file: - -1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable> - +foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rpm The output: - - 1-58569-xx-y - + +foo-version-number.arch.rpm + @@ -1792,73 +1791,166 @@ At the <prompt>C:\></prompt> prompt, type .... screen + + The <screen> 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 <screen> and closing + </screen> tags around the text you are + emphasizing. + + + + Important - The <screen> 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 - <screen> and closing - </screen> tags around the text you are - emphasizing. + When using the <screen> tag, you must set + everything within that screen, including the + <screen> 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. + - - Important When using the - <screen> tag, you must set everything within - that screen, including the <screen> 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. - + + The <screen> tag set may contain other inline + tags, such as <computeroutput>, + <userinput>, or + <replaceable>. Additional inline tags are not + required by definition. The <screen> 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. + + + If you use inline tags, remember that line breaks inside + <screen> tags create line breaks in any rendered + output. Place any inline tags on the same line as + their content. Do not overuse tagging within a + <screen> tag set. + + + + An example of <screen> is the following: + - - An example of <screen> is the following: - - -<screen> -<computeroutput> -This is an example of a screen. You do not need <para> tags +<screen> +This is an example of a screen. You do not need &lt;para&gt; tags within this command. -</computeroutput> -</screen> - +</screen> + + The output: + + + +This is an example of a screen. You do not need <para> tags +within this command. + + + + Using Inline Tags with <command>screen</command> - The output: + If you choose to use inline tags inside a + <screen> 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 + <computeroutput> tag set around the entire + output. If the user should type the example on the command line or in + a configuration file, use the <userinput> tag + set. Separate input and output with a short sentence of narrative, as + below: - -This is an example of a screen. You do not need <para> -tags within this command. - + <para> + Type the following command: + </para> + +<screen> +<userinput>command -sw file1</userinput> +</screen> + + <para> + You should see the following output: + </para> + +<screen> +<computeroutput>Completed, time = 0.12 sec</computeroutput> +</screen> - - Note To properly use the - <screen> 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 - <computeroutput> tag set. If it is a command, - it needs the <command> tag set. If it is a - command with user input, it may require a construction like the one - below: + + The output looks like: + + + + Type the following command: + + -<command>command <userinput>input</userinput></command> +command -sw file1 - The output looks like: + You should see the following output: -command input +Completed, time = 0.12 sec + + + Note + + When showing a command or series of commands inside + screen tags, do not show the prompt. + + + If the <screen> shows the reader how to + change only part of a line, mark the change with + an inline <userinput> tag set. You may use + the <userinput> tag set inside a larger area + that is already marked inline with + <computeroutput>. 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> + Edit the <filename>/etc/sysconfig/init</filename> file as follows: + </para> + +<screen> +GRAPHICAL=<userinput>yes</userinput> +</screen> + + + + The output looks like: + + + + Edit the /etc/sysconfig/init file as follows: + + + +GRAPHICAL=yes + + + + For an explanation of how to use the replaceable + tags within a set of screen tags, refer to . + + + -- cgit