documentation-guide/en_US writing-guidelines.xml,1.3,1.4
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Mon Feb 5 00:33:50 UTC 2007
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv31551
Modified Files:
writing-guidelines.xml
Log Message:
Retagged some elements to make things more DocBooky. Use sgmltag to
advantage, cool!
Index: writing-guidelines.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/writing-guidelines.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- writing-guidelines.xml 4 Feb 2007 13:57:23 -0000 1.3
+++ writing-guidelines.xml 5 Feb 2007 00:33:47 -0000 1.4
@@ -17,7 +17,7 @@
<indexterm>
<primary>RTFM</primary>
- <secondary>read the f*'ing manual</secondary>
+ <secondary>read the fine manual</secondary>
<seealso>humor</seealso>
</indexterm>
@@ -30,9 +30,8 @@
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:</para>
- <para>
- <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</ulink>
+ 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">
@@ -57,7 +56,7 @@
<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
+ to cross-reference a section, chapter, or other element. The
following general rules apply to IDs:</para>
<indexterm>
@@ -74,7 +73,7 @@
<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>
+ self-identifying the XML container type.</para>
<table id="tb-id-two-char-naming-conventions">
<title>Two-Character Naming Conventions</title>
@@ -90,36 +89,36 @@
</thead>
<tbody>
<row>
- <entry><command>preface</command></entry>
- <entry><computeroutput>pr-</computeroutput></entry>
+ <entry><sgmltag class="element">preface</sgmltag></entry>
+ <entry><literal>pr-</literal></entry>
</row>
<row>
- <entry><command>chapter</command></entry>
- <entry><computeroutput>ch-</computeroutput></entry>
+ <entry><sgmltag class="element">chapter</sgmltag></entry>
+ <entry><literal>ch-</literal></entry>
</row>
<row>
- <entry><command>section</command></entry>
- <entry><computeroutput>sn-</computeroutput></entry>
+ <entry><sgmltag class="element">section</sgmltag></entry>
+ <entry><literal>sn-</literal></entry>
</row>
<row>
- <entry><command>figure</command></entry>
- <entry><computeroutput>fig-</computeroutput></entry>
+ <entry><sgmltag class="element">figure</sgmltag></entry>
+ <entry><literal>fig-</literal></entry>
</row>
<row>
- <entry><command>table</command></entry>
- <entry><computeroutput>tb-</computeroutput></entry>
+ <entry><sgmltag class="element">table</sgmltag></entry>
+ <entry><literal>tb-</literal></entry>
</row>
<row>
- <entry><command>appendix</command></entry>
- <entry><computeroutput>ap-</computeroutput></entry>
+ <entry><sgmltag class="element">appendix</sgmltag></entry>
+ <entry><literal>ap-</literal></entry>
</row>
<row>
- <entry><command>part</command></entry>
- <entry><computeroutput>pt-</computeroutput></entry>
+ <entry><sgmltag class="element">part</sgmltag></entry>
+ <entry><literal>pt-</literal></entry>
</row>
<row>
- <entry><command>example</command></entry>
- <entry><computeroutput>ex-</computeroutput></entry>
+ <entry><sgmltag class="element">example</sgmltag></entry>
+ <entry><literal>ex-</literal></entry>
</row>
</tbody>
</tgroup>
@@ -152,79 +151,87 @@
<varlistentry>
<term>Do Not Use Trademark Entities</term>
<listitem>
- <para>Do not use the trademark entities ™, ©, or
- ® 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>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 <command>trademark</command> tag and its
+ <para>Instead, use the <sgmltag>trademark</sgmltag> tag and its
associates classes as follows:
</para>
<itemizedlist>
<listitem>
- <para><trademark>trademark symbol after me</trademark>
+ <para><sgmltag
+ class="starttag">trademark</sgmltag>trademark symbol after
+ me<sgmltag class="endtag">trademark</sgmltag>
</para>
</listitem>
<listitem>
- <para><trademark class="registered">registered trademark symbol after me</trademark>
+ <para><sgmltag class="starttag">trademark
+ class="registered"</sgmltag>registered trademark symbol
+ after me<sgmltag class="endtag">trademark</sgmltag>
</para>
</listitem>
<listitem>
- <para><trademark class="copyright">copyright symbol after me</trademark></para>
+ <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 <command>para</command> tags</term>
+ <term>Content inside <sgmltag>para</sgmltag> tags</term>
<listitem>
- <para>In general, use <command>para</command> tags
+ <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 <command>para</command> tags around
- the following (or, to put this another way, do not embed the
- following within <command>para</command> tags):
+ <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><screen></para>
+ <para><sgmltag class="element">screen</sgmltag></para>
</listitem>
<listitem>
- <para><itemizedlist></para>
+ <para><sgmltag class="element">itemizedlist</sgmltag></para>
</listitem>
<listitem>
- <para><orderedlist></para>
+ <para><sgmltag class="element">orderedlist</sgmltag></para>
</listitem>
<listitem>
- <para><variablelist></para>
+ <para><sgmltag class="element">variablelist</sgmltag></para>
</listitem>
<listitem>
- <para><table></para>
+ <para><sgmltag class="element">table</sgmltag></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>
+ <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 <command>screen</command> tags</term>
+ <term>Content inside <sgmltag>screen</sgmltag> tags</term>
<listitem>
- <para>The content inside <command>screen</command> tags
- (<screen> and </screen>)
+ <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.
@@ -301,7 +308,7 @@
<tertiary>note</tertiary>
</indexterm>
- <Indexterm>
+ <indexterm>
<primary>XML tags</primary>
<secondary>admonitions</secondary>
<tertiary>caution</tertiary>
@@ -529,8 +536,11 @@
<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>
@@ -576,8 +586,11 @@
8032 pts/0 S 0:00 ssh user at host.example.com
8032 pts/1 S 0:00 ssh root at 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>
More information about the Fedora-docs-commits
mailing list