La documentation JOnAS compose le module SVN jonas_doc du repository jonas .

Dans ce projet va être mis en oeuvre le DocBook Xslt Publishing Model qui est décrit dans ce diagramme

1.1.1. Structure du module SVN jonas_doc

Le module SVN jonas_doc a la structure suivante:

Avec:

olddoc

contient les fichiers html correspondant à l'ancienne doc JOnAS. Devrait etre detruit tres prochainement

src/docbook/doc-en

contient les fichiers xml correspondants aux documents anglais écrits en docBook

src/docbook/doc-fr

contient les fichiers xml correspondants aux documents français écrits en docBook

resources

contients les images, les stylesheets xls ou css

tools

contient le processeur Apache FOP utilisé pour fabriquer les documents pdf.

La génération de la doc se fait via ant. Il existe une target par document, ainsi que des target pour enchainer un ensemble de documents :

Les documents livrés sont genérés sous 3 formes :

Ces target ne sont pas appelables directement. On doit donc générer les 3 formats à chaque fois pour chaque document.

Les targets html , fo et chunk dépendent de la target xslt qui utilise xsltproc.

Dans le cas d'un environnement Windows, le chemin vers l'exécutable xsltproc devra être présent dans le PATH du système. L'exécutable et ces dll associées sont présents dans le répertoire tools/win32.

Les transformations XML docBook -> HTML se fait via les feuilles de styles html.xsl et chunk.xsl

la transformation XML-> XSL-FO se fait via la feuille de style fo.xls

Ces feuilles de style se trouvent dans la directory resources

	Attention
	Ces feuilles de styles en incluent d'autres qui se trouvent sous tools/docbook-xsl-1.73.2/html/docbook.xsl

Toute la doc genérée va sous un directory output, qui est structuré ainsi:

Les 2 repertoires dist et local ont la même structure:

Deux machines rentrent en ligne de compte jonas.forge.objectweb.org et jonas.objectweb.org

La machine jonas.forge.objectweb.org est la machine de développement, jonas.objectweb.org est la machine de publication.

Sur la machine jonas.forge.objectweb.org il y a une zone accessible via webdavs qui contient :

La publication de la doc se fait en deux phases:

Il y a trois niveaux de personnalisation possibles

La génération des chaines variables via la directive xi:include pose un problème quand cette chaine apparait dans un lien

exemple :

<a href="#id2">abcde <span ><a name="appserver"></a>fghijk</span></a>

Le html généré par les feuilles de styles xls n'est pas valide voici le compte rendu du validateur html du W3C:

Le workaround utilisé est de processer les fichier html générés et remplacer <a name="appserver"></a> par rien (car par chance seule la string variable JOnAS apparait dans des href)

L'outil XMLmind (xxe) permet de travailler en wysiwyg. C'est une alternative intéressante à un editeur basic de style emacs. Il permet en outre de ne pas avoir à connaitre tous les tags docbook puisqu'il les propose dans ses menus.

Pour l'utiliser, il suffit de lancer la commande: xxe

On peut trouver de la documentation en français dans le Guide de l'utilisateur de l'éditeur XML de XMLmind V3.4

Pour créer un nouveau document, le plus simple est de copier un document existant et de modifier ensuite son contenu, récupérant ainsi facilement toute sa structure

Pour personnaliser son environement xmlmind il faut:

On a souvent besoin de présenter des parties de codes, des fichiers de conf, des parties d'affichage d'écran alphanumérique pour lesquels on a besoin de faire du telquel (les coupures de lignes doivent être respectées).

En DocBook nous pouvons utiliser les éléments <screen>,<programlisting>, <literallayout> qui ont à peu prés les mêmes caractéristiques.

Ces éléments seront différentiés à la présentation par la feuille de style .css (pour le html).

Nous reservons :

Par exemple, dans le document présent nous réservons <literallayout> pour montrer du code docBook et <screen> pour le résultat du code précédent cf Section 3.4.1, « lien vers une partie du document (xref) ».

