diff options
| -rw-r--r-- | en_US/docs-rh-guidelines.xml | 966 | ||||
| -rw-r--r-- | en_US/docs-xml-tags.xml | 37 |
2 files changed, 476 insertions, 527 deletions
diff --git a/en_US/docs-rh-guidelines.xml b/en_US/docs-rh-guidelines.xml index bc8b467..f243058 100644 --- a/en_US/docs-rh-guidelines.xml +++ b/en_US/docs-rh-guidelines.xml @@ -7,589 +7,529 @@ ]> - <chapter id="ch-rh-guidelines"> - <title>&RH; Documentation Guidelines</title> +<chapter id="ch-rh-guidelines"> + <title>&RH; Documentation Guidelines</title> - <indexterm> - <primary>recursion</primary> - <see>recursion</see> - </indexterm> + <indexterm> + <primary>recursion</primary> + <see>recursion</see> + </indexterm> - <indexterm> - <primary>RTFM</primary> - <secondary>read the f*'ing manual</secondary> - <seealso>humor</seealso> - </indexterm> + <indexterm> + <primary>RTFM</primary> + <secondary>read the f*'ing manual</secondary> + <seealso>humor</seealso> + </indexterm> - <indexterm> - <primary>humor</primary> - <secondary>RTFM</secondary> - </indexterm> + <indexterm> + <primary>humor</primary> + <secondary>RTFM</secondary> + </indexterm> - <para>Please read this chapter carefully. This chapter describes the - guidelines that must be followed such as naming conventions. - </para> + <para>Please read this chapter carefully. This chapter describes the + guidelines that must be followed such as naming conventions.</para> - <sect1 id="s1-xml-guidelines-naming"> - <title>ID Naming Conventions</title> + <sect1 id="s1-xml-guidelines-naming"> + <title>ID Naming Conventions</title> - <indexterm> - <primary>XML tags</primary> - <secondary>naming conventions</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>naming conventions</secondary> + </indexterm> - <indexterm> - <primary>naming conventions</primary> - </indexterm> + <indexterm> + <primary>naming conventions</primary> + </indexterm> - <para>You will see certain ID names referred to below and this will - help to explain how we come up with those names. For example: - </para> + <para>You will see certain ID names referred to below and this will + help to explain how we come up with those names. For + example:</para> -<screen> -<computeroutput> -<chapter id="ch-uniquename"> + <screen><![CDATA[<chapter id="ch-uniquename"> -<sect3="s3-install-make-disks"> +<section id="sn-install-make-disks"> -<figure id="fig-redhat-config-kickstart-basic"> -</computeroutput> -</screen> +<figure id="fig-redhat-config-kickstart-basic">]]></screen> - <para>IDs are unique identifiers, allowing DocBook XML to know where to - cross-reference a section or chapter or the like. - </para> - - <para>The general rules for defining an ID are:</para> + <para>IDs are unique identifiers, allowing DocBook XML to know where + to cross-reference a section or chapter or the like. The + following general rules apply to IDs:</para> - <indexterm> - <primary>XML tags</primary> - <secondary>rules for defining an ID</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> - <indexterm> - <primary>naming conventions</primary> - <secondary>rules for defining an ID</secondary> - </indexterm> + <indexterm> + <primary>naming conventions</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> - <itemizedlist> - <listitem> - <para>Keep it 32 characters or under (this is counted as - everything between the quotation marks)</para> - </listitem> - <listitem> - <para>Keep it as short and simple as possible</para> - </listitem> - <listitem> - <para>Make sure the name is relevant to the information (make it - recognizable)</para> - </listitem> - </itemizedlist> + <itemizedlist> + <listitem> + <para>Restrict the ID name, which is everything between the + quotation marks, to 32 characters or fewer</para> + </listitem> + <listitem> + <para>Keep it as short and simple as possible</para> + </listitem> + <listitem> + <para>Make sure the name is recognizable and relevant to the + information</para> + </listitem> + </itemizedlist> - <para>Some examples are <command>"ch-uniquename"</command> (with 13 - characters) and <command>"s3-install-make-disks"</command> (with 21 - characters). - </para> + <para>Some examples are <command>"ch-uniquename"</command> (13 + characters) and <command>"sn-install-make-disks"</command> (21 + characters).</para> + + <para>A section within a particular chapter always uses the chapter + name (minus the <command>"ch-"</command>) in its ID. For example, + you are working with the <command>"ch-intro"</command> chapter and + need to create your first section on disk partitions. That section + ID would look similar to <command>"s1-intro-partition"</command> + which contains the section number, the main chapter ID, and a + unique ID for that section.</para> + + <table id="tb-xml-namingconventions"> + <title>Naming Conventions</title> + + <tgroup cols="2"> + <colspec colnum="1" colname="tag" colwidth="100"/> + <colspec colnum="2" colname="prefix" colwidth="100"/> + <thead> + <row> + <entry>Tag</entry> + <entry>Prefix</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preface</command></entry> + <entry><computeroutput>pr-</computeroutput></entry> + </row> + <row> + <entry><command>chapter</command></entry> + <entry><computeroutput>ch-</computeroutput></entry> + </row> + <row> + <entry><command>section</command></entry> + <entry><computeroutput>sn-</computeroutput></entry> + </row> + <row> + <entry><command>sect1</command></entry> + <entry><computeroutput>s1-</computeroutput></entry> + </row> + <row> + <entry><command>sect2</command></entry> + <entry><computeroutput>s2-</computeroutput></entry> + </row> + <row> + <entry><command>sect3</command></entry> + <entry><computeroutput>s3-</computeroutput></entry> + </row> + <row> + <entry><command>sect4</command></entry> + <entry><computeroutput>s4-</computeroutput></entry> + </row> + <row> + <entry><command>figure</command></entry> + <entry><computeroutput>fig-</computeroutput></entry> + </row> + <row> + <entry><command>table</command></entry> + <entry><computeroutput>tb-</computeroutput></entry> + </row> + <row> + <entry><command>appendix</command></entry> + <entry><computeroutput>ap-</computeroutput></entry> + </row> + <row> + <entry><command>part</command></entry> + <entry><computeroutput>pt-</computeroutput></entry> + </row> + <row> + <entry><command>example</command></entry> + <entry><computeroutput>ex-</computeroutput></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-xml-guidelines-header"> + <title>File Header</title> - <para>A section within a particular chapter always uses the chapter - name (minus the <command>"ch-"</command>) in its ID. For example, you - are working with the <command>"ch-intro"</command> chapter and need to - create your first section on disk partitions. That section ID would look - similar to <command>"s1-intro-partition"</command> which contains the - section number, the main chapter ID, and a unique ID for that section. - </para> + <para>All the files must contain the CVS Id header. If you create a + new file, the first line must be:</para> - <table id="tb-xml-namingconventions"> - <title>Naming Conventions</title> - - <tgroup cols="2"> - <colspec colnum="1" colname="tag" colwidth="100"/> - <colspec colnum="2" colname="prefix" colwidth="100"/> - <thead> - <row> - <entry>Tag</entry> - <entry>Prefix</entry> - </row> - </thead> - <tbody> - <row> - <entry><command>preface</command></entry> - <entry><computeroutput>pr-</computeroutput></entry> - </row> - <row> - <entry><command>chapter</command></entry> - <entry><computeroutput>ch-</computeroutput></entry> - </row> - <row> - <entry><command>section</command></entry> - <entry><computeroutput>sn-</computeroutput></entry> - </row> - <row> - <entry><command>sect1</command></entry> - <entry><computeroutput>s1-</computeroutput></entry> - </row> - <row> - <entry><command>sect2</command></entry> - <entry><computeroutput>s2-</computeroutput></entry> - </row> - <row> - <entry><command>sect3</command></entry> - <entry><computeroutput>s3-</computeroutput></entry> - </row> - <row> - <entry><command>sect4</command></entry> - <entry><computeroutput>s4-</computeroutput></entry> - </row> - <row> - <entry><command>figure</command></entry> - <entry><computeroutput>fig-</computeroutput></entry> - </row> - <row> - <entry><command>table</command></entry> - <entry><computeroutput>tb-</computeroutput></entry> - </row> - <row> - <entry><command>appendix</command></entry> - <entry><computeroutput>ap-</computeroutput></entry> - </row> - <row> - <entry><command>part</command></entry> - <entry><computeroutput>pt-</computeroutput></entry> - </row> - <row> - <entry><command>example</command></entry> - <entry><computeroutput>ex-</computeroutput></entry> - </row> - </tbody> - </tgroup> - </table> - - </sect1> - - <sect1 id="s1-xml-guidelines-header"> - <title>File Header</title> - - <para> - All the files must contain the CVS Id header. - </para> + <screen><![CDATA[<!-- $Id: -->]]></screen> - <para> - If you create a new file, the first line must be: - </para> -<screen> -<computeroutput> -<!-- $Id: --> -</computeroutput> -</screen> - - <para> - The first time it is committed to CVS (and every time it is committed to - CVS) the line is updated automatically to include information about the - file. For example: - </para> + <para>The first time it is committed to CVS (and every time it is + committed to CVS) the line is updated automatically to include + information about the file. For example:</para> -<screen> -<computeroutput> -<!-- $Id: docs-rh-guidelines.xml,v 1.2 2006/12/17 00:41:55 pfrields Exp $ --> -</computeroutput> -</screen> + <screen><![CDATA[<!-- $Id: docs-rh-guidelines.xml,v 1.3 2006/12/23 23:49:59 pfrields Exp $ -->]]></screen> - </sect1> + </sect1> - <sect1 id="s1-xml-admon"> - <title>Admonitions</title> + <sect1 id="s1-xml-admon"> + <title>Admonitions</title> - <indexterm> - <primary>admonitions</primary> - </indexterm> + <indexterm> + <primary>admonitions</primary> + </indexterm> - <indexterm> - <primary>XML tags</primary> - <secondary>warning</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>warning</secondary> + </indexterm> - <indexterm> - <primary>XML tags</primary> - <secondary>tip</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>tip</secondary> + </indexterm> - <indexterm> - <primary>XML tags</primary> - <secondary>note</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>note</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>caution</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>important</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>warning</tertiary> + </indexterm> - <indexterm> - <primary>XML tags</primary> - <secondary>caution</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>tip</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>note</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>caution</tertiary> + </indexterm> - <indexterm> - <primary>XML tags</primary> - <secondary>important</secondary> - </indexterm> + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>important</tertiary> + </indexterm> + + <para>There are five types of admonitions in DocBook: Caution, + Important, Note, Tip, and Warning. All of the admonitions have + the same structure: an optional Title followed by paragraph-level + elements. The DocBook DTD does not impose any specific semantics + on the individual admonitions. For example, DocBook does not + mandate that Warnings be reserved for cases where bodily harm can + result.</para> + + <sect2 id="s2-xml-notesetc"> + <title>Creating Notes, Tips, Cautions, Importants, and + Warnings</title> <indexterm> <primary>XML tags</primary> - <secondary>admonitions</secondary> - <tertiary>warning</tertiary> + <secondary>note</secondary> </indexterm> <indexterm> <primary>XML tags</primary> - <secondary>admonitions</secondary> - <tertiary>tip</tertiary> + <secondary>tip</secondary> </indexterm> <indexterm> <primary>XML tags</primary> - <secondary>admonitions</secondary> - <tertiary>note</tertiary> + <secondary>caution</secondary> </indexterm> <indexterm> <primary>XML tags</primary> - <secondary>admonitions</secondary> - <tertiary>caution</tertiary> + <secondary>important</secondary> </indexterm> <indexterm> <primary>XML tags</primary> - <secondary>admonitions</secondary> - <tertiary>important</tertiary> + <secondary>warning</secondary> </indexterm> - <para>There are five types of admonitions in DocBook: Caution, Important, - Note, Tip, and Warning.</para> - - <para>All of the admonitions have the same structure: an optional Title - followed by paragraph-level elements. The DocBook DTD does not impose any - specific semantics on the individual admonitions. For example, DocBook - does not mandate that Warnings be reserved for cases where bodily harm can - result.</para> - - - <sect2 id="s2-xml-notesetc"> - <title>Creating Notes, Tips, Cautions, Importants, and Warnings</title> - - <indexterm> - <primary>XML tags</primary> - <secondary>note</secondary> - </indexterm> - - <indexterm> - <primary>XML tags</primary> - <secondary>tip</secondary> - </indexterm> - - <indexterm> - <primary>XML tags</primary> - <secondary>caution</secondary> - </indexterm> - - <indexterm> - <primary>XML tags</primary> - <secondary>important</secondary> - </indexterm> - - <indexterm> - <primary>XML tags</primary> - <secondary>warning</secondary> - </indexterm> - - <para>There are several ways to bring attention to text within a - document. A <emphasis>Note</emphasis> is used to bring additional - information to the users' attention. A <emphasis>Tip</emphasis> is - used to show the user helpful information or another way to do - something. A <emphasis>Caution</emphasis> is used to show the user - they must be careful when attempting a certain step. An - <emphasis>Important</emphasis> tag set can be used to show the user a - piece of information that should not be overlooked. While this - information may not change anything the user is doing, it should show - the user that this piece of information could be vital. A - <emphasis>Warning</emphasis> is used to show the reader that their - current setup will change or be altered, such as files being removed, - and they should not choose this operation unless they are alright with - the consequences.</para> - - <para>The following lines of code will show the basic setup for each - case as mentioned above, along with an example of how it would be - displayed in the HTML.</para> - - -<screen> -<computeroutput> -<note> -<title>Note</title> -<para>Body of text goes here.</para> -</note> -</computeroutput> -</screen> - - <note> - <title>Note</title> <para>Body of text goes here.</para> - </note> - - -<screen> -<computeroutput> -<tip> -<title>Tip</title> -<para>Body of text goes here.</para> -</tip> -</computeroutput> -</screen> - - <tip> - <title>Tip</title> - <para>Body of text goes here</para> - </tip> - -<screen> -<computeroutput> -<caution> -<title>Caution</title> -<para>Body of text goes here.</para> -</caution> -</computeroutput> -</screen> - - <caution> - <title>Caution</title> <para>Body of text goes here.</para> - </caution> - - -<screen> -<computeroutput> -<important> -<title>Important</title> -<para>Body of text goes here.</para> -</important> -</computeroutput> -</screen> - - <important> - <title>Important</title> - <para>Body of text goes here.</para> - </important> + <para>There are several ways to bring attention to text within a + document. A <emphasis>Note</emphasis> is used to bring + additional information to the users' attention. A + <emphasis>Tip</emphasis> is used to show the user helpful + information or another way to do something. A + <emphasis>Caution</emphasis> is used to show the user they must + be careful when attempting a certain step. An + <emphasis>Important</emphasis> tag set can be used to show the + user a piece of information that should not be overlooked. While + this information may not change anything the user is doing, it + should show the user that this piece of information could be + vital. A <emphasis>Warning</emphasis> is used to show the reader + that their current setup will change or be altered, such as + files being removed, and they should not choose this operation + unless they are alright with the consequences.</para> + + <para>The following lines of code will show the basic setup for + each case as mentioned above, along with an example of how it + would be displayed in the HTML.</para> + + <screen><![CDATA[<note> + <title>Note</title> + <para>Body of text goes here.</para> +</note>]]></screen> + + <note> + <title>Note</title> + <para>Body of text goes here.</para> + </note> + + <screen><![CDATA[<tip> + <title>Tip</title> + <para>Body of text goes here.</para> +</tip>]]></screen> + + <tip> + <title>Tip</title> + <para>Body of text goes here</para> + </tip> + + <screen><![CDATA[<caution> + <title>Caution</title> + <para>Body of text goes here.</para> +</caution>]]></screen> + + <caution> + <title>Caution</title> + <para>Body of text goes here.</para> + </caution> + + <screen><![CDATA[<important> + <title>Important</title> + <para>Body of text goes here.</para> +</important>]]></screen> + + <important> + <title>Important</title> + <para>Body of text goes here.</para> + </important> -<screen> -<computeroutput> -<warning> -<title>Warning</title> -<para>Body of text goes here.</para> -</warning> -</computeroutput> -</screen> + <screen><![CDATA[<warning> + <title>Warning</title> + <para>Body of text goes here.</para> +</warning>]]></screen> - <warning> - <title>Warning</title> <para>Body of text goes here.</para> - </warning> - </sect2> + <warning> + <title>Warning</title> + <para>Body of text goes here.</para> + </warning> + </sect2> - </sect1> + </sect1> - <sect1 id="s1-screenshots"> - <title>Screenshots</title> + <sect1 id="s1-screenshots"> + <title>Screenshots</title> - <indexterm> - <primary>screenshots</primary> - <secondary>how to take</secondary> - </indexterm> - <indexterm> - <primary>screen captures</primary> - <see>screenshots</see> - </indexterm> - <indexterm> - <primary>screen grabs</primary> - <see>screenshots</see> - </indexterm> + <indexterm> + <primary>screenshots</primary> + <secondary>how to take</secondary> + </indexterm> + <indexterm> + <primary>screen captures</primary> + <see>screenshots</see> + </indexterm> + <indexterm> + <primary>screen grabs</primary> + <see>screenshots</see> + </indexterm> - <para> - There are two types of screenshots: graphical and textual. The - philosophy on using these two types is <firstterm>rely on text over - graphics</firstterm>. This means, if you can say it in text instead of - showing a graphic, do so. A graphical screenshot of a GUI can create a good - setting of objects to then describe textually, but you don't want to create - a screenshot for each graphical step. - </para> - <para> - The main reason for this preference is that a block of text can usually - convey more meaning than the same physical space of graphics. This is - highly dependent on the graphic; obviously, a photographic image of a - scene can convey more than 1000 words can. A GUI screenshot is usually - full of blank space with a few elements that can just as easily be - described or listed. - </para> - <para> - The steps for taking a graphical screenshot illustrate how using text to - describe a procedure is more concise than a series of screenshots. - </para> - <variablelist> - <varlistentry> - <term>Graphical Screenshot</term> - <listitem> - <procedure> - <step> - <para> - Set the theme to Bluecurve defaults. This gives a look that - is familiar to most readers, and makes &FDP; documents - consistent. From the panel menu, choose - <guimenu>Preferences</guimenu>, - <guimenuitem>Theme</guimenuitem> and select - <guimenuitem>Bluecurve</guimenuitem> from the theme list. - </para> - </step> - <step> - <para> - Set fonts to Bluecurve defaults as well. From the panel menu, - choose <guimenu>Preferences</guimenu>, - <guimenuitem>Fonts</guimenuitem>. Set the - <guilabel>Application font</guilabel> and the - <guilabel>Desktop font</guilabel> to Sans Regular 10. Set the - <guilabel>Window Title font</guilabel> to Sans Bold 10. Set - the <guilabel>Terminal font</guilabel> to Monospace Regular - 10. - </para> - </step> - <step> - <para> - Before taking the screenshot, try to resize the targeted GUI - element(s) to the smallest possible size they can be. Your - target is an image of 500 pixels or less. If you are doing a - screenshot of more than one GUI element, you may need to - resize the screenshot in a following step. - </para> - </step> - <step> - <para> - To take the screenshot, select the GUI element with your - mouse, bringing it to the forefront, or otherwise arranging - the elements. Press <keycombo> <keycap>Alt</keycap> - <keycap>Print Screen</keycap> </keycombo> to capture a single - GUI window. For capturing the entire desktop use - <keycap>Print Screen</keycap>. If you are taking a shot of - multiple elements and have grouped them closely together, you - can crop the resulting image in <application>The - GIMP</application>. The image will be in the PNG format. - </para> - </step> - <step> - <para> - If you need to, you can resize using <application>The - GIMP</application>. With the image open, right-click on it - and choose <guimenu>Image</guimenu> -> <guimenuitem>Scale - Image...</guimenuitem>. With the chain symbol intact, set the - <guilabel>New Width</guilabel> to <guilabel>500 px</guilabel>, - and click <guibutton>OK</guibutton>. Be sure to <keycombo> - <keycap>Ctrl</keycap> <keycap>s</keycap> </keycombo> to save - your changes to your PNG before converting to EPS. - </para> + <para>There are two types of screenshots: graphical and textual. + The philosophy on using these two types is <firstterm>rely on text + over graphics</firstterm>. This means, if you can say it in + text instead of showing a graphic, do so. A graphical screenshot + of a GUI can create a good setting of objects to then describe + textually, but you don't want to create a screenshot for each + graphical step.</para> + <para>The main reason for this preference is that a block of text + can usually convey more meaning than the same physical space of + graphics. This is highly dependent on the graphic; obviously, a + photographic image of a scene can convey more than 1000 words can. + A GUI screenshot is usually full of blank space with a few + elements that can just as easily be described or listed.</para> + <para>The steps for taking a graphical screenshot illustrate how + using text to describe a procedure is more concise than a series + of screenshots.</para> + <variablelist> + <varlistentry> + <term>Graphical Screenshot</term> + <listitem> + <procedure> + <step> + <para>Set the theme to Bluecurve defaults. This gives a look + that is familiar to most readers, and makes &FDP; + documents consistent. From the panel menu, choose + <guimenu>Preferences</guimenu>, + <guimenuitem>Theme</guimenuitem> and select + <guimenuitem>Bluecurve</guimenuitem> from the theme + list.</para> + </step> + <step> + <para>Set fonts to Bluecurve defaults as well. From the + panel menu, choose <guimenu>Preferences</guimenu>, + <guimenuitem>Fonts</guimenuitem>. Set the + <guilabel>Application font</guilabel> and the + <guilabel>Desktop font</guilabel> to Sans Regular 10. + Set the <guilabel>Window Title font</guilabel> to Sans + Bold 10. Set the <guilabel>Terminal font</guilabel> to + Monospace Regular 10.</para> + </step> + <step> + <para>Before taking the screenshot, try to resize the + targeted GUI element(s) to the smallest possible size + they can be. Your target is an image of 500 pixels or + less. If you are doing a screenshot of more than one + GUI element, you may need to resize the screenshot in a + following step.</para> + </step> + <step> + <para>To take the screenshot, select the GUI element with + your mouse, bringing it to the forefront, or otherwise + arranging the elements. Press <keycombo> + <keycap>Alt</keycap> + <keycap>Print Screen</keycap> </keycombo> to capture a + single GUI window. For capturing the entire desktop use + <keycap>Print Screen</keycap>. If you are taking a shot + of multiple elements and have grouped them closely + together, you can crop the resulting image in + <application>The GIMP</application>. The image will be + in the PNG format.</para> </step> <step> - <para> - With the image open in <application>The GIMP</application>, - right-click on the image, selecting <guimenu>File</guimenu> - -> <guimenuitem>Save As...</guimenuitem>. Under - <guimenu>Determine File Type:</guimenu>, select - <guimenuitem>PostScript</guimenuitem>, then click - <guibutton>OK</guibutton>. Allow flattening of the image by - clicking <guibutton>Export</guibutton>. - </para> - <para> - In the <guilabel>Save as PostScript</guilabel> window, select - <guilabel>Encapsulated PostScript</guilabel>, and click - <guibutton>OK</guibutton>. - </para> - </step> - </procedure> - <para> - For more information about calling the images from the XML, refer - to <xref linkend="s1-xml-tags-figure"/>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Text Screenshot</term> - <listitem> - <para>Textual screen information is also useful for readers. If you - use a graphical screenshot to illustrate a function, and the - textual mode has identical functions, you should not include - both, unless omitting either would make your description - unclear. You should make your information generic over specific. - Omit the username and machine information, and separate what the - user types from sample command output. Also, in - <command>screen</command> tags, what the user types should be in - <command>userinput</command> tags, and what the user is shown as - output should be in <command>computeroutput</command> tags. - For example, the usage in - <xref linkend="ex-text-screenshot-bad"/> should look like <xref + <para>If you need to, you can resize using + <application>The GIMP</application>. With the image + open, right-click on it and choose + <guimenu>Image</guimenu> -> <guimenuitem>Scale + Image...</guimenuitem>. With the chain symbol intact, + set the <guilabel>New Width</guilabel> to <guilabel>500 + px</guilabel>, and click <guibutton>OK</guibutton>. + Be sure to <keycombo> + <keycap>Ctrl</keycap> <keycap>s</keycap> </keycombo> + to save your changes to your PNG before converting to + EPS.</para> + </step> + <step> + <para> + With the image open in <application>The + GIMP</application>, right-click on the image, + selecting <guimenu>File</guimenu> -> + <guimenuitem>Save As...</guimenuitem>. Under + <guimenu>Determine File Type:</guimenu>, select + <guimenuitem>PostScript</guimenuitem>, then click + <guibutton>OK</guibutton>. Allow flattening of the image + by clicking <guibutton>Export</guibutton>.</para> + <para>In the <guilabel>Save as PostScript</guilabel> + window, select <guilabel>Encapsulated + PostScript</guilabel>, and click + <guibutton>OK</guibutton>.</para> + </step> + </procedure> + <para>For more information about calling the images from the + XML, refer to <xref linkend="s1-xml-tags-figure"/>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Text Screenshot</term> + <listitem> + <para>Textual screen information is also useful for readers. + If you use a graphical screenshot to illustrate a function, + and the textual mode has identical functions, you should not + include both, unless omitting either would make your + description unclear. You should make your information + generic over specific. Omit the username and machine + information, and separate what the user types from sample + command output. Also, in <command>screen</command> tags, + what the user types should be in + <command>userinput</command> tags, and what the user is + shown as output should be in + <command>computeroutput</command> tags. For example, the + usage in + <xref linkend="ex-text-screenshot-bad"/> should look like + <xref linkend="ex-text-screenshot-good"/>. - </para> - <example id="ex-text-screenshot-bad"> - <title>Incorrect Textual Screenshot</title> - <screen> -<userinput>ps ax | grep ssh</userinput> -<computeroutput> - 2564 ? S 0:23 /usr/sbin/sshd + </para> + <example id="ex-text-screenshot-bad"> + <title>Incorrect Textual Screenshot</title> + <screen><userinput>ps ax | grep ssh</userinput> +<computeroutput> 2564 ? S 0:23 /usr/sbin/sshd 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients 8235 ? S 0:00 ssh -Nf rocky@philadelphia.net -L 6667:localhost 17223 pts/0 S 0:00 ssh rbalboa@core-router7 17227 pts/2 S 0:10 ssh rbalboa@smbshare2 -21113 pts/7 S 1:19 ssh rocky@xxx.private -</computeroutput> - </screen> - </example> - <example id="ex-text-screenshot-good"> - <title>Correct Textual Screenshot</title> - <para> - To find all the currently active ssh sessions, execute the - following command: - </para> -<screen> -<command>ps ax | grep ssh</command> -</screen> +21113 pts/7 S 1:19 ssh rocky@xxx.private</computeroutput></screen> + </example> + <example id="ex-text-screenshot-good"> + <title>Correct Textual Screenshot</title> + <para>To find all the currently active ssh sessions, execute the + following command:</para> + <screen><command>ps ax | grep ssh</command></screen> - <para> - The output will appear similar to: - </para> + <para>The output will appear similar to:</para> - <screen> -<computeroutput> - 2564 ? S 0:23 /usr/sbin/sshd + <screen><computeroutput> 2564 ? S 0:23 /usr/sbin/sshd 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients 8032 pts/0 S 0:00 ssh user@host.example.com - 8032 pts/1 S 0:00 ssh root@backup.example.com -</computeroutput> - </screen> - </example> - <para> - For more information about using screen, refer to <xref - linkend="s1-xml-tags-screen"/>. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="s1-diagrams-images"> - <title>Diagrams and Images</title> - - <indexterm> - <primary>images</primary> - </indexterm> - <indexterm> - <primary>diagrams</primary> - <secondary>creating</secondary> - </indexterm> + 8032 pts/1 S 0:00 ssh root@backup.example.com</computeroutput></screen> + </example> + <para>For more information about using screen, refer to <xref + linkend="s1-xml-tags-screen"/>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + +<!-- + <sect1 id="s1-diagrams-images"> + <title>Diagrams and Images</title> + + <indexterm> + <primary>images</primary> + </indexterm> + <indexterm> + <primary>diagrams</primary> + <secondary>creating</secondary> + </indexterm> - <para> + <para> To be written </para> </sect1> +--> - </chapter> - +</chapter> - - +<!-- +Local variables: +mode: xml +fill-column: 72 +End: +--> diff --git a/en_US/docs-xml-tags.xml b/en_US/docs-xml-tags.xml index 6c31779..31a13d2 100644 --- a/en_US/docs-xml-tags.xml +++ b/en_US/docs-xml-tags.xml @@ -1,4 +1,4 @@ -<!-- $Id: docs-xml-tags.xml,v 1.2 2006/12/17 00:41:55 pfrields Exp $ --> +<!-- $Id: docs-xml-tags.xml,v 1.3 2006/12/23 23:49:59 pfrields Exp $ --> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ @@ -35,7 +35,9 @@ <secondary>general tag information</secondary> </indexterm> - <para>All tags in XML must have an opening and closing tag Additionally, + <para>Most tags in XML must have an opening and closing tag. A few + tags, such as <sgmltag class="emptytag">xref</sgmltag>, have no + content and close themselves. Additionally, proper XML conventions say that there must be a unique identifier for sections, chapters, figures, tables, and so on, so that they may be correctly identified, and cross referenced if needed.</para> @@ -137,12 +139,11 @@ <varlistentry> <term>Content inside <command>screen</command> tags</term> <listitem> - <para>The <command>screen</command> tags (<screen> and - </screen>) <emphasis>must</emphasis> be flush left in the - XML file, and all the content inside the - <command>screen</command> tags must be flush left as well unless - the white space in intentional; otherwise, the extraneous - whitespace will appear in the HTML version. + <para>The content inside <command>screen</command> tags + (<screen> and </screen>) + <emphasis>must</emphasis> be flush left in the XML file; + otherwise, the extraneous whitespace will appear in the HTML + version. </para> </listitem> </varlistentry> @@ -200,7 +201,7 @@ browser. <screen> <computeroutput> -<!--$Id: docs-xml-tags.xml,v 1.2 2006/12/17 00:41:55 pfrields Exp $ --> +<!--$Id: docs-xml-tags.xml,v 1.3 2006/12/23 23:49:59 pfrields Exp $ --> <chapter id="ch-sample"> <title>Sample Chapter</title> @@ -1813,11 +1814,12 @@ foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rp <important> <title>Important</title> <para> - When using the <command><screen></command> tag, you must set - everything within that screen, including the - <command><screen></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. + When using the <command><screen></command> tag, set + everything within that screen to flush left. The contents of + the <sgmltag class="starttag">screen</sgmltag> element are + rendered exactly as is, including any indentation. Using flush + left prevents extra blank space in front of the text inside the + gray background when the content is converted to HTML. </para> </important> @@ -2498,3 +2500,10 @@ For more information about the parent file, refer to </sect1> </chapter> + +<!-- +Local variables: +mode: xml +fill-column: 72 +End: +--> |