diff options
Diffstat (limited to 'en_US')
-rw-r--r-- | en_US/writing-guidelines.xml | 177 |
1 files changed, 127 insertions, 50 deletions
diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml index 32ed5aa..c791274 100644 --- a/en_US/writing-guidelines.xml +++ b/en_US/writing-guidelines.xml @@ -8,7 +8,7 @@ ]> <chapter id="ch-rh-guidelines"> - <title>&RH; Documentation Guidelines</title> + <title>&FED; Documentation Guidelines</title> <indexterm> <primary>recursion</primary> @@ -29,7 +29,13 @@ <para>Please read this chapter carefully. This chapter describes the guidelines that must be followed such as naming conventions.</para> - <section id="sn-xml-guidelines-naming"> + <para>This chapter only discusses tags used for documentation for the &PROJECT;, + not all available DocBook XML tags. For the complete list, refer to:</para> + <para> + <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</ulink> + </para> + + <section id="sn-id-naming-conventions"> <title>ID Naming Conventions</title> <indexterm> @@ -41,11 +47,10 @@ <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 + <para>This section explains the ID naming convention. For example:</para> - <screen><![CDATA[<chapter id="ch-uniquename"> + <screen><![CDATA[<chapter id="ch-unique-name-of-chapter"> <section id="sn-install-make-disks"> @@ -64,35 +69,15 @@ <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>Keep it as short and simple as possible.</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>"sn-intro-partition"</command> - which contains the section number, the main chapter ID, and a - unique ID for that section.</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 what the XML container type is.</para> - <table id="tb-xml-namingconventions"> - <title>Naming Conventions</title> + <table id="tb-id-two-char-naming-conventions"> + <title>Two-Character Naming Conventions</title> <tgroup cols="2"> <colspec colnum="1" colname="tag" colwidth="100"/> @@ -117,22 +102,6 @@ <entry><computeroutput>sn-</computeroutput></entry> </row> <row> - <entry><command>section</command></entry> - <entry><computeroutput>sn-</computeroutput></entry> - </row> - <row> - <entry><command>section</command></entry> - <entry><computeroutput>sn-</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> @@ -156,6 +125,114 @@ </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 &trade;, &copy;, or + &reg; 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 <command>trademark</command> tag and its + associates classes as follows: + </para> + <itemizedlist> + <listitem> + <para><trademark>trademark symbol after me</trademark> + </para> + </listitem> + <listitem> + <para><trademark class="registered">registered trademark symbol after me</trademark> + </para> + </listitem> + <listitem> + <para><trademark class="copyright">copyright symbol after me</trademark></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>para</command> tags</term> + <listitem> + <para>In general, use <command>para</command> 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 <command>para</command> tags around + the following (or, to put this another way, do not embed the + following within <command>para</command> tags): + </para> + <itemizedlist> + <listitem> + <para><screen></para> + </listitem> + <listitem> + <para><itemizedlist></para> + </listitem> + <listitem> + <para><orderedlist></para> + </listitem> + <listitem> + <para><variablelist></para> + </listitem> + <listitem> + <para><table></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>para</command> tags within + <command>listitem</command> tags</term> + <listitem> <sect id="sn-xml-tags-caveats"> + <title>Tags and Entities Caveats</title> + + + <para>Content inside <command>para</command> tags within + <command>listitem</command> tags <emphasis>must</emphasis> start + immediately after the beginning <para> tag to avoid extra + white space in the PDF version. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>screen</command> tags</term> + <listitem> + <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> + </variablelist> + </section> <section id="sn-xml-guidelines-header"> @@ -170,7 +247,7 @@ 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.2 2007/02/03 22:29:37 kwade Exp $ -->]]></screen> + <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.3 2007/02/04 13:57:23 kwade Exp $ -->]]></screen> </section> @@ -224,7 +301,7 @@ <tertiary>note</tertiary> </indexterm> - <indexterm> + <Indexterm> <primary>XML tags</primary> <secondary>admonitions</secondary> <tertiary>caution</tertiary> |