On utilise en général la balise <informaltable> sous laquelle on trouve une balise tgroup qui précise le nb de colonnes du tableau. Sous <tgroup> on trouve 2 parties: <thead> pour la partie en-tête, et <tbody> pour le corps du tableau. Les <thead> et <tbody> ont la même structure, mais n'auront pas le même rendu html, défini dans la feuille de style.

Avec xxe, on pourra utiliser le menu approprié, dans la barre d'outils : informaltable(head_row)

Exemple de tableau très simple, avec le code xml correspondant :

Pour obtenir ceci:

carol.protocols=jrmp 
carol.jrmp.url=rmi://localhost:1099 
        


 

            
choice of the protocol or list of protocols
          


 

            
connexion url to the RMI registry
          

Il faut un <screen> (ou <programlisting>) avec des éléments <co> à l'endroit que l'on veut annoter avec un identifiant comme attribut xml:id

suivi d'un <calloutlist> ayant le meme nombre d'éléments <callout> que d'annotations, chacun des callout ayant un attribut arearefs contenant l' xml:id de l'annotation correspondante.

Voici le code xml correspondant:

A noter que l'insertion des annotations dans la ligne se fait très simplement avec xxe.

le fichier variables.xml est un fichier utilisé uniquement pour définir le contenu de chaines de caractères qui risquent de changer (nom de projet, numéro de version, etc...):

Ce fichier est consitué d'une section et d'un ensemble de lignes contenant des déclarations du style :

objectweb étant l'identifiant utilisé dans les documents sources, et ObjectwebV2 la valeur qui sera finalement remplacée dans le fichier html (ou pdf) généré.

Dans la document xml, il faudra insérer, à la place de ObjectwebV2, un texte qui ressemble à :

Avec xxe, on fera simplement :

On peut utiliser la mécanique des xi:include décrite ci-dessus pour inclure tout ou partie d'un document xml dans un autre. Il faudra juste supprimer la partie xpointer si tout le document doit etre inclus.

Cette mécanique est largement utilisée dans la documentation JOnAS, la plupart des books étant une liste de chapitres (ou annexes) qui incluent des fichiers xml situés ailleurs

Un exemple :

Sous xxe, on fera comme précédemment, mais il faudra ensuite manuellement supprimer la partie xpointer.

Pour obtenir ceci une barre de défilement permettant de scroller une zone d'information importante, on utilisera une balise programlisting :

la (ou les) barre de défilement n'apparaitront pas dans le document pdf bien sur.

Exemple de présentation du fichier jonas.properties:

# Enable the Security context propagation (for jrmp)
jonas.security.propagation    true

# Enable the Security manager
# default value is true (if not set)
# Setting this to false implies a colocated registry and setting in carol.properties:
# carol.jvm.rmi.local.registry=true
jonas.security.manager    false

# Enable csiv2
jonas.csiv2.propagation    true

# Enable the Transaction context propagation
jonas.transaction.propagation    true

#  Set the name of log configuration file
jonas.log.configfile    trace

# Set to true if the server is a master
jonas.master    false


#  Set the list of the services launched in the JOnAS Server.
#  Possible services are: registry,jmx,security,jtm,db,mail,wm,wc,dbm,resource,cmi,ha,versioning,ejb2,ejb3,ws,web,ear,depmonitor,discovery
#  (registry and jmx are automatically started even if not present in the list)
#  Order in the list is important (see 'Configuring JOnAS services' in JOnAS documentation)
#
jonas.services    registry,jmx,jtm,db,dbm,security,wm,wc,resource,ejb2,ejb3,ws,web,ear,depmonitor

#
###################### JOnAS Registry service configuration
#
#  Set the name of the implementation class of the Registry service
jonas.service.registry.class org.ow2.jonas.registry.carol.CarolRegistryService

#  Set the Registry launching mode
#  If set to 'automatic', the registry is launched in the same JVM as Application Server,
#                         if it's not already started.
#  If set to 'collocated', the registry is launched in the same JVM as Application Server
#  If set to 'remote', the registry has to be launched before in a separate JVM
jonas.service.registry.mode    collocated

#
###################### JOnAS JMX service configuration
#
#  Set the name of the implementation class of the JMX service
jonas.service.jmx.class                         org.ow2.jonas.jmx.internal.JOnASJMXService

