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-writing-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-xml-guidelines-header">
    <title>File Header</title>
    <section id="sn-xml-header-xml">
      <title>XML Header</title>
      <para>In accordance with good XML practices, the first line in any
	DocBook XML source files should identify the file as XML.  Use
	the following line as the first line of any new XML file:</para>
      <screen><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></screen>
    </section>
    <section id="sn-xml-header-cvs">
      <title>CVS Id Header</title>
      <para>All the files must contain the CVS Id header. Use the
      following line as the second line of any new XML file:</para>
      <screen><![CDATA[<!-- $Id: -->]]></screen>
      <para>Any time the file 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.11 2007/09/16 19:12:38 pfrields Exp $ -->]]></screen>
    </section>
  </section>
  <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.  IDs are
      unique identifiers that allow DocBook XML to cross-reference a
      section, chapter, or other element.</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>The following general rules apply to IDs:</para>

    <itemizedlist>
      <listitem>
	<para>Keep an ID as short and simple as possible.</para>
      </listitem>
      <listitem>
	<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>
      </listitem>
    </itemizedlist>

    <para>
      <xref linkend="ex-id-usage"/> demonstrates some example ID
      attributes used properly.
    </para>

    <example id="ex-id-usage">
      <title>Proper ID Usage</title>
    <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">

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

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

    <segmentedlist id="sg-id-two-char-naming-conventions">
      <title>Two-Character Naming Conventions</title>
      <segtitle>Tag</segtitle>
      <segtitle>Prefix</segtitle>
      <seglistitem>
	<seg><sgmltag class="element">preface</sgmltag></seg>
	<seg><literal>pr-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">chapter</sgmltag></seg>
	<seg><literal>ch-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">section</sgmltag></seg>
	<seg><literal>sn-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">figure</sgmltag></seg>
	<seg><literal>fig-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">table</sgmltag></seg>
	<seg><literal>tb-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">appendix</sgmltag></seg>
	<seg><literal>ap-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">part</sgmltag></seg>
	<seg><literal>pt-</literal></seg>
      </seglistitem>
      <seglistitem>
	<seg><sgmltag class="element">example</sgmltag></seg>
	<seg><literal>ex-</literal></seg>
      </seglistitem>
    </segmentedlist>

    <para>Use the title of the item as the ID.  Make your titles unique
      within a document to prevent conflicts.  For example:</para>    
    
    <screen><![CDATA[<chapter id="ch-how-to-fold-laundry">
  <title>How To Fold Laundry</title>
  <section id="sn-folding-shirts">
    <title>Folding Shirts</title>]]></screen>
  </section>
  <section id="sn-xml-tags">
    <title>XML Tags</title>
      <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>
	  <segmentedlist>
	    <segtitle>DocBook XML source</segtitle>
	    <segtitle>Rendered content</segtitle>
	    <seglistitem>
	      <seg><code><![CDATA[<trademark>trademark symbol after
		  me</trademark>]]></code></seg>
	      <seg><trademark>trademark symbol after
		  me</trademark></seg>
	    </seglistitem>
	    <seglistitem>
	      <seg><code><![CDATA[<trademark
		  class="registered">registered trademark symbol after
		  me</trademark>]]></code></seg>
	      <seg><trademark class="registered">registered trademark
		  symbol after me</trademark></seg>
	    </seglistitem>
	    <seglistitem>
	      <seg><code><![CDATA[<trademark class="copyright">copyright
		  symbol after me</trademark>]]></code></seg>
	      <seg><trademark class="copyright">copyright symbol after
		  me</trademark></seg>
	    </seglistitem>
	  </segmentedlist>
	</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-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: <sgmltag
	class="element">caution</sgmltag>, <sgmltag
	class="element">important</sgmltag>, <sgmltag
	class="element">note</sgmltag>, <sgmltag
	class="element">tip</sgmltag>, and <sgmltag
	class="element">warning</sgmltag>.  All of the admonitions have
      the same structure: an optional <sgmltag
	class="element">title</sgmltag> 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 a <sgmltag class="element">warning</sgmltag> is
      reserved for cases where bodily harm can result.</para>
      
    <section id="sn-xml-notesetc">
      <title>Creating a <sgmltag class="element">note</sgmltag>,
	<sgmltag class="element">tip</sgmltag>, <sgmltag
	  class="element">caution</sgmltag>, <sgmltag
	  class="element">important</sgmltag>, or <sgmltag
	  class="element">warning</sgmltag></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><sgmltag
	    class="element">note</sgmltag></emphasis> is used to bring
	additional information to the users' attention. A
	<emphasis><sgmltag class="element">tip</sgmltag></emphasis> is
	used to show the user helpful information or another way to do
	something. A <emphasis><sgmltag
	    class="element">caution</sgmltag></emphasis> is used to show
	the user they must be careful when attempting a certain step. An
	<emphasis><sgmltag
	    class="element">important</sgmltag></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><sgmltag
	    class="element">warning</sgmltag></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 show the basic setup for each
	case mentioned above, along with its appearance in 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>Screenshots are illustrations that show the state of a display
      the user may encounter.  Screenshots can be either graphical or
      textual.  However, screenshots use a great deal of space in a text
      document to convey relatively small amounts of information.  The
      same space in the document can hold a greater amount of more
      descriptive and helpful information.  Therefore, authors should
      avoid screenshots whenever possible in favor of descriptive
      text.</para>
    <para>One of the isolated instances in which screenshots are useful
      is to demonstrate a physical screen layout that is unfamiliar to a
      reader.  <emphasis>This does not mean that illustrations of dialog
	boxes are good uses of screenshots.</emphasis>  On the contrary,
      dialogs are simply instances of a user interface element with
      which a reader is already familiar.  An annotated diagram in
      certain cases, however, explains to the reader where to find
      functional landmarks on the screen such as menu bars.</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>Create a new user account to make screenshots.  The
		new account uses the distribution default theme, fonts,
		and element sizes.  The resulting screenshot has an
		appearance familiar to the largest number of readers,
		and makes &FDP; documents consistent.</para>
	    </step>
	    <step>
	      <para>Before taking the screenshot, if possible, resize
		the targeted GUI element(s) to the smallest possible
		size.  The target image should be 500 pixels wide or
		less.  If the screenshot includes 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
		the mouse to bring it to the forefront, or otherwise
		arrange 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 the shot includes
		multiple elements grouped closely together, crop the
		resulting PNG format image in <application>The
		  GIMP</application>.</para>
	      </step>
	      <step>
		<para>If necessary, resize the image using
		<application>The GIMP</application>.  Open the image,
		then right-click on it and choose
		<menuchoice>
		  <guimenu>Image</guimenu>
		  <guimenuitem>Scale Image...</guimenuitem>
		</menuchoice>.  With the chain symbol intact, set the
		<guilabel>New Width</guilabel> to <guilabel>500
		  px</guilabel>, and click <guibutton>OK</guibutton>.
		Choose <menuchoice>
		  <guimenu>File</guimenu>
		  <guimenuitem>Save</guimenuitem>
		</menuchoice> to save changes to the image before
		converting it.</para>
	    </step>
	    <step>
	      <para>
		With the image open in <application>The
		  GIMP</application>, right-click the image, and select
		<menuchoice>
		  <guimenu>File</guimenu>
		  <guimenuitem>Save As...</guimenuitem>
		</menuchoice>.  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>A <guilabel>Save as PostScript</guilabel> window
		appears.  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.
	    Follow these guidelines for textual screenshots:</para>
	  <itemizedlist>
	    <listitem>
	      <para>If a graphical screenshot illustrates a function,
		and the textual mode has identical functions, do not
		include both, unless omitting either would make your
		description unclear.</para>
	    </listitem>
	    <listitem>
	      <para>Make the information generic over specific, and omit
		any username and machine information if possible. Do not
		include the shell prompt unless it is vital to the
		demonstration.</para>
	    </listitem>
	    <listitem>
	      <para>Separate what the user types from sample command
		output.</para>
	    </listitem>
	    <listitem>
	      <para>When using <sgmltag class="element">screen</sgmltag>
		to demonstrate a procedure, use <sgmltag
		  class="element">userinput</sgmltag> tags to show what
		the user types, and use <sgmltag
		  class="element">computeroutput</sgmltag> tags to show
		the resulting output.</para>
	    </listitem>
	  </itemizedlist>
	  <para>
	    <xref linkend="ex-text-screenshot-good"/> is an example of
	    textual screenshot usage.
	  </para>
	  <example id="ex-text-screenshot-good">
	    <title>Correct Textual Screenshot (XML Source and
	      HTML)</title>
	    <screen><![CDATA[<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><userinput>ps ax | grep ssh</userinput></screen>
  <para>Output appears similar to the following:</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>]]></screen>
	    <para>To find all the currently active ssh sessions, execute the
		following command:</para>
	    <screen><userinput>ps ax | grep ssh</userinput></screen>

	    <para>Output appears similar to the following:</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>	
-->

  <section id="sn-live-previews">
    <title>Previewing Your Work</title>
    <para>The GNOME <application>Help</application> browser, also known
      as <command>yelp</command>, and the KDE
      <application>Khelp</application> documentation browser can render
      DocBook XML information as needed.  Use these applications to
      preview your work if you prefer reading your work in a
      browser-like environment.  Run the following command:</para>
    <screen><![CDATA[yelp file:///path/to/parent-file.xml]]></screen>
    <para>Make sure to point the preferred help browser at the top
      parent file of your XML document.  Once the document loads, you
      can add a bookmark for it for ease of use later.</para>
    <tip>
      <title>Using Bookmarks</title>
      <para>Keeping your documents in the same place for every checkout
	session makes help browser bookmarks more effective.</para>
    </tip>
    <para>Once you have a bookmark stored, it will appear in the help
      browser at every use.  You can now hit <keycap>F1</keycap> during
      any GUI session to launch the help browser.  Then choose your
      bookmark from the menu to preview your document at any
      time.</para>
  </section>
</chapter>

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