Drools Documentation Authoring Guideline and Cheat Sheet
========================================================

Guideline
=========
* please markup all package names, class names, method names, etc. with 
  <code></code>.
  
  example:
    <para>The <code>JavaDialectConfiguration</code> allows the compiler
     and language levels to be supported. You can override by setting the
    <code>drools.dialect.java.compiler</code> property in a 
    <code>packagebuilder.conf</code> file that the 
    <code>ChainedProperties</code> instance will find, or you can do it 
    at runtime as shown below.</para>

* keywords may be enclosed in <kw></kw>, rendered in boldface Courier

* 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. Use any image processing program such as GIMP to convert your bmp 
  images to png images first. Better yet, use any vector graphic program
  such as InkScape to scan your bmp image and make a true svg image out
  of it. But this approach may take time and effort, recommanded for 
  processing diagrams but not screenshots.
  

Cheat Sheet
===========

Text boxes implemented in the jboss docbook styles:
---------------------------------------------------
* <caution><para></para></caution>
* <important><para></para></important>
* <note><para></para></note>
* <tip><para></para></tip>
* <warning><para></para></warning>

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. 

Markup program list or console output:
--------------------------------------

* as Example:

    <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>

* Simple (not as Example):

  <programlisting ><![CDATA[ your code here...  ]]></programlisting>
  

Link image files:
-----------------

* suitable for diagrams:

  <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.


* suitable for screenshots:

  TODO


Lists
-----

* unnumbered list (bullets):

    <itemizedlist>
      <listitem> <para>Linear</para> </listitem>
      ...
    </itemizedlist>

* numbered list:
    <orderedlist>
      <listitem> <para> Initialize the .... </para> </listitem>
      ...
    </orderedlist>
  

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"
    (<ulink url="http://en.wikipedia.org/wiki/Formal_grammar">
    <citetitle>wikipedia</citetitle>
    </ulink>).
</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>, <ulink> 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.)