#  Set to true if the JMXRemote interface should require the client to provide
#  authentication information. That information is provided when establishing
#  the JMX connection, using the JMXConnector.CREDENTIALS key.
#
#  Note that if you enable JMX security for a server, all clients (including
#  any administration tool such as the domain master) connecting to this
#  instance via JMX must provide a valid user name and password.
jonas.service.jmx.secured                       false

#  If jonas.service.jmx.secured is set to true, defines the authentication
#  method and the method's parameter. For example, to use file-based
#  authentication using the conf/jmx.passwords file, define:
#      jonas.service.jmx.authentication.method    jmx.remote.x.password.file
#      jonas.service.jmx.authentication.parameter conf/jmx.passwords
#  You are free to use the authentication provider you wish.
jonas.service.jmx.authentication.method         jmx.remote.x.password.file
jonas.service.jmx.authentication.parameter      conf/jmx.passwords
#  You may for example choose to use JAAS LoginModule for authentication.
#  In this case define the used configuration in the JAAS configuration file
#  using the jonas.service.jmx.authentication.parameter:
#      jonas.service.jmx.authentication.method      jmx.remote.x.login.config
#      jonas.service.jmx.authentication.parameter   jaas-jmx

#  If jonas.service.jmx.secured is set to true, defines the authorization
#  method and the method's parameter. For example, to use file-based
#  authorization using the conf/jmx.access file, define:
#      jonas.service.jmx.authorization.method    jmx.remote.x.access.file
#      jonas.service.jmx.authorization.parameter conf/jmx.access
#  You are free to use the authorization provider you wish.
jonas.service.jmx.authorization.method          jmx.remote.x.access.file
jonas.service.jmx.authorization.parameter       conf/jmx.access
#  You may for example choose to use role-based authorization manager
#  configured using conf/jmx.rolebased.access file. In this case, define:
#      jonas.service.jmx.authorization.method          jmx.remote.x.access.rolebased.file
#      jonas.service.jmx.authorization.parameter       conf/jmx.rolebased.access


#
###################### JOnAS WorkCleaner service configuration
#
#  Set the name of the implementation class of the wc service
jonas.service.wc.class    org.ow2.jonas.workcleaner.internal.JOnASWorkCleanerService

#  Set the clean period in seconds
jonas.service.wc.period   300


#
###################### JOnAS WorkManager service configuration
#
#  Set the name of the implementation class of the wm service
jonas.service.wm.class    org.ow2.jonas.workmanager.internal.JOnASWorkManagerService

#  Set the size of the worker thread pool
jonas.service.wm.minworkthreads   3

#  Set the maximun size of the worker thread pool
jonas.service.wm.maxworkthreads   80

#  Set the max # of seconds that a thread will wait for work
#  This is used to shrink the worker thread pool back to minimum
jonas.service.wm.threadwaittimeout 60


#
###################### JOnAS EJB 2 Container service configuration
#
#  Set the name of the implementation class of the ejb2 service
jonas.service.ejb2.class    org.ow2.jonas.ejb2.internal.JOnASEJBService

#  Set the XML deployment descriptors parsing mode (with or without validation)
jonas.service.ejb2.parsingwithvalidation    true

# If enabled, the GenIC tool will be called if :
#  - JOnAS version of the ejb-jar is not the same version than the running JOnAS instance
#  - Stubs/Skels stored in the ejb-jar are not the same than the JOnAS current protocols.
# By default, this is enabled
jonas.service.ejb2.auto-genic    true

# Arguments for the auto GenIC (-invokecmd, -verbose, etc.)
jonas.service.ejb2.auto-genic.args -invokecmd

###################### JOnAS EJB 3 container service configuration
#
#  Set the name of the implementation class of the EJB 3 service.
jonas.service.ejb3.class    org.ow2.jonas.ejb.easybeans.EasyBeansService

###################### JOnAS Versioning service configuration
#
#  Set the name of the implementation class of the versioning service.
jonas.service.versioning.class          org.ow2.jonas.versioning.internal.VersioningServiceImpl

