documentation-guide/en_US docs-rh-guidelines.xml, 1.2, 1.3 docs-xml-tags.xml, 1.2, 1.3
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sat Dec 23 23:50:01 UTC 2006
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv26144/en_US
Modified Files:
docs-rh-guidelines.xml docs-xml-tags.xml
Log Message:
Minor changes, major reformatting. Sorry about the noise.
Index: docs-rh-guidelines.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/docs-rh-guidelines.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- docs-rh-guidelines.xml 17 Dec 2006 00:41:55 -0000 1.2
+++ docs-rh-guidelines.xml 23 Dec 2006 23:49:59 -0000 1.3
@@ -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>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>
+
+ <sect1 id="s1-xml-guidelines-naming">
+ <title>ID Naming Conventions</title>
<indexterm>
- <primary>RTFM</primary>
- <secondary>read the f*'ing manual</secondary>
- <seealso>humor</seealso>
+ <primary>XML tags</primary>
+ <secondary>naming conventions</secondary>
</indexterm>
<indexterm>
- <primary>humor</primary>
- <secondary>RTFM</secondary>
+ <primary>naming conventions</primary>
</indexterm>
- <para>Please read this chapter carefully. This chapter describes the
- guidelines that must be followed such as naming conventions.
- </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>
- <sect1 id="s1-xml-guidelines-naming">
- <title>ID Naming Conventions</title>
+ <screen><![CDATA[<chapter id="ch-uniquename">
- <indexterm>
- <primary>XML tags</primary>
- <secondary>naming conventions</secondary>
- </indexterm>
+<section id="sn-install-make-disks">
- <indexterm>
- <primary>naming conventions</primary>
- </indexterm>
+<figure id="fig-redhat-config-kickstart-basic">]]></screen>
- <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">
-
-<sect3="s3-install-make-disks">
-
-<figure id="fig-redhat-config-kickstart-basic">
-</computeroutput>
-</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>
- <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>
- </sect1>
+ <para>All the files must contain the CVS Id header. If you create a
+ new file, the first line must be:</para>
- <sect1 id="s1-xml-guidelines-header">
- <title>File Header</title>
+ <screen><![CDATA[<!-- $Id: -->]]></screen>
- <para>
- All the files must contain the CVS Id header.
- </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>
- <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>
+ <screen><![CDATA[<!-- $Id$ -->]]></screen>
-<screen>
-<computeroutput>
-<!-- $Id$ -->
-</computeroutput>
-</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>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>note</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>caution</secondary>
- </indexterm>
+ <indexterm>
+ <primary>XML tags</primary>
+ <secondary>admonitions</secondary>
+ <tertiary>important</tertiary>
+ </indexterm>
- <indexterm>
- <primary>XML tags</primary>
- <secondary>important</secondary>
- </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>
-
- <warning>
- <title>Warning</title> <para>Body of text goes here.</para>
- </warning>
- </sect2>
+ <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>
- </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 at philadelphia.net -L 6667:localhost
17223 pts/0 S 0:00 ssh rbalboa at core-router7
17227 pts/2 S 0:10 ssh rbalboa at smbshare2
-21113 pts/7 S 1:19 ssh rocky at 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 at 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 at host.example.com
- 8032 pts/1 S 0:00 ssh root at 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 at 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:
+-->
Index: docs-xml-tags.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/docs-xml-tags.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- docs-xml-tags.xml 17 Dec 2006 00:41:55 -0000 1.2
+++ docs-xml-tags.xml 23 Dec 2006 23:49:59 -0000 1.3
@@ -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>
@@ -1813,11 +1814,12 @@
<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 @@
</sect1>
</chapter>
+
+<!--
+Local variables:
+mode: xml
+fill-column: 72
+End:
+-->
More information about the Fedora-docs-commits
mailing list