diff options
Diffstat (limited to 'en_US/writing-guidelines.xml')
| -rw-r--r-- | en_US/writing-guidelines.xml | 535 |
1 files changed, 535 insertions, 0 deletions
diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml new file mode 100644 index 0000000..64f2736 --- /dev/null +++ b/en_US/writing-guidelines.xml @@ -0,0 +1,535 @@ +<!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>&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><![CDATA[<chapter id="ch-uniquename"> + +<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 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>naming conventions</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> + + <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> (13 + characters) and <command>"sn-install-make-disks"</command> (21 + characters).</para> + + <para>A section within a particular chapter always uses the chapter + name (minus the <command>"ch-"</command>) in its ID. For example, + you are working with the <command>"ch-intro"</command> chapter and + need to create your first section on disk partitions. That section + ID would look similar to <command>"s1-intro-partition"</command> + which contains the section number, the main chapter ID, and a + unique ID for that section.</para> + + <table id="tb-xml-namingconventions"> + <title>Naming Conventions</title> + + <tgroup cols="2"> + <colspec colnum="1" colname="tag" colwidth="100"/> + <colspec colnum="2" colname="prefix" colwidth="100"/> + <thead> + <row> + <entry>Tag</entry> + <entry>Prefix</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preface</command></entry> + <entry><computeroutput>pr-</computeroutput></entry> + </row> + <row> + <entry><command>chapter</command></entry> + <entry><computeroutput>ch-</computeroutput></entry> + </row> + <row> + <entry><command>section</command></entry> + <entry><computeroutput>sn-</computeroutput></entry> + </row> + <row> + <entry><command>sect1</command></entry> + <entry><computeroutput>s1-</computeroutput></entry> + </row> + <row> + <entry><command>sect2</command></entry> + <entry><computeroutput>s2-</computeroutput></entry> + </row> + <row> + <entry><command>sect3</command></entry> + <entry><computeroutput>s3-</computeroutput></entry> + </row> + <row> + <entry><command>sect4</command></entry> + <entry><computeroutput>s4-</computeroutput></entry> + </row> + <row> + <entry><command>figure</command></entry> + <entry><computeroutput>fig-</computeroutput></entry> + </row> + <row> + <entry><command>table</command></entry> + <entry><computeroutput>tb-</computeroutput></entry> + </row> + <row> + <entry><command>appendix</command></entry> + <entry><computeroutput>ap-</computeroutput></entry> + </row> + <row> + <entry><command>part</command></entry> + <entry><computeroutput>pt-</computeroutput></entry> + </row> + <row> + <entry><command>example</command></entry> + <entry><computeroutput>ex-</computeroutput></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-xml-guidelines-header"> + <title>File Header</title> + + <para>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.1 2007/02/03 22:21:58 kwade Exp $ -->]]></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. 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><![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> + </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> -> <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 + 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> + +<!-- +Local variables: +mode: xml +fill-column: 72 +End: +--> |