###################### JOnAS Web container service configuration
#
#  Set the name of the implementation class of the web container service.
jonas.service.web.class    org.ow2.jonas.web.tomcat6.Tomcat6Service
#jonas.service.web.class    org.ow2.jonas.web.jetty6.Jetty6Service

#  Set the XML deployment descriptors parsing mode for the WEB container
#  service (with or without validation).
jonas.service.web.parsingwithvalidation    true

###################### JOnAS WebServices service configuration
#
#  Set the name of the implementation class of the WebServices service.
jonas.service.ws.class    org.ow2.jonas.ws.axis.AxisService

# Set the JServiceFactory to use
jonas.service.ws.factory.class org.ow2.jonas.ws.axis.JAxisServiceFactory

#  Set the XML deployment descriptors parsing mode for the WebServices
#  service (with or without validation).
jonas.service.ws.parsingwithvalidation    true

#  Set the WSDL Handler list for WSDL publication
#  A minimum of 1 WSDLHandler is required !
#  This property is set with a coma-separated list of WSDLHandler properties
#  file names (without the '.properties' suffix).
#  Ex: file1,uddi (while the properties file names are
#                  file1.properties and uddi.properties)
jonas.service.ws.wsdlhandlers file1

# Set the Generator to use with wsgen
jonas.service.ws.wsgen.generator.factory     org.ow2.jonas.generators.wsgen.generator.ews.EWSGeneratorFactory

# Set the prefix that will be used to compute URL endpoints for web services
# Example of prefix: http://www.mydomain.com:8888
jonas.service.ws.url-prefix

# Set automatic WsGen mode on/off
# If set to 'true', WsGen will automatically be applied to all deployed archives (EjbJars, Webapps, Applications)
jonas.service.ws.auto-wsgen.engaged true

#
###################### JOnAS EAR service configuration
#
#  Set the name of the implementation class of the ear service.
jonas.service.ear.class    org.ow2.jonas.ear.internal.JOnASEARService

#  Set the XML deployment descriptors parsing mode for the EAR service
#  (with or without validation).
jonas.service.ear.parsingwithvalidation    true

#
###################### JOnAS DBM Database service configuration
#
#  Set the name of the implementation class of the dbm service
jonas.service.dbm.class    org.ow2.jonas.dbm.internal.JOnASDataBaseManagerService

#  Set the jonas DataSources. This enables the JOnAS server to load
#  the data dources, to load related jdbc drivers, and to register the data
#  sources into JNDI.
#  This property is set with a coma-separated list of Datasource properties
#  file names (without the '.properties' suffix).
#  Ex: Oracle1,InstantDB1 (while the Datasources properties file names are
#                          Oracle1.properties and InstantDB1.properties)
jonas.service.dbm.datasources    HSQL1

#
###################### JOnAS Mail service configuration
#
#  Set the name of the implementation class of the mail service
jonas.service.mail.class  org.ow2.jonas.mail.internal.JOnASMailService

#  Set the jonas mail factories.
#  This property is set with a coma-separated list of MailFactory properties
#  file names (without the '.properties' suffix).
#  Ex: MailSession1,MailMimePartDS1 (while the properties file names are
#                  MailSession1.properties and MailMimePartDS1.properties)
jonas.service.mail.factories

#
###################### JOnAS JTM Transaction service configuration
#

#  Set the name of the implementation class of the jtm service
jonas.service.jtm.class    org.ow2.jonas.tm.jotm.JOTMTransactionService

#  Set the Transaction Manager launching mode.
#  If set to 'true', TM is remote: TM must be already launched in an other JVM.
#  If set to 'false', TM is local: TM is going to run into the same JVM
#  than the jonas Server.
jonas.service.jtm.remote    false

#  Set the default transaction timeout, in seconds.
jonas.service.jtm.timeout    60


#
###################### JOnAS SECURITY service configuration
#
#  Set the name of the implementation class of the security service
jonas.service.security.class  org.ow2.jonas.security.internal.JonasSecurityServiceImpl

# Realm used for CsiV2 authentication
jonas.service.security.csiv2.realm    memrlm_1

