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</link></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.)
