How to write ProActive documentation

The main tags/structures you should be using are:

	Note
	BUT, you should always be using the XXE icons. They have all you need (except for EXAMPLE/SCREEN)! You can also cut n paste!

This is the figure example. Please use the TITLE tag

Figure 38.1. A Drawing using the FIGURE tag

Use ITEMIZEDLIST followed by as many 'LISTITEM's as you want!

Code sources should be written between PROGRAMLISTING tags (possiblibly lang="java" or "xml" ). You don't have to write valid code, as the highlighting (done by LanguageToDocBook classes) is based on regular expression replacement, and not on language grammars. If you want to show some program output, you can use SCREEN instead of PROGRAMLISTING. In any case, watch out, because spaces count (and produce your own indentation)! You can also use the EXAMPLE TAG around your PROGRAMLISTING or SCREEN tags, to give a title, and be referenced in the table of examples.

You can also insert directly sources from their original files, or type the code in the docbook. When you are typing the code inside the docbook file, you can even highlight yourself some bits of the code you want to emphasis. This is shown in the last example. But beware, as you are inside docbook you have to escape the "&" and the "<" signs. If you don't want to, hide everything in a CDATA block.

Within normal text, for instance in a paragraph, you can also just use the LITERAL tag to highlight the main methods.

package org.objectweb.proactive.examples.hello;

import org.apache.log4j.Logger;
import org.objectweb.proactive.api.PAActiveObject;
import org.objectweb.proactive.api.PALifeCycle;
import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.core.util.log.Loggers;
import org.objectweb.proactive.core.util.log.ProActiveLogger;
import org.objectweb.proactive.core.util.wrapper.StringMutableWrapper;


/** A stripped-down Active Object example.
 * The object has only one public method, sayHello()
 * The object does nothing but reflect the host its on. */
public class TinyHello implements java.io.Serializable {
    static Logger logger = ProActiveLogger.getLogger(Loggers.EXAMPLES);
    private final String message = "Hello World!";

    /** ProActive compulsory no-args constructor */
    public TinyHello() {
    }

    /** The Active Object creates and returns information on its location
     * @return a StringWrapper which is a Serialized version, for asynchrony */
    public StringMutableWrapper sayHello() {
        return new StringMutableWrapper(this.message + "\n from " + getHostName() + "\n at " +
            new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date()));
    }

    /** finds the name of the local machine */
    static String getHostName() {
        return ProActiveInet.getInstance().getInetAddress().getHostName();
    }

    /** The call that starts the Acive Objects, and displays results.
     * @param args must contain the name of an xml descriptor */
    public static void main(String[] args) throws Exception {
        // Creates an active instance of class Tiny on the local node
        TinyHello tiny = (TinyHello) PAActiveObject.newActive(TinyHello.class.getName(), // the
 class to deploy
                null // the arguments to pass to the constructor, here none
                ); // which jvm should be used to hold the Active Object

        // get and display a value 
        StringMutableWrapper received = tiny.sayHello(); // possibly remote call
        logger.info("On " + getHostName() + ", a message was received: " + received); // potential
 wait-by-necessity
        // quitting

        PALifeCycle.exitSuccess();
    }
}

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN"
 "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<!-- A user component. It has an interface to the dispatcher. -->

<definition name="org.objectweb.proactive.examples.components.c3d.adl.UserImpl">

<!-- The interfaces the component defines -->
  <interface signature="org.objectweb.proactive.examples.c3d.Dispatcher" role="client" name=
"user2dispatcher"/>

<!-- The implementation of the component -->
  <content class="org.objectweb.proactive.examples.components.c3d.UserImpl"/>
  <controller desc="primitive"/>

<!-- deploy this component only on 'User' VirtualNodes (which must be found in the deploy.
 descr.) -->
  <virtual-node name="User" cardinality="single"/>

</definition>

A screen example, for instance some code inside a unix shell:

linux > start.sh & 

Here is some java code directly included in the docbook (you can use CDATA to escape & and <):

package util;
                                                   
import java.io.IOException;
                                                   
/** Just a dummy class. */

public class Dummy {
                                                   
  /** Just the method description 
   * @param fileToConvert the name of the file to convert 
   * @return a String created  */   
  String convert(String fileToConvert) throws IOException {
    if (a > b && c < d ) {
      // can use "this" for 'NodeCreationEvent'
      VirtualNode vn = pad.getVirtualNode("p2pvn");
      vn.start();
      }
    return "Hello World";      
  }
                                                                    
}

