path: root/en_US/docs-rh-guidelines.xml

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;

]>

  <chapter id="ch-rh-guidelines">
    <title>&RH; Documentation Guidelines</title>

    <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>XML tags</primary>
	<secondary>naming conventions</secondary>
      </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>

<screen>
<computeroutput>
&lt;chapter id="ch-uniquename"&gt;

&lt;sect3="s3-install-make-disks"&gt;

&lt;figure id="fig-redhat-config-kickstart-basic"&gt;
</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>

      <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>
      
      <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>
      
      <para>Some examples are <command>"ch-uniquename"</command> (with 13
	characters) and <command>"s3-install-make-disks"</command> (with 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>
	All the files must contain the CVS Id header.
      </para>

      <para>
	If you create a new file, the first line must be:
      </para>
<screen>
<computeroutput>
&lt;!-- $Id: --&gt;
</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>
<computeroutput>
&lt;!-- $Id: docs-rh-guidelines.xml,v 1.1 2006/11/23 02:24:17 pfrields Exp $ --&gt;
</computeroutput>
</screen>

    </sect1>

    <sect1 id="s1-xml-admon">
      <title>Admonitions</title>

      <indexterm>
	<primary>admonitions</primary>
      </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>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>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>admonitions</secondary>
	<tertiary>important</tertiary>
      </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>
&lt;note&gt;
&lt;title&gt;Note&lt;/title&gt;
&lt;para&gt;Body of text goes here.&lt;/para&gt;
&lt;/note&gt;
</computeroutput>
</screen>

	<note>
	  <title>Note</title> <para>Body of text goes here.</para>
	</note>

	  
<screen>
<computeroutput>
&lt;tip&gt;
&lt;title&gt;Tip&lt;/title&gt;
&lt;para&gt;Body of text goes here.&lt;/para&gt;
&lt;/tip&gt;
</computeroutput>
</screen>

	<tip>
	  <title>Tip</title>
	  <para>Body of text goes here</para> 
	</tip>

<screen>
<computeroutput>
&lt;caution&gt;
&lt;title&gt;Caution&lt;/title&gt;
&lt;para&gt;Body of text goes here.&lt;/para&gt;
&lt;/caution&gt;
</computeroutput>
</screen>

	<caution>
	  <title>Caution</title> <para>Body of text goes here.</para>
	</caution>


<screen>
<computeroutput>
&lt;important&gt;
&lt;title&gt;Important&lt;/title&gt;
&lt;para&gt;Body of text goes here.&lt;/para&gt;
&lt;/important&gt;
</computeroutput>
</screen>

	<important>
	  <title>Important</title>
	  <para>Body of text goes here.</para>
	</important>
	
<screen>
<computeroutput>
&lt;warning&gt;
&lt;title&gt;Warning&lt;/title&gt;
&lt;para&gt;Body of text goes here.&lt;/para&gt;
&lt;/warning&gt;
</computeroutput>
</screen>

	<warning>
	  <title>Warning</title> <para>Body of text goes here.</para>
	</warning>
      </sect2>

    </sect1>

    <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>

      <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> -&gt; <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>
		  -&gt; <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
 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>

	      <para>
		The output will appear similar to:
	      </para>

	      <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>

      <para>
	To be written
      </para>

    </sect1>	

  </chapter>