path: root/en_US/writing-guidelines.xml

<!DOCTYPE chapter 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>&FED; Documentation Guidelines</title>

  <indexterm>
    <primary>recursion</primary>
    <see>recursion</see>
  </indexterm>

  <indexterm>
    <primary>RTFM</primary>
    <secondary>read the fine 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>

  <para>This chapter only discusses tags used for documentation for the &PROJECT;,
    not all available DocBook XML tags. For the complete list, refer to
    <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
  </para>

  <section id="sn-id-naming-conventions">
    <title>ID Naming Conventions</title>

    <indexterm>
      <primary>XML tags</primary>
      <secondary>naming conventions</secondary>
    </indexterm>

    <indexterm>
      <primary>naming conventions</primary>
    </indexterm>

    <para>This section explains the ID naming convention. For
      example:</para>

    <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">

<section id="sn-install-make-disks">

<figure id="fig-redhat-config-kickstart-basic">]]></screen>

    <para>IDs are unique identifiers, allowing DocBook XML to know where
      to cross-reference a section, chapter, or other element.  The
      following general rules apply to IDs:</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>
    
    <para>Keep it as short and simple as possible.</para>

    <para>Start the ID with the special short two-character label.  This
    makes URLs and other references to this ID human readable, by
    self-identifying the XML container type.</para>

    <table id="tb-id-two-char-naming-conventions">
      <title>Two-Character 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><sgmltag class="element">preface</sgmltag></entry>
	    <entry><literal>pr-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">chapter</sgmltag></entry>
	    <entry><literal>ch-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">section</sgmltag></entry>
	    <entry><literal>sn-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">figure</sgmltag></entry>
	    <entry><literal>fig-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">table</sgmltag></entry>
	    <entry><literal>tb-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">appendix</sgmltag></entry>
	    <entry><literal>ap-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">part</sgmltag></entry>
	    <entry><literal>pt-</literal></entry>
	  </row>
	  <row>
	    <entry><sgmltag class="element">example</sgmltag></entry>
	    <entry><literal>ex-</literal></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <para>Use the title of the item as the ID.  If your title is not
      unique, there is either a problem you need to fix (titles should
      be unique within a document), or it is part of a template and
      should reflect the containing chapter/section of the template. For
      example:</para>    
    
    <screen><![CDATA[<chapter id="ch-how-to-fold-laundry">
<title>How To Fold Laundry</title>]]></screen>
      
    <screen><![CDATA[<section id="sn-folding-shirts">
<title>Folding Shirts</title>]]></screen>
    
      <indexterm>
	<primary>xml tags</primary>
	<secondary>caveats</secondary>
      </indexterm>
    
      <para>
	It is very important that you remember the caveats in this
	section. These are learned suggestions or rules that make your
	XML experience better.
      </para>

      <variablelist>
	<varlistentry>
	  <term>Do Not Use Trademark Entities</term>
	  <listitem>
	  <para>Do not use the trademark entities <sgmltag
	      class="genentity">trade</sgmltag>, <sgmltag
	      class="genentity">copy</sgmltag>, or <sgmltag
	      class="genentity">reg</sgmltag> because the do not produce
	    HTML output that works for all charsets. The HTML output
	    produces by these entities are declared in the DTD and
	    cannot be changed via the stylesheet.</para>
	  
	  <para>Instead, use the <sgmltag>trademark</sgmltag> tag and its
	    associates classes as follows:
	    </para>
	    <itemizedlist>
	      <listitem>
	      <para><sgmltag
	      class="starttag">trademark</sgmltag>trademark symbol after
	      me<sgmltag class="endtag">trademark</sgmltag>
		</para>
	      </listitem>
	      <listitem>
	      <para><sgmltag class="starttag">trademark
	      class="registered"</sgmltag>registered trademark symbol
	      after me<sgmltag class="endtag">trademark</sgmltag>
		</para>
	      </listitem>
	      <listitem>
	      <para><sgmltag class="starttag">trademark
	      class="copyright"</sgmltag>copyright symbol after
	      me<sgmltag class="endtag">trademark</sgmltag></para>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Content inside <sgmltag>para</sgmltag> tags</term>
	  <listitem>
	    <para>In general, use <sgmltag>para</sgmltag> tags
	    around anything other than a simple paragraph. Doing so will
	    create additional white space within the text itself in the
	    PDF version.
	    </para>
	    <para>Specifically, do not use <sgmltag>para</sgmltag> tags
	    around the following (or, to put this another way, do not
	    embed the following within <sgmltag
	      class="element">para</sgmltag> elements):
	    </para>
	    <itemizedlist>
	      <listitem>
	      <para><sgmltag class="element">screen</sgmltag></para>
	      </listitem>
	      <listitem>
	      <para><sgmltag class="element">itemizedlist</sgmltag></para>
	      </listitem>
	      <listitem>
	      <para><sgmltag class="element">orderedlist</sgmltag></para>
	      </listitem>
	      <listitem>
	      <para><sgmltag class="element">variablelist</sgmltag></para>
	      </listitem>
	      <listitem>
	      <para><sgmltag class="element">table</sgmltag></para>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Content inside <sgmltag class="element">para</sgmltag> elements within
	  <sgmltag>listitem</sgmltag> tags</term>
	  <listitem>
	    <para>Content inside <sgmltag class="element">para</sgmltag>
	    elements within <sgmltag class="element">listitem</sgmltag>
	    elements <emphasis>must</emphasis> start immediately after
	    the beginning <sgmltag class="starttag">para</sgmltag> tag
	    to avoid extra white space in the PDF version.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Content inside <sgmltag>screen</sgmltag> tags</term>
	  <listitem>
	    <para>The content inside <sgmltag>screen</sgmltag> tags
	    (<sgmltag class="starttag">screen</sgmltag> and <sgmltag
	    class="endtag">screen</sgmltag>)
	    <emphasis>must</emphasis> be flush left in the XML file;
	    otherwise, the extraneous whitespace will appear in the HTML
	    version.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>

  </section>
  
  <section id="sn-xml-guidelines-header">
    <title>File Header</title>

    <para>All the files must contain the CVS Id header. If you create a
      new file, the first line must be:</para>

    <screen><![CDATA[<!-- $Id: -->]]></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: writing-guidelines.xml,v 1.4 2007/02/05 00:33:47 pfrields Exp $ -->]]></screen>

  </section>

  <section id="sn-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.  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>
      
    <section id="sn-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><![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><![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>
    </section>

  </section>

  <section id="sn-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>
	  <!-- This section is dropped, right?  [PWF] -->
<!--
	  <para>For more information about calling the images from the
	    XML, refer to <xref linkend="sn-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>
	  <!-- This section is dropped, right?  [PWF] -->
<!--
	  <para>For more information about using screen, refer to <xref
	      linkend="sn-xml-tags-screen"/>.</para>
-->
	</listitem>
      </varlistentry>
    </variablelist>
  </section>

<!-- 
  <section id="sn-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>

    </section>	
-->

</chapter>

<!--
Local variables:
mode: xml
fill-column: 72
End:
-->