User: vlada
Date: 01/03/28 14:09:55
Modified: src/docs preface.xml
Log:
some initial guidelines, will add more soon
Revision Changes Path
1.3 +56 -0 manual/src/docs/preface.xml
Index: preface.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/preface.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- preface.xml 2001/03/21 08:30:20 1.2
+++ preface.xml 2001/03/28 22:09:55 1.3
@@ -29,4 +29,60 @@
<citetitle>here</citetitle>
</ulink>
</para>
+ <formalpara>
+ <title>Docbook documentation guidelines</title>
+ <para>
+ <itemizedlist>
+ <listitem><para>Format for readability and content, not for a formated
document.</para>
+ <para>It is not your job and responsibility to make sure the final
documentation looks good. If you use appropriate markup
+ tags for the content of your documentation, Docbook will ensure that
your document looks good. Do not substitute an inappropriate
+ DocBook XML tag because you do not like the "look" of the correct
tag.</para>
+
+ </listitem>
+
+ <listitem>
+ <para>Do what you can to ensure you turn in a valid DocBook
file.</para>
+
+ <para>If you notice any parser errors during documentation
build, correct them to ensure XML validity. If you get absolutely stuck notify
+ one of the documentation leads. The reviewers will correct any DocBook
errors you create, but please try to reduce the number of errors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>All <![CDATA[<chapter> and major <section> ]]> tags must have
an id attribute. The id must be all lower case, with dashes seperating
+ words: <![CDATA[ <section id="configuring-containerinvoker"> ]]>
+ </para>
+
+ <para>This is very important since it allows other documentation
writers to refer to your chapters and sections</para>
+ </listitem>
+ <listitem>
+ <para>
+ When trying to decide between an ordered and unordered list,
simply ask yourself the following question: "Does the order of the
+ listed items matter?" or "If I change the order of the listed items,
does that change the meaning of the list?". If you answer "No"
+ to either question, then an unordered list is likely the logical
choice.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When referring to chapters, sections, code samples, figures and other
parts of documentation use either <![CDATA[<link> or <xref>]]>
+ element. </para>
+
+ <para><![CDATA[<xref> ]]> element is more powerful since it creates
both link and link text. You should use it whenever possible.</para>
+ <para>For example: If there is a figure somewhere in the documentation
<![CDATA[<figure id="comp.ejb-jar.xml">]]> then using
+ <![CDATA[<xref linkend="comp.ejb-jar.xml"/>]]> creates both the link
to that figure as well as link text. Link text is usually
+ autogenerated (in case of figures - figure number) or assigned by the
author of that link target.</para>
+
+ <para><![CDATA[<link>]]> element also creates links, but you assign
link text. For example:
+ <![CDATA[<link linkend="jca-terminology">JCA
Terminology</link>]]></para>
+
+ </listitem>
+
+ <listitem>
+ <para>Use <![CDATA[<ulink>]]> element to create links to other URLs.
For example:
+ <![CDATA[<ulink
url="http://java.sun.com/j2se/1.3/docs/guide/rmi/rmisocketfactory.doc.html">The Custom
Socket Factory Tutorial</ulink>]]>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
</preface>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