# Realm used for Web Service authentication
jonas.service.security.ws.realm    memrlm_1

# Registration of realm resources into JNDI
# Disable by default so configuration is not available with clients
jonas.service.security.realm.jndi.registration    false

# Enable security context check on Remote Login Module
jonas.security.context.check    false

# Path to the keystore file
jonas.security.context.check.keystoreFile /tmp/keystore

# Pass used for the keystore file
jonas.security.context.check.keystorePass keystorepass

# Alias (stored in the keystore)
jonas.security.context.check.alias FB

#
###################### JOnAS J2CA resource service configuration
#
#  Set the name of the implementation class of the J2CA resource service
jonas.service.resource.class  org.ow2.jonas.resource.internal.JOnASResourceService

###################### JOnAS DB service configuration
#
#  Set the name of the implementation class of the db service (hsql for example)
jonas.service.db.class    org.ow2.jonas.db.hsqldb.HsqlDBServiceImpl
jonas.service.db.port    9001
jonas.service.db.dbname    db_jonas
jonas.service.db.users    jonas:jonas
# Multiple users
#jonas.service.db.users    jonas:jonas,login:password

###################### JOnAS Discovery service
#
#  Set the name of the implementation class and initialization parameters
jonas.service.discovery.class=org.ow2.jonas.discovery.jgroups.JgroupsDiscoveryServiceImpl
# Uncomment this to set Multicast implementation
#jonas.service.discovery.class=org.ow2.jonas.discovery.internal.MulticastDiscoveryServiceImpl


#####################  Properties for multicast impl.

#  For a master server, configure the client source port with this property
jonas.service.discovery.source.port=9888
jonas.service.discovery.ttl=1
jonas.service.discovery.multicast.address=224.224.224.224
jonas.service.discovery.multicast.port=9080

#  A multicast greeting message is sent out when discovery service is started.
#  The starting server listens at the port jonas.service.discovery.greeting.port
#  (default 9899) for a response for jonas.service.discovery.greeting.timeout miliseconds
#  (default 1000 ms). If a pre-existing server has the same server name as this one,
#  this server's discovery service will be terminated.
#  Uncomment these two lines for multicast discovery
jonas.service.discovery.greeting.port=9899
jonas.service.discovery.greeting.timeout=1000

#####################  properties for JGroups impl.
jonas.service.discovery.jgroups.conf= jgroups-discovery.xml
jonas.service.discovery.group.name = JGroupsDiscovery
#Reconnection timeout for JGroups Channel, if it's closed on request.
jonas.service.discovery.reconnection.timeout = 5000

###################### JOnAS CMI service configuration
#
# Set the name of the implementation class of the CMI service.
jonas.service.cmi.class   org.ow2.jonas.cmi.internal.CmiServiceImpl

###################### JOnAS HA service configuration
#
# Set the name of the implementation class of the HA service.
jonas.service.ha.class    org.ow2.jonas.ha.internal.HaServiceImpl

# Set the JGroups configuration file name
jonas.service.ha.jgroups.conf jgroups-ha.xml

# Set the JGroups group name
jonas.service.ha.jgroups.groupname jonas-rep

# Set the SFSB backup info timeout. The info stored in the backup node is removed when the timer expires.
jonas.service.ha.gc.period 600

# Set the datasource for the tx table
jonas.service.ha.datasource jdbc_1

# Reconnection timeout for JGroups Channel, if it's closed on request.
jonas.service.ha.reconnection.timeout 5000

###################### JOnAS Deployment Monitor
#
# Set the name of the implementation class of the depmonitor service
#
jonas.service.depmonitor.class          org.ow2.jonas.deployablemonitor.DeployableMonitorService
jonas.service.depmonitor.development    true
jonas.service.depmonitor.directories
# List (comma separated) of exclusion patterns (based on names, not directories)
jonas.service.depmonitor.exclusions     README
      

Voici le résultat attendu (dans un document HTML):

Il suffit de rajouter dans la feuille de style fo.xsl:

        <xsl:param name="fop1.extensions" select="1"/>
      

dans ce § un certain nombre de règles sont énumérées afin d'obtenir une documentation homogène: