<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:lang="fr" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:mml="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>La Documentation JOnAS</title>

    <authorgroup>
      <author>
        <orgname>JOnAS Team</orgname>
      </author>

      <author>
        <personname><surname>Coq</surname>
        <firstname>Philippe</firstname></personname>
      </author>

      <author>
        <personname><surname>Durieux</surname>
        <firstname>Philippe</firstname></personname>
      </author>
    </authorgroup>

    <copyright>
      <year>2007-2008</year>

      <holder>OW2 consortium</holder>
    </copyright>

    <date>juin 2008</date>
  </info>

  <preface xml:id="jonas.doc.preface">
    <info>
      <title>Preface</title>
    </info>

    <para>Ce document s'adresse aux contributeurs (nombreux, espérons le..)
    qui auront à participer à l'amélioration de la documentation JOnAS.</para>

    <para>Il est fortement conseillé de le lire avant de contribuer car
    l'infrastructure de fabrication de la documentation a complètement changé
    par rapport à l'ancienne documentation JOnAS. Avant il fallait écrire
    directement la documentation en HTML. Maintenant, la technologie utilisée
    est XML DocBook qui a l'avantage de bien séparer la partie contenu de la
    présentation et de permettre de générer cette documentation sous
    différents formats. Ce document est censé décrire comment écrire,
    fabriquer, publier la documentation JOnAS. Nous avons profité de ce
    changement pour intégrer la documentation dans SVN.</para>

    <para>Le document est organisé de la manière suivante:</para>

    <itemizedlist>
      <listitem>
        <para><xref linkend="infrastructure" /> décrit la structure du projet
        SVN aussi bien du point de vue des fichiers initiaux (DocBook,
        feuilles de style) que des fichiers générés (HTML,pdf,war)</para>
      </listitem>

      <listitem>
        <para><xref linkend="xmlmind" /> décrit brièvement l'utilisation d'un
        outil possible et conseillé pour écrire la doc en DocBook
        (XMLmind)</para>
      </listitem>

      <listitem>
        <para><xref linkend="docbook" /> n'est pas un manuel de référence mais
        c'est un chapitre qui donne des liens sur des documents intéressants
        sur DocBook, et des solutions à quelques problèmes. Ce chapitre
        devrait être en constante évolution pour constituer une base de
        connaissance.</para>
      </listitem>

      <listitem>
        <para><xref linkend="conventions" /> se veut une collection de bonnes
        pratiques dont le but pricipal est d'obtenir une documentation
        homogène quelque soit le nombre de rédacteurs.</para>
      </listitem>
    </itemizedlist>
  </preface>

  <chapter xml:id="infrastructure">
    <info>
      <title>L'infrastructure de la documentation JOnAS</title>
    </info>

    <section>
      <info>
        <title>Description</title>
      </info>

      <para>La documentation JOnAS compose le module SVN <emphasis
      role="bold">jonas_doc</emphasis> du repository <emphasis
      role="bold">jonas</emphasis> .</para>

      <para>Dans ce projet va être mis en oeuvre le DocBook Xslt Publishing
      Model qui est décrit dans ce <link
      xlink:href="http://wiki.docbook.org/topic/DocBookXsltPublishingModelDiagram">
      diagramme </link></para>

      <section>
        <info>
          <title>Structure du module SVN jonas_doc</title>
        </info>

        <para>Le module SVN jonas_doc a la structure suivante:</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="../../resources/images/jonas_doc.gif"></imagedata>
          </imageobject>
        </mediaobject>

        <para>Avec:</para>

        <variablelist>
          <varlistentry>
            <term>olddoc</term>

            <listitem>
              <para>contient les fichiers html correspondant à l'ancienne doc
              JOnAS. Devrait etre detruit tres prochainement</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>src/docbook/doc-en</term>

            <listitem>
              <para>contient les fichiers xml correspondants aux documents
              anglais écrits en docBook</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>src/docbook/doc-fr</term>

            <listitem>
              <para>contient les fichiers xml correspondants aux documents
              français écrits en docBook</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>resources</term>

            <listitem>
              <para>contients les images, les stylesheets <filename
              class="extension">xls</filename> ou <filename
              class="extension">css</filename></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>tools</term>

            <listitem>
              <para>contient le processeur Apache FOP utilisé pour fabriquer
              les documents pdf.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>

      <section>
        <info>
          <title>Structure des sources de la documentation livrée (guides en
          anglais)</title>
        </info>

        <para>L'ensemble des fichiers xml permettant de générer les guides
        JOnAS se trouve sous le directory
        <filename>jonas_doc/src/docbook/doc-en</filename> . Le directory est
        structuré en sous-répertoires de façon a retrouver facilement les
        documents sources. Cette structure est aujourd'hui la suivante:
        <informaltable>
            <tgroup cols="3">
              <tbody>
                <row>
                  <entry><filename>admin</filename></entry>

                  <entry>administration de JOnAS</entry>
                </row>

                <row>
                  <entry><filename>anttasks</filename></entry>

                  <entry>toutes les taches ant</entry>
                </row>

                <row>
                  <entry><filename>clustering</filename></entry>

                  <entry>clustering dans JOnAS</entry>
                </row>

                <row>
                  <entry><filename>commands</filename></entry>

                  <entry>toutes les commandes de JOnAS</entry>
                </row>

                <row>
                  <entry><filename>deploy</filename></entry>

                  <entry>deploiement</entry>
                </row>

                <row>
                  <entry><filename>howto</filename></entry>

                  <entry>Les "howto"</entry>
                </row>

                <row>
                  <entry><filename>install</filename></entry>

                  <entry>Installation de JOnAS</entry>
                </row>

                <row>
                  <entry><filename>log</filename></entry>

                  <entry>Logging</entry>
                </row>

                <row>
                  <entry><filename>migration</filename></entry>

                  <entry>Ensemble des documents pour la migration d'une
                  version de JOnAS a une autre</entry>
                </row>

                <row>
                  <entry><filename>protocols</filename></entry>

                  <entry>les protocoles</entry>
                </row>

                <row>
                  <entry><filename>ra</filename></entry>

                  <entry>les "resource adaptor"</entry>
                </row>

                <row>
                  <entry><filename>security</filename></entry>

                  <entry>la securite</entry>
                </row>

                <row>
                  <entry morerows="16"><filename>services</filename></entry>

                  <entry><filename>cmi</filename></entry>

                  <entry>service cmi</entry>
                </row>

                <row>
                  <entry><filename>db</filename></entry>

                  <entry>service db</entry>
                </row>

                <row>
                  <entry><filename>dbm</filename></entry>

                  <entry>service dbm</entry>
                </row>

                <row>
                  <entry><filename>discovery</filename></entry>

                  <entry>service discovery</entry>
                </row>

                <row>
                  <entry><filename>ear</filename></entry>

                  <entry>service ear</entry>
                </row>

                <row>
                  <entry><filename>ejb2</filename></entry>

                  <entry>service ejb2</entry>
                </row>

                <row>
                  <entry><filename>ejb3</filename></entry>

                  <entry>service ejb3</entry>
                </row>

                <row>
                  <entry><filename>ha</filename></entry>

                  <entry>service ha</entry>
                </row>

                <row>
                  <entry><filename>jmx</filename></entry>

                  <entry>service jmx</entry>
                </row>

                <row>
                  <entry><filename>jtm</filename></entry>

                  <entry>service jtm</entry>
                </row>

                <row>
                  <entry><filename>mail</filename></entry>

                  <entry>service mail</entry>
                </row>

                <row>
                  <entry><filename>registry</filename></entry>

                  <entry>service registry</entry>
                </row>

                <row>
                  <entry><filename>resource</filename></entry>

                  <entry>service resource</entry>
                </row>

                <row>
                  <entry><filename>security</filename></entry>

                  <entry>service security</entry>
                </row>

                <row>
                  <entry><filename>web</filename></entry>

                  <entry>service web</entry>
                </row>

                <row>
                  <entry><filename>wm</filename></entry>

                  <entry>service wm</entry>
                </row>

                <row>
                  <entry><filename>ws</filename></entry>

                  <entry>service ws</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable></para>

        <para>Tous les documents finaux (les guides) sont à la racine
        (doc-en). Ils utilisent de maniere quasi systématiques des xi:include
        pour intégrer des morceaux de documents situés n'importe ou dans cet
        arbre.</para>
      </section>
    </section>

    <section>
      <info>
        <title>Générer la doc JOnAS via ant</title>
      </info>

      <para>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
      :</para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>target</entry>

              <entry>description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>clean</entry>

              <entry>delete all generated files</entry>
            </row>

            <row>
              <entry>all</entry>

              <entry>rebuild toute la doc</entry>
            </row>

            <row>
              <entry>war</entry>

              <entry><para> fabrique le <filename>jonas-doc-en.war</filename>
              qui sera integré dans la distribution JOnAS </para></entry>
            </row>

            <row>
              <entry>local</entry>

              <entry><para> fabrique les documents non distribues (ce guide,
              par exemple) </para></entry>
            </row>

            <row>
              <entry>dist</entry>

              <entry><para>fabrique tous les documents livres</para></entry>
            </row>

            <row>
              <entry>guides</entry>

              <entry>enchaine la fabrication de tous les guides</entry>
            </row>

            <row>
              <entry>essai</entry>

              <entry>fabrique le document essai.xml, utilise pour divers
              essais</entry>
            </row>

            <row>
              <entry>ear</entry>

              <entry>J2EE Application Deployer's Guide</entry>
            </row>

            <row>
              <entry>client</entry>

              <entry>J2EE Client programmer's guide</entry>
            </row>

            <row>
              <entry>clustering</entry>

              <entry>JOnAS Clustering Guide</entry>
            </row>

            <row>
              <entry>connector</entry>

              <entry>J2EE Connector programmer's guide</entry>
            </row>

            <row>
              <entry>webpg</entry>

              <entry>Web Application programmer's guide</entry>
            </row>

            <row>
              <entry>ejb2pg</entry>

              <entry>ejb2 programmer's guide</entry>
            </row>

            <row>
              <entry>j2eepg</entry>

              <entry>j2ee programmer's guide</entry>
            </row>

            <row>
              <entry>config</entry>

              <entry>configuration guide</entry>
            </row>

            <row>
              <entry>anttasks</entry>

              <entry>anttasks manual</entry>
            </row>

            <row>
              <entry>howto</entry>

              <entry>fabrique les howto</entry>
            </row>

            <row>
              <entry>bamboo</entry>

              <entry>fabrique le continuous_integration_guide (bamboo)</entry>
            </row>

            <row>
              <entry>migration</entry>

              <entry>migration guide</entry>
            </row>

            <row>
              <entry>started</entry>

              <entry>getting started guide</entry>
            </row>

            <row>
              <entry>deployer</entry>

              <entry>deployer guide</entry>
            </row>

            <row>
              <entry>admin</entry>

              <entry>administration guide</entry>
            </row>

            <row>
              <entry>command</entry>

              <entry>command guide</entry>
            </row>

            <row>
              <entry>copydist</entry>

              <entry>copy toutes les images et l'index.html livrés</entry>
            </row>

            <row>
              <entry>copylocal</entry>

              <entry>copy toutes les images pour les docs locales</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>Les documents livrés sont genérés sous 3 formes :</para>

      <itemizedlist>
        <listitem>
          <para>un document html unique via la target <emphasis
          role="bold">html</emphasis></para>
        </listitem>

        <listitem>
          <para>un document partitonné en <emphasis>chunk</emphasis> via la
          target <emphasis role="bold">chunk</emphasis></para>
        </listitem>

        <listitem>
          <para>un document pdf à partir du document XSL-FO via la target
          <emphasis role="bold">pdf</emphasis></para>
        </listitem>

        <listitem>
          <para>un document en format XSL-FO <footnote>
              <para>des renseignements sur ce format peuvent être trouvés
              <link
              xlink:href="http://sagehill.net/docbookxsl/FOprocessors.html">
              ici </link></para>
            </footnote> (formatting object) via la target <emphasis
          role="bold">fo</emphasis></para>
        </listitem>
      </itemizedlist>

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

      <para>Les targets <emphasis role="bold">html</emphasis> , <emphasis
      role="bold">fo</emphasis> et <emphasis role="bold">chunk</emphasis>
      dépendent de la target <emphasis role="bold">xslt</emphasis> qui utilise
      <emphasis role="bold">xsltproc.</emphasis></para>

      <para>Dans le cas d'un environnement Windows, le chemin vers
      l'exécutable <emphasis role="bold">xsltproc</emphasis> 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 <filename>tools/win32.</filename></para>

      <para>Les transformations XML docBook -&gt; HTML se fait via les
      feuilles de styles <emphasis role="bold">html.xsl</emphasis> et
      <emphasis role="bold">chunk.xsl</emphasis></para>

      <para>la transformation XML-&gt; XSL-FO se fait via la feuille de style
      <emphasis role="bold">fo.xls</emphasis></para>

      <para>Ces feuilles de style se trouvent dans la directory <filename
      class="directory">resources</filename></para>

      <caution>
        <para>Ces feuilles de styles en incluent d'autres qui se trouvent sous
        tools/docbook-xsl-1.73.2/html/docbook.xsl</para>
      </caution>
    </section>

    <section>
      <info>
        <title>Structure de la doc générée via ant</title>
      </info>

      <para>Toute la doc genérée va sous un directory output, qui est
      structuré ainsi: <informaltable>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry><filename>dist</filename> Tous les documents
                livrés</entry>
              </row>

              <row>
                <entry><filename>local</filename> Tous les documents
                locaux</entry>
              </row>

              <row>
                <entry><filename>tmp</filename> fichiers temporaires</entry>
              </row>

              <row>
                <entry><filename>war</filename> le fichier war à integrer dans
                la distribution JOnAS</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable> Les 2 repertoires dist et local ont la même
      structure: <informaltable>
          <tgroup cols="2">
            <tbody>
              <row>
                <entry morerows="2"><filename>doc-en</filename> (documents en
                anglais)</entry>

                <entry><filename>chunk</filename></entry>
              </row>

              <row>
                <entry><filename>html</filename></entry>
              </row>

              <row>
                <entry><filename>pdf</filename></entry>
              </row>

              <row>
                <entry morerows="2"><filename>doc-fr</filename> (documents en
                français)</entry>

                <entry><filename>chunk</filename></entry>
              </row>

              <row>
                <entry><filename>html</filename></entry>
              </row>

              <row>
                <entry><filename>pdf</filename></entry>
              </row>

              <row>
                <entry><filename>resources</filename> images, feuilles de
                style, ...</entry>

                <entry><filename>images</filename></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable></para>
    </section>

    <section>
      <info>
        <title>Publier la doc sur le site JOnAS</title>
      </info>

      <para>Deux machines rentrent en ligne de compte <emphasis
      role="bold">jonas.forge.objectweb.org</emphasis> et <emphasis
      role="bold">jonas.objectweb.org</emphasis></para>

      <para>La machine <emphasis role="bold">jonas.forge.objectweb.org
      </emphasis>est la machine de développement, <emphasis
      role="bold">jonas.objectweb.org </emphasis>est la machine de
      publication.</para>

      <para>Sur la machine <emphasis
      role="bold">jonas.forge.objectweb.org</emphasis> il y a une zone
      accessible via webdavs qui contient :</para>

      <itemizedlist>
        <listitem>
          <para>Une directory current contenant la documentation de JOnAS 4.8
          EE</para>
        </listitem>

        <listitem>
          <para>Une directory doc contenant un ensemble de doc et tutoriels
          plus ou moins vieux</para>
        </listitem>

        <listitem>
          <para>Une directory JOnAS_4_7 contenant la documentation de JOnAS
          4.7</para>
        </listitem>

        <listitem>
          <para>Une directory pour la doc JOnAS5 (ayant le nom du tag
          correspondant) contenant:</para>

          <itemizedlist>
            <listitem>
              <para>une directory doc qui contient l'equivalent du output/dist
              de la doc jonas 5</para>
            </listitem>

            <listitem>
              <para>une directory jdoc qui contient la javadoc
              correspondante<footnote>
                  <para>Rappel: pour JOnAS 5 la javadoc se génère en faisant
                  mvn javadoc:javadoc</para>
                </footnote></para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Une directory pour la doc JOnAS4 (ayant le nom du tag
          correspondant) contenant:</para>

          <itemizedlist>
            <listitem>
              <para>une directory doc qui contient l'equivalent du output/dist
              de la doc jonas 4</para>
            </listitem>

            <listitem>
              <para>une directory jdoc qui contient la javadoc
              correspondante<footnote>
                  <para>Rappel: pour JOnAS 4 la javadoc se génère en faisant
                  ant javadoc</para>
                </footnote></para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>La publication de la doc se fait en deux phases:</para>

      <orderedlist>
        <listitem>
          <para>Mise à jour de <emphasis
          role="bold">jonas.forge.objectweb.org</emphasis></para>

          <para>On utilise Konqueror avec l'URL:
          webdavs://jonas.forge.objectweb.org:8002/</para>

          <para>Il suffit de copier les repertoires avec la souris (doc-en et
          resources) depuis le directory output/dist de la doc.</para>
        </listitem>

        <listitem>
          <para>Mise à jour de <emphasis
          role="bold">jonas.objectweb.org</emphasis></para>

          <para>Se mettre sous l'onglet admin de <link
          xlink:href="http://forge.objectweb.org/project/admin/?group_id=5">
          la forge JOnAS: </link></para>

          <mediaobject>
            <imageobject>
              <imagedata fileref="../../resources/images/forgeadmin.gif"></imagedata>
            </imageobject>
          </mediaobject>

          <para></para>

          <para>Cliquer sur le bouton de publication " <emphasis> Push Project
          Web Site from Development to Production Now </emphasis> !"</para>

          <mediaobject>
            <imageobject>
              <imagedata fileref="../../resources/images/publish.gif"></imagedata>
            </imageobject>
          </mediaobject>

          <para>Cette opération consiste à copier le contenu de la zone
          webdavs de <emphasis
          role="bold">jonas.forge.objectweb.org</emphasis> sur <emphasis
          role="bold">jonas.objectweb.org</emphasis> et de faire un merge avec
          le contenu du sous projet web (ancien site web) du projet
          JOnAS.</para>

          <para><note>
              <para>ll est à noter que le contenu de web/html sera copié
              directement sous <emphasis
              role="bold">jonas.objectweb.org</emphasis>. C'est ainsi que sont
              publiés les démos sous http://jonas.ow2.org/demos/, les dtd sous
              http://jonas.ow2.org/dtds/ et les schémas sous
              http://jonas.ow2.org/ns/.</para>
            </note></para>

          <para></para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <info>
        <title>Personnalisation de la doc JOnAS</title>
      </info>

      <para>Il y a trois niveaux de personnalisation possibles</para>

      <orderedlist continuation="restarts" inheritnum="ignore">
        <listitem>
          <para>personnalisation des transformations Docbook-&gt;autres
          formats (HTML ou XSL-FO)</para>

          <para>L'idée est de fournir une couche de personnalisation (
          <emphasis>Customization layer</emphasis> ) via une feuille de style
          .xls qui permet de modifier certains paramétres comme la profondeur
          de la table des matières, la manière de numéroter les chapitres,
          sections etc... <itemizedlist>
              <listitem>
                <para>pour une transformation DocBook-&gt;HTML les paramètres
                que l'on peut positionner sont décrits <link
                xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html">
                ici. </link></para>
              </listitem>

              <listitem>
                <para>pour une transformation DocBook-&gt; XSL-FO les
                paramètres positionnables sont décrits <link
                xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/fo/index.html">
                ici </link> .</para>
              </listitem>

              <listitem>
                <para>les feuilles de styles utilisées pour la doc JOnAS se
                trouve dans la directory <filename
                class="directory">resources</filename> et sont:</para>

                <variablelist>
                  <varlistentry>
                    <term>html.xls</term>

                    <listitem>
                      <para>utilisée dans la génération d'un document
                      monolitique</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>chunk.xls</term>

                    <listitem>
                      <para>utilisée dans la génération d'un document
                      segmenté. (elle aurait besoin d'amélioration).</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>fo.xls</term>

                    <listitem>
                      <para>utilisée dans la génération d'un document
                      pdf</para>
                    </listitem>
                  </varlistentry>
                </variablelist>
              </listitem>

              <listitem>
                <para>pour trouver des renseignements sur les
                <emphasis>Customization layer</emphasis> se reporter au <link
                xlink:href="http://www.sagehill.net/docbookxsl/CustomMethods.html">
                Chapter 8. Customization methods du livre DocBook XSL: The
                Complete Guide - 3rd Edition </link></para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>personnalisation de la présentation des documents HTML</para>

          <para>On ne positionne pas de caractéristiques de présentation dans
          le document DocBook lui même, mais plutôt dans des Cascading Style
          Sheets ( <filename class="extension">.css).</filename></para>

          <para>On peut se reporter au chapitre <link
          xlink:href="http://www.sagehill.net/docbookxsl/UsingCSS.html"> Using
          CSS to style HTML </link> pour plus de renseignements</para>

          <para>La feuille de style utilisée est
          <filename>resources/common.css</filename></para>
        </listitem>

        <listitem>
          <para>personnalisation de la présentation des documents pdf. Pour
          cette personnalisation il faut apprendre à connaitre le langage
          XSL-FO!</para>

          <para>on peut se reporter: <itemizedlist>
              <listitem>
                <para>au tutoriel W3C <link
                xlink:href="http://www.w3schools.com/xslfo/xslfo_intro.asp">
                Introduction to XSL-FO </link></para>
              </listitem>

              <listitem>
                <para>au <link
                xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/fo/index.html">
                FO Parameter Reference document </link></para>
              </listitem>
            </itemizedlist></para>

          <para>La feuille de style utilisee est
          <filename>resources/fo.xls</filename> Elle permet d'élaborer une
          page de garde appropriée en fonction des bookinfo. Elle pourrait
          permettre d'améliorer la présentation des document pdf actuel mais
          il y a encore du travail à faire.</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <info>
        <title>Problèmes connus</title>
      </info>

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

      <para>exemple :</para>

      <para>&lt;a href="#id2"&gt;abcde &lt;span &gt;&lt;a
      name="appserver"&gt;&lt;/a&gt;fghijk&lt;/span&gt;&lt;/a&gt;</para>

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

      <para><literallayout>
          Essai2 avec &lt;span&gt;
          <emphasis role="bold">
            &lt;a name="appserver"&gt;&lt;/a&gt;
          </emphasis>
          JOnAS&lt;/span&gt;&lt;/a&gt;&lt;/span&gt; The element named
          above was found in a context where it is not allowed. This
          could mean that you have incorrectly nested elements -- such
          as a "style" element in the "body" section instead of inside
          "head" -- or two elements that overlap (which is not allowed).
          One common cause for this error is the use of XHTML syntax in
          HTML documents. Due to HTML's rules of implicitly closed
          elements, this error can create cascading effects. For
          instance, using XHTML's "self-closing" tags for "meta" and
          "link" in the "head" section of a HTML document may cause the
          parser to infer the end of the "head" section and the
          beginning of the "body" section (where "link" and "meta" are
          not allowed; hence the reported error).
        </literallayout></para>

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

  <chapter xml:id="xmlmind">
    <info>
      <title>L'outillage de développement: XMLmind</title>
    </info>

    <section>
      <info>
        <title>Utiliser l'outil XMLmind (xxe)</title>
      </info>

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

      <para>Pour l'utiliser, il suffit de lancer la commande:
      <command>xxe</command></para>

      <para>On peut trouver de la documentation en français dans le <link
      xlink:href="file:///download/xxe/user_fr/index.html"> Guide de
      l'utilisateur de l'éditeur XML de XMLmind V3.4 </link></para>
    </section>

    <section>
      <info>
        <title>Personnaliser son environement XMLmind</title>
      </info>

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

      <para>Pour personnaliser son environement xmlmind il faut:</para>

      <itemizedlist>
        <listitem>
          <para>positionner dans les options d'edit
          (Options&gt;Options&gt;Edit) le toggle XInclude.</para>
        </listitem>

        <listitem>
          <para>positionner l'option UTF-8 dans le menu Options - Preferences
          - Save</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <info>
        <title>Naviguer d'un document à l'autre</title>
      </info>

      <para><itemizedlist>
          <listitem>
            <para>pour modifier le document inclu :</para>

            <para>cliquer sur une partie de celui-ci puis Edit &gt; Document
            Reference&gt; Edit Referenced Document</para>

            <para>ou cliquer sur l'icone de droite que l'on voit
            ci-dessous</para>

            <figure>
              <info>
                <title></title>
              </info>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="../../resources/images/editbuttons.gif"></imagedata>
                </imageobject>
              </mediaobject>
            </figure>
          </listitem>

          <listitem>
            <para>pour revenir au document référençant :</para>

            <para>cliquer sur l'icone de gauche de la figure ci-dessus (en
            haut à gauche de l'ecran)</para>

            <para>ou faire Edit &gt; Document Reference&gt; Edit Referencing
            Document.</para>
          </listitem>
        </itemizedlist></para>
    </section>
  </chapter>

  <chapter xml:id="docbook">
    <info>
      <title>Apprendre à maitriser DocBook</title>
    </info>

    <para>On enumere ici quelques recettes pour resoudre des pbs courants.
    Cette liste n'est absolument pas exhaustive. On peut trouver de la
    documentation utile dans plusieurs documents listes en <xref
    linkend="refs" /> . On peut aussi s'inspirer de ce document lui-meme,
    ecrit bien sur en docbook. Il suffit de comparer le source .xml et le
    rendu en html. La feuille de style utilisee est la meme que pour les docs
    JOnAS.</para>

    <section xml:id="docbook.français">
      <info>
        <title>Faire une documentation en Français</title>
      </info>

      <section>
        <info>
          <title>Declaration d'un book en français</title>
        </info>

        <para>Comment faire pour qu'aprés transformation on obtienne dans une
        documentation française chapitre au lieu de chapter, table des
        matières au lieu de table of contents etc...?</para>

        <para>Il suffit de rajouter l'attribut xml:lang="fr" dans l'élément
        book ainsi:</para>

        <screen>&lt;book xml:lang="fr"&gt;</screen>
      </section>

      <section>
        <info>
          <title>Saisie des caractères accentués</title>
        </info>

        <para>Il a été décidé d'utiliser le format UTF-8 pour écrire
        l'ensemble de la doc, y compris les documents en français. Ceci
        implique de bien faire attention à positionner dans l'en-tête du
        fichier xml:</para>

        <screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</screen>

        <para>De même, lorsqu'on utilisera un éditeur, il faudra être certain
        qu'il travaille dans le bon format. Il faut aussi s'assurer que le
        format du fichier est bien UTF-8. On peut pour cela utiliser gedit et
        sauver le fichier dans le bon format. Avec xxe, il faut positionner
        l'option save en UTF-8 (menu Options - Preferences - Save) sinon on va
        se retrouver avec un document converti dans le mauvais format!</para>

        <para>Avant de lancer un éditeur (emacs ou xxe par exemple): Il faut
        positionner</para>

        <screen>export LC_CTYPE=fr_FR.UTF-8</screen>

        <para>On pourra alors lire et écrire des accents sans problème:
        àùûéôâîèêç § ÀÙÛÉÇÔÂÎÈÊ→</para>
      </section>
    </section>

    <section>
      <title>Représenter un fragment de code</title>

      <para>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 <emphasis>telquel </emphasis>(les
      coupures de lignes doivent être respectées).</para>

      <para>En DocBook nous pouvons utiliser les éléments &lt;<emphasis
      role="bold">screen</emphasis>&gt;,<emphasis
      role="bold">&lt;programlisting&gt;</emphasis>, <emphasis
      role="bold">&lt;literallayout&gt; </emphasis>qui ont à peu prés les
      mêmes caractéristiques.</para>

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

      <para>Nous reservons :</para>

      <variablelist>
        <varlistentry>
          <term>&lt;programlisting&gt;</term>

          <listitem>
            <para>pour la présentation d'une portion de code assez long, et
            qui sera affiché avec un scrollbar en html.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>&lt;literallayout&gt;</term>

          <listitem>
            <para>pour la présentation d'une portion de code plus court, et
            qui sera affiché sans scrollbar en html.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>&lt;screen&gt;</term>

          <listitem>
            <para>pour la présentation d'une copie d'écran, sans
            scrollbar.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Par exemple, dans le document présent nous réservons <emphasis
      role="bold">&lt;literallayout&gt;</emphasis> pour montrer du code
      docBook et &lt;<emphasis role="bold">screen</emphasis>&gt; pour le
      résultat du code précédent cf <xref linkend="documentpart" />.</para>
    </section>

    <section xml:id="tableaux">
      <info>
        <title>Faire des tableaux</title>
      </info>

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

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

      <para>Exemple de tableau très simple, avec le code xml correspondant
      :</para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>header 1</entry>

              <entry>header 2</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>elt 1</entry>

              <entry>description 1</entry>
            </row>

            <row>
              <entry>elt 2</entry>

              <entry>description 2</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <literallayout>
&lt;informaltable&gt;
  &lt;tgroup cols="2"&gt;
    &lt;thead&gt;
      &lt;row&gt;
        &lt;entry&gt;header 1&lt;/entry&gt;
        &lt;entry&gt;header 2&lt;/entry&gt;
      &lt;/row&gt;
    &lt;/thead&gt;
    &lt;tbody&gt;
      &lt;row&gt;
        &lt;entry&gt;elt 1&lt;/entry&gt;
        &lt;entry&gt;description 1&lt;/entry&gt;
      &lt;/row&gt;
      &lt;row&gt;
        &lt;entry&gt;elt 2&lt;/entry&gt;
        &lt;entry&gt;description 2&lt;/entry&gt;
      &lt;/row&gt;
    &lt;/tbody&gt;
  &lt;/tgroup&gt;
&lt;/informaltable&gt;
      </literallayout>
    </section>

    <section xml:id="liens">
      <info>
        <title>Faire des liens</title>
      </info>

      <section xml:id="documentpart">
        <info>
          <title>lien vers une partie du document (xref)</title>
        </info>

        <para>il faut positionnner l'attribut <emphasis>linkend</emphasis>
        avec l' <emphasis>xml:id</emphasis> de la section, chapitre,... ou on
        veut aller la chaine sensible sera le titre de la
        section,chapitre,...</para>

        <para>exemple d'un lien xref vers une section :</para>

        <literallayout>
se reporter au 
&lt;xref linkend="conventions" /&gt;
...
&lt;chapter xml:id="conventions"/&gt;
  &lt;title&gt;Conventions et règles diverses&lt;/title&gt;
        </literallayout>

        <para>donnera:</para>

        <screen>se reporter au <xref linkend="conventions" /></screen>
      </section>

      <section>
        <info>
          <title>autres types de lien (link)</title>
        </info>

        <para>Cet élément contient une chaine de caracteres qui deviendra
        sensible et un attribut <emphasis>linkend</emphasis> contenant l'
        <emphasis>xml:id</emphasis> de l'endoit ou on veut aller</para>

        <para>Exemple de lien vers une partie du document :</para>

        <literallayout>
se reporter à &lt;link linkend="partiesection"&gt; une partie de la section suivante&lt;/link&gt;
... 
&lt;para xml:id="partiesection"&gt;
        </literallayout>

        <para>donnera :</para>

        <screen>se reporter à <link linkend="partiesection">une partie de la section suivante</link></screen>

        <para>On peut l'utiliser pour faire un lien sur une url ou pour faire
        un lien sur une autre partie de la doc dont on connait la position
        relative par rapport au document courant.</para>

        <para>Exemple de lien vers un document externe à la doc JOnAS :</para>

        <literallayout>
exemple de lien vers &lt;link xlink:href="http://www.objectweb.org/"&gt;objectweb&lt;/link&gt;
        </literallayout>

        <para>donnera :</para>

        <screen>exemple de lien vers <link
            xlink:href="http://www.objectweb.org/">objectweb</link></screen>

        <para>On peut aussi faire un lien vers un autre document en relatif
        par rapport à celui-ci. Il suffira de mettre comme valeur de xlink:ref
        une chaine du style: ../doc_en/toto.html.</para>

        <para>Pour faire un lien vers un autre document de la doc JOnAS dont
        on connait la localisation de l'html généré:</para>

        <literallayout>
the &lt;link xlink:href="command_guide.html#commands.jonas.jonasadmin"&gt;jonas admin command&lt;/link&gt; 
        </literallayout>

        <para>donnera:</para>

        <screen>the <link
            xlink:href="command_guide.html#commands.jonas.jonasadmin">jonas admin command</link></screen>
      </section>
    </section>

    <section xml:id="exemple-commente">
      <info>
        <title>Faire un exemple commenté d'un fichier de conf</title>
      </info>

      <para>Pour obtenir ceci:</para>

      <screen>carol.protocols=jrmp <co xml:id="id1" />
carol.jrmp.url=rmi://localhost:1099 <co xml:id="id2" />
        <calloutlist>
          <callout arearefs="id1">
            <para>choice of the protocol or list of protocols</para>
          </callout>
          <callout arearefs="id2">
            <para>connexion url to the RMI registry</para>
          </callout>
        </calloutlist></screen>

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

      <para>suivi d'un &lt;calloutlist&gt; ayant le meme nombre d'éléments
      &lt;callout&gt; que d'annotations, chacun des <emphasis
      role="bold">callout</emphasis> ayant un attribut <emphasis
      role="bold">arearefs</emphasis> contenant l' <emphasis
      role="bold">xml:id</emphasis> de l'annotation correspondante.</para>

      <para>Voici le code xml correspondant:</para>

      <literallayout>
carol.protocols=jrmp &lt;co xml:id="id1" /&gt;
carol.jrmp.url=rmi://localhost:1099 &lt;co xml:id="id2"  /&gt;
&lt;calloutlist&gt; 
  &lt;callout arearefs="id1"&gt; 
    &lt;para&gt;choice of the protocol or list of protocols&lt;/para&gt;
  &lt;/callout&gt; 
  &lt;callout arearefs="id2"&gt; 
    &lt;para&gt;connexion url to the RMI registry&lt;/para&gt; 
  &lt;/callout&gt; 
&lt;/calloutlist&gt;
      </literallayout>

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

    <section xml:id="notes-bas-page">
      <info>
        <title>Insérer des notes de bas de page</title>
      </info>

      <para><itemizedlist>
          <listitem>
            <para>inserer une nouvelle note :</para>

            <itemizedlist>
              <listitem>
                <para>insérer un élément <emphasis
                role="bold">footnote</emphasis></para>
              </listitem>
            </itemizedlist>

            <screen>Voici un exemple de note <footnote xml:id="firstnote">
                <para>première note de bas de page</para>
              </footnote></screen>

            <para>code correspondant:</para>

            <literallayout>
Voici un exemple de note &lt;footnote xml:id="firstnote"&gt; 
    &lt;para&gt;première note de bas de page&lt;/para&gt;
  &lt;/footnote&gt;
            </literallayout>
          </listitem>

          <listitem>
            <para>insérer une note pointant sur une note existante:</para>

            <itemizedlist>
              <listitem>
                <para>positionner l'attribut <emphasis
                role="bold">xml:id</emphasis> de la note existante</para>
              </listitem>

              <listitem>
                <para>insérer un élément <emphasis
                role="bold">footnoteref</emphasis> l'attribut <emphasis
                role="bold">linkend</emphasis> a pour valeur l'attribut xml:id
                de la note existante</para>
              </listitem>
            </itemizedlist>

            <screen>Voici une note <footnoteref linkend="firstnote" /> référençant la précédente</screen>

            <para>code correspondant:</para>

            <literallayout>
Voici une note&lt;footnoteref linkend="firstnote" /&gt; référençant la précédente
            </literallayout>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Insérer des images</title>

      <para>Nous préconisons d'utiliser un élément &lt;mediaobject&gt;
      incluant un élément &lt;imagedata&gt;</para>

      <para>pour positionner correctement les tailles aussi bien pour le
      format HTML que PDF voir le <link
      xlink:href="http://www.sagehill.net/docbookxsl/ImageSizing.html">chapitre
      Image sizing</link></para>

      <para><mediaobject>
          <imageobject>
            <imagedata fileref="../../resources/images/versioning-general-schema.png"
                       scalefit="1" width="85%"></imagedata>
          </imageobject>
        </mediaobject>Exemple d'image avec l'attribut width positionné à
      85%:</para>

      <para>Voici le code xml correspondant:</para>

      <para><literallayout> &lt;para&gt;&lt;mediaobject&gt;
      &lt;imageobject&gt;
        &lt;imagedata width="85%" scalefit="1" fileref="../../resources/images/versioning-general-schema.png"&gt;&lt;/imagedata&gt;
      &lt;/imageobject&gt;
    &lt;/mediaobject&gt;&lt;/para&gt;</literallayout>la même avec width =
      50%:</para>

      <para><mediaobject>
          <imageobject>
            <imagedata fileref="../../resources/images/versioning-general-schema.png"
                       scalefit="1" width="50%"></imagedata>
          </imageobject>
        </mediaobject></para>
    </section>

    <section xml:id="variables">
      <info>
        <title>Utiliser des chaines de caracteres variables</title>
      </info>

      <para>le fichier <filename>variables.xml</filename> 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...):</para>

      <para xml:id="partiesection">Ce fichier est consitué d'une section et
      d'un ensemble de lignes contenant des déclarations du style :
      <literallayout>&lt;phrase xml:id="objectweb"&gt;ObjectwebV2&lt;/phrase&gt;</literallayout>
      <emphasis>objectweb</emphasis> étant l'identifiant utilisé dans les
      documents sources, et <emphasis>ObjectwebV2</emphasis> la valeur qui
      sera finalement remplacée dans le fichier html (ou pdf) généré.</para>

      <para>Dans la document xml, il faudra insérer, à la place de
      <emphasis>ObjectwebV2</emphasis>, un texte qui ressemble à :</para>

      <literallayout>&lt;xi:include href="../variables.xml" xpointer="objectweb"/&gt;</literallayout>

      <para>Avec xxe, on fera simplement :</para>

      <orderedlist continuation="restarts" inheritnum="ignore">
        <listitem>
          <para>cliquer sur la chaine voulue dans variable.xml</para>
        </listitem>

        <listitem>
          <para>faire Edit&gt;Document Reference&gt;Copy as reference</para>
        </listitem>

        <listitem>
          <para>faire paste a l'endroit voulu dans le document
          referencant</para>
        </listitem>
      </orderedlist>
    </section>

    <section xml:id="include">
      <info>
        <title>Inclure un document xml dans un autre</title>
      </info>

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

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

      <para>Un exemple :</para>

      <literallayout>&lt;xi:include href="ra/JMSRA.xml"/&gt;</literallayout>

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

    <section>
      <info>
        <title>Zone apparaissant avec barre de défilement</title>
      </info>

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

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

      <para>Exemple de présentation du fichier jonas.properties:</para>

      <programlisting>
# 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
      </programlisting>

      <para>Voici le résultat attendu (dans un document HTML):</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="../../resources/images/defilement.gif"></imagedata>
        </imageobject>
      </mediaobject>
    </section>

    <section>
      <info>
        <title>Générer un document pdf avec des bookmarks</title>
      </info>

      <para>Il suffit de rajouter dans la feuille de style fo.xsl:</para>

      <screen>
        &lt;xsl:param name="fop1.extensions" select="1"/&gt;
      </screen>
    </section>
  </chapter>

  <chapter xml:id="conventions">
    <info>
      <title>Conventions et règles diverses</title>
    </info>

    <section>
      <info>
        <title>Bonnes pratiques</title>
      </info>

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

      <itemizedlist>
        <listitem>
          <para>Eviter le style direct du genre</para>

          <para>First of all, <emphasis role="bold">we</emphasis> need to
          define or <emphasis role="bold">you</emphasis> have to type the
          following command.</para>

          <para>(sauf dans un tutorial)</para>
        </listitem>

        <listitem>
          <para>limiter les liens, utiliser l'inclusion</para>
        </listitem>

        <listitem>
          <para>Conventions typographiques pour les differents éléments
          textuels:</para>

          <para>d'une manière générale la politique est de caracteriser
          l'élément textuel via un element DocBook ce qui permettra de
          s'occupper de la présentation de cet élément de manière fine dans la
          feuille de style <filename class="extension">.css</filename>
          .</para>

          <para>Donc, éviter <emphasis>emphasis</emphasis> et utiliser les
          éléments possibles de DocBook comme <emphasis
          role="bold">filename,</emphasis> <emphasis
          role="bold">classname</emphasis> , <emphasis
          role="bold">property</emphasis> ,etc...</para>

          <para>dans xmlmind pour connaitre les éléments possibles surligner
          la chaine de caractères puis faire <keycap>ctrl-T</keycap> (ou
          <guimenu>convert)</guimenu> le nom des éléments apparaissent dans la
          fenêtre à droite. A noter que certains élément peuvent être encore
          précisé via l'éditeur d'attributs: à l'élément <emphasis
          role="bold">filename</emphasis> on peut préciser l'attribut
          <emphasis role="bold">class</emphasis> avec les valeurs suivantes:
          <filename>directory, devicefile, extension,etc...</filename></para>

          <itemizedlist>
            <listitem>
              <para>nom de directory:</para>

              <para><filename
              class="directory">$JONAS_ROOT/conf</filename></para>

              <para>utiliser <emphasis role="bold">filename</emphasis> +
              attribut class= <emphasis
              role="bold">directory</emphasis></para>
            </listitem>

            <listitem>
              <para>nom de fichier</para>

              <para><filename>jonas.properties</filename></para>

              <para>utiliser <emphasis role="bold">filename</emphasis></para>
            </listitem>

            <listitem>
              <para>nom de propriete de configuration</para>

              <para><emphasis role="bold"> <property>jonas.services</property>
              </emphasis></para>

              <para>utiliser <emphasis role="bold">property</emphasis></para>
            </listitem>

            <listitem>
              <para>nom de variable d'environnement</para>

              <para><envar>JONAS_ROOT</envar></para>

              <para>utiliser <emphasis role="bold">envar</emphasis></para>
            </listitem>

            <listitem>
              <para>valeur de variable d'environnement</para>

              <para>/home/jr48</para>

              <para>dépend du type de la valeur , si c'est un path
              filename+directory si c'est une valeur prendre <emphasis
              role="bold">literal</emphasis></para>
            </listitem>

            <listitem>
              <para>nom de classe java ou package :</para>

              <para><classname> javax.mail.internet.MimePartDataSource
              </classname> .</para>

              <para>utiliser <emphasis role="bold">classname</emphasis></para>
            </listitem>

            <listitem>
              <para>nom d'interface java:</para>

              <para><interfacename>javax.ejb.SessionSynchronization
              </interfacename> .</para>

              <para>utiliser <emphasis
              role="bold">interfacename</emphasis></para>
            </listitem>
          </itemizedlist>

          <para>Voici un tableau permettant de controler le rendu pour les
          différents éléments textuels(compte tenu de notre feuille de style
          utilisée) :</para>

          <informaltable>
            <tgroup cols="2">
              <thead>
                <row>
                  <entry>elements/attributs</entry>

                  <entry>rendu du texte</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>texte</entry>

                  <entry>texte</entry>
                </row>

                <row>
                  <entry>&lt;emphasis&gt;texte&lt;/emphasis&gt;</entry>

                  <entry><emphasis>texte</emphasis></entry>
                </row>

                <row>
                  <entry>&lt;emphasis
                  role="bold"&gt;texte&lt;/emphasis&gt;</entry>

                  <entry><emphasis role="bold">texte</emphasis></entry>
                </row>

                <row>
                  <entry>&lt;filename&gt;texte&lt;/filename&gt;</entry>

                  <entry><filename>texte</filename></entry>
                </row>

                <row>
                  <entry>&lt;filename
                  class="directory"&gt;texte&lt;/filename&gt;</entry>

                  <entry><filename class="directory">texte</filename></entry>
                </row>

                <row>
                  <entry>&lt;filename
                  class="extension"&gt;texte&lt;/filename&gt;</entry>

                  <entry><filename class="extension">texte</filename></entry>
                </row>

                <row>
                  <entry>&lt;literal&gt;texte&lt;/literal&gt;</entry>

                  <entry><literal>texte</literal></entry>
                </row>

                <row>
                  <entry>&lt;classname&gt;texte&lt;/classname&gt;</entry>

                  <entry><classname>texte</classname></entry>
                </row>

                <row>
                  <entry>&lt;interfacename&gt;texte&lt;/interfacename&gt;</entry>

                  <entry><interfacename>texte</interfacename></entry>
                </row>

                <row>
                  <entry>&lt;command&gt;texte&lt;/command&gt;</entry>

                  <entry><command>texte</command></entry>
                </row>

                <row>
                  <entry>&lt;envar&gt;texte&lt;/envar&gt;</entry>

                  <entry><envar>texte</envar></entry>
                </row>

                <row>
                  <entry>&lt;interfacename&gt;texte&lt;/interfacename&gt;</entry>

                  <entry><interfacename>texte</interfacename></entry>
                </row>

                <row>
                  <entry>&lt;package&gt;texte&lt;/package&gt;</entry>

                  <entry><package>texte</package></entry>
                </row>

                <row>
                  <entry>&lt;property&gt;texte&lt;/property&gt;</entry>

                  <entry><property>texte</property></entry>
                </row>

                <row>
                  <entry>&lt;function&gt;texte&lt;/function&gt;</entry>

                  <entry><function>texte</function></entry>
                </row>

                <row>
                  <entry>&lt;link
                  xlink:href="http://wiki.jonas.objectweb.org"&gt;texte&lt;/link&gt;</entry>

                  <entry><link xlink:href="http://wiki.jonas.objectweb.org">
                  texte </link></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>voici <link
          xlink:href="http://www.docbook.org/tdg/en/html/part2.html"> la liste
          des éléments possibles </link></para>
        </listitem>

        <listitem>
          <para>Identifier les éléments qui risquent d'etre référencés ou
          inclu (chapitre, section, autres) en positionant l'attribut id de
          l'élément XML DocBook correspondant :</para>

          <para><screen>&lt;section xml:id="config.cmi"&gt;</screen> L'id
          choisi doit être unique dans le document entier.</para>

          <para>On prend la convention de nommage suivante: prendre un nom qui
          reflète la structure arborescente des sources (comme les package
          java).</para>
        </listitem>
      </itemizedlist>
    </section>
  </chapter>

  <appendix xml:id="refs">
    <info>
      <title>References documentation externe</title>
    </info>

    <para><variablelist>
        <varlistentry>
          <term><link
          xlink:href="http://www.sagehill.net/docbookxsl/index.html"> DocBook
          XSL: The Complete Guide </link></term>

          <listitem>
            <para>C'est la bible! un peu mastoc mais il faut y revenir
            régulièrement il est incontournable...</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link
          xlink:href="http://docbook.org/tdg5/en/html/docbook.html"> DocBook:
          The Definitive Guide </link></term>

          <listitem>
            <para>pas mal non plus on y trouve parfois des choses différentes
            que dans le précédent</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://feloy.free.fr/dbmanual/book1.html">
          Manuel DocBook (en français) </link></term>

          <listitem>
            <para>a le mérite d'être en français...</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link xlink:href="http://www.docbook.org/docs/howto/"> DocBook
          5.0 The Transition Guide </link></term>

          <listitem>
            <para>Pour le passage à docBook 5</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link
          xlink:href="www.mathrice.org/rencontres/mars.2007/presentations/DocBook-Mathrice.pdf">
          DocBook-XML et éditeur XMLmind </link> (en français)</term>

          <listitem>
            <para>excellente introduction rapide à DocBook (une sorte de
            DocBook pour les nuls...)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link
          xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html">
          HTML Parameter Reference </link></term>

          <listitem>
            <para>documentation de réference pour parametrisation des DocBook
            XSL HTML stylesheets (pour generer des documents HTML</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link
          xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/fo/index.html">
          FO Parameter Reference </link></term>

          <listitem>
            <para>documentation de réference pour paramétrisation des DocBook
            XSL FO stylesheets (pour generer des documents XSL-FO utilisé pour
            des documents finaux au format PDF.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><link
          xlink:href="http://www.sagehill.net/docbookxsl/UsingCSS.html"> Using
          CSS to style HTML </link></term>

          <listitem>
            <para>comment utiliser css pour personnaliser un document
            HTML</para>
          </listitem>
        </varlistentry>
      </variablelist></para>
  </appendix>
</book>
