documentation-guide/en_US writing-guidelines.xml,1.2,1.3
Karsten Wade (kwade)
fedora-docs-commits at redhat.com
Sun Feb 4 13:57:25 UTC 2007
Author: kwade
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv13936
Modified Files:
writing-guidelines.xml
Log Message:
the latest stuff I did :)
Index: writing-guidelines.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/writing-guidelines.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- writing-guidelines.xml 3 Feb 2007 22:29:37 -0000 1.2
+++ writing-guidelines.xml 4 Feb 2007 13:57:23 -0000 1.3
@@ -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>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>Keep it as short and simple as possible.</para>
- <table id="tb-xml-namingconventions">
- <title>Naming Conventions</title>
+ <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-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">
@@ -224,7 +301,7 @@
<tertiary>note</tertiary>
</indexterm>
- <indexterm>
+ <Indexterm>
<primary>XML tags</primary>
<secondary>admonitions</secondary>
<tertiary>caution</tertiary>
More information about the docs-commits
mailing list