/
documentation-guidelines.txt
200 lines (152 loc) · 7.42 KB
/
documentation-guidelines.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
Drools Documentation Authoring Guideline and Cheat Sheet
========================================================
External documentation
----------------------
JBoss Documentation Guide: http://jboss.org/pressgang/jdg.html (a must read from chapter 6: Structure guidelines)
JDocBook plugin: http://docs.jboss.org/docbook/userguide/html_single/index.html
DocBook: http://www.sagehill.net/docbookxsl/
http://www.docbook.org/tdg5/en/html/docbook.html
Marking words in a paragraph
----------------------------
* Use <code> for package names, class names, method names, ...:
the class <code>JavaDialectConfiguration</code>
the package <code>drools.dialect.java.compiler</code>
the method <code>toString()</code>
* Use <filename> for directories and files:
the directory <filename>drools-docs/target/</filename>
the file <filename>pom.xml</filename>
* Use <command> for commands:
run the command <command>mvn clean install</command>
* Use <literal> for literals and keywords:
the value <literal>null</literal>
the keyword <literal>not</literal>
* Use <emphasis> to emphasis something (turns bold).
Note that you can use <emphasis> on <literal>, etc:
<emphasis><literal>null</literal></emphasis>
Marking paragraphs
------------------
* You can encapsulate a paragraph or more in note, warning, etc:
<note><para></para></note>
<warning><para></para></warning>
<important><para></para></important>
Always use one or more <para>'s (or other elements) inside it,
never write text directly (which gives visual bugs).
Note: the JBoss Documentation Guide disallow the use of <caution> and <tip>
* Use <programlisting> for longer code, commands or log listings:
<programlisting><![CDATA[public interface Move ...]]></programlisting>
Do not use <programlisting> inside <para> as it is a paragraph style
(which gives code coloring bugs).
* Use <programlisting language="java"> for java code to get color highlighting.
* Use <programlisting language="xml"> for XML code to get color highlighting.
* Use <example> with <programlisting> for example code:
<example>
<title>Configuring the <code>JavaDialectConfiguration</code> to use JANINO via a setter</title>
<programlisting><![CDATA[PackageBuilderConfiguration cfg = new PackageBuilderConfiguration( );
JavaDialectConfiguration javaConf = (JavaDialectConfiguration) cfg.getDialectConfiguration( "java" );
javaConf.setCompiler( JavaDialectConfiguration.JANINO );]]></programlisting>
</example>
Images
------
* Please link svg image files instead of png bitmaps in the text whenever
possible.
* Please avoid using .bmp bitmaps, since it will bloat size of the end
doc. To convert your bmp to a png images, use the GIMP, paint or the command "ffmpeg -i x.bmp x.png".
Better yet, use a vector graphic program such as InkScape to make a true svg image.
But this approach may take time and effort, recommended for processing diagrams but not for screenshots.
* At the head of a docbook file, the xml:base property should be set to
the relative path to the translation base directory ("en-US").
For example: a file under "en-US/Chapter-Introduction/" has xml:base="../"
while a file under "en-US/Chapter-Introduction/Section-WhatIs/" has xml:base="../../"
If it is not set correctly, the images won't show up in a visual docbook editor like XmlMind.
There is one exception: any file that use xinclude to include other files usually have a xml:base="./"
and it should not contain images.
* Use <mediaobject> with <imageobject> to show an image.
* Use <figure> for diagrams with a title:
<figure>
<title>High-level View of a Rule Engine</title>
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/Chapter-Rule_Engine/rule-engine-inkscape.svg"
format="SVG" contentwidth="540px" contentdepth="300px" />
</imageobject>
</mediaobject>
</figure>
* For HTML, width="100%" ensures that imagedata is scaled down to the
current width of the browser's window.
Linking syntax in DocBook 5.0+:
-------------------------------
http://www.sagehill.net/docbookxsl/Db5Tools.html#Db5UnivLinking
Note: The jboss docbook xsl does not support docbook 5.0 syntax yet,
so please use the docbook 4.5 linking syntax for the links.
Lists
-----
* unnumbered list (bullets):
<itemizedlist>
<listitem> <para>Linear</para> </listitem>
...
</itemizedlist>
* numbered list:
<orderedlist>
<listitem> <para> Initialize the .... </para> </listitem>
...
</orderedlist>
* Inside a <listitem>, always use a <para> (or another element)
Indexed terms:
-------------
<para>Drools implements and extends the
<indexterm><primary>Rete</primary></indexterm> Rete algorithm,
<indexterm><primary>Leaps</primary></indexterm> ...</para>
Citations:
---------
<para>To quote a Drools mailing list regular:
<blockquote>
<attribution>Dave Hamu</attribution>
<para>It seems to me
that in the excitement of working with rules engines, that people forget
that a rules engine is only one piece of a complex application or
solution. Rules engines are not really intended to handle workflow or
process executions nor are workflow engines or process management tools
designed to do rules. Use the right tool for the job. Sure, a pair of
pliers can be used as a hammering tool in a pinch, but that's not what
it's designed for.</para>
</blockquote>
</para>
You can see the effect of the above example code here:
https://hudson.jboss.org/hudson/job/drools/lastSuccessfulBuild/artifact/trunk/target/docs/drools-expert/html/ch01.html#d0e231
Show source of reference:
-------------------------
<para>The term "Production Rule" originates from formal grammar - where it
is described as "an abstract structure that describes a formal language
precisely, i.e., a set of rules that mathematically delineates a (usually
infinite) set of finite-length strings over a (usually finite) alphabet"
(<citetitle><link xlink:href="http://en.wikipedia.org/wiki/Formal_grammar">Wikipedia</ulink></citetitle>).
</para>
You can see the the effect of the above example code here:
https://hudson.jboss.org/hudson/job/drools/lastSuccessfulBuild/artifact/trunk/target/docs/drools-expert/html/ch01.html#d0e41
You can of course combine the <blockquote>, <link> and <citetitle> together.
Footnotes:
----------
TODO
Callouts:
---------
TODO
======================================
I guess the "reference section" would be somehow like a bibliography
section in a book or paper. Here is the information I found for
bibliography markup:
http://www.docbook.org/tdg5/en/html/bibliography.html
But I'm not sure whether it is working with the JBoss customized XSLT
and CSS. If it looks too complex for you, just don't waste your time
and I'll try it out later and add the relevant information to the
cheatsheet.
For the "Definition/Concept", I found the <termdef> tag that might be
what you want:
http://www.docbook.org/tdg5/en/html/termdef.html
The example in the page looks not that complex. You can give it a try.
Be warned I've not tested it yet (have much to do in the office for
now), if this markup breaks the build, please let me know. (If it does
not break the build, but you do not see any obvious visual effect,
that means this tag is not defined the css. This is small problem and
you can keep using the markup. I'm into CSS these days and will sooner
or later update the Drools css for documentation.)