Here is an example of deployment descriptor that deploys 3 virtual nodes .

 <!-- Deploying 3 virtual Nodes  -->
 <ProActiveDescriptor>                        
  <componentDefinition>
   <virtualNodesDefinition>
    <virtualNode name="NonFT-Workers" property="multiple"/>
    <virtualNode name="FT-Workers" property="multiple" ftServiceId="appli"/>
    <virtualNode name="Failed" property="multiple" ftServiceId="resource"/>
   </virtualNodesDefinition>
  </componentDefinition>
  
  <deployment>
     <mapping>
      <map virtualNode="NonFT-Workers">
       <jvmSet>
        <vmName value="Jvm1"/>
       </jvmSet>
      </map>
      <map virtualNode="FT-Workers">
       <jvmSet>
        <vmName value="Jvm2"/>
       </jvmSet>
      </map>
    ....

Use XREF tags to point to the Figures id (Section 38.3.2, “Figures”) which is in the doc above. The LINKEND attribute points to the id which is referenced, for example, in a SECTION tag. The ENDTERM tag (example with the biblio) is used to customize the string which will be used to point to the reference.

You can also use XREF to include files which are in the html hierararchy already. This goes for java files, and deployment descriptors. You have a few examples in Descriptor.xml. (technical note: including files is done through the java files in util. This may be done in pure xsl, but I gave up! The pdf and html look different thanks to profiling)

Use ULINK tags to point to web references (ProActive for instance). Use freely, it sticks out nicely in pdf too!

Use CITATION followed by an XREF for citations. For example, see [BBC02] to learn on groups. All the biblio entries should be put in biblio.xml. You should consider using the bibdb tool to convert from bibtex (http://charybde.homeunix.org/~schmitz/code/bibdb/).

The tag to use is TABLE.

The files for configuration are the following:

Basically, in the customization layers, you have full control (just do what you want). The only thing is that each block (template, variable...) should be described by a comment. That will help later users. As customization can get cryptic, make a special effort!

The book you want to have with you is the following: "DocBook XSL: The Complete Guide", Third Edition, by Bob Stayton, online version at http://www.sagehill.net.

Have a look at the index if you just want to change a little something in the customization. Parse through it at least once if you intend to do some heavy editing. I have found everything I needed in this book, but sometimes in unexpected sections.

If you want to write some stuff that should go in pdf but not html, or vice-versa, you want to do some "profiling". This is very easy to do, as it was needed and tuned for the processing stages. Add an "os" attribute to the sections you want to exclude, specifying the wanted output format in which it should only appear.

 <para os="pdf"> This paragraph only appears in pdf output! </para>

(Comment) Using the "os" attribute to specify the output is not elegant. Agreed. But in docbook there is no default attribute intended to express the expected output file format, and using the "role" attribute is discouraged.

If you are editing the xsl stylesheets, and are having a hard time figuring out what's happening, don't panic! Use many messages to find out what the values of the variables are at a given time:

<xsl:message>
     <xsl:text> OK, in question.toc, id is </xsl:text> <xsl:copy-of select="$id" /> 
    </xsl:message>
    
    <xsl:for-each select="./@*">
     <xsl:message>
      <xsl:text> Attribute  <xsl:value-of select="name(.)"/> = <xsl:value-of select="."/>  </xsl:text> 
     </xsl:message>
    </xsl:for-each >  

You will very soon find that you still have to dig deeper into the templates, and they certainly are not easy to follow. Here's a little helper:

java -cp $CLASSPATH org.apache.xalan.xslt.Process -TT -xsl ...  -in ... -out ...

This uses the specified templates with the xsl file specified, but tracing every template called. Useful when you're wondering what's being called. I'm sorry but I have not found a way to trace the call tree of a method, ie knowing exactly where it comes from. Have to do without!

The dtd is the file detailling which are the allowed tags in our DocBook subset. Some tags have been removed, to make it easier to manage. Please refer to the file called ProActive/doc-src/ProActiveManual.dtd to know how much freedom you have been granted.

When you run the manual generation through the ant tasks, the xml is checked for validity. The message you should see is

XML is VALID and complies to dtd in ../docs/tmp/PA_index.xml

If you happen to modify the dtd, you should put also copy it on the web, on /proj/oasis/www/proactive/doc/dtd/$version/ or else the previous version one will always be used.