Copyright © 2007 ObjectWeb consortium
Résumé
Ce document présente l'infrastructure mise en place pour fabriquer la documentation JOnAS en utilisant la technologie DocBook XML.
Table des matières
Ce document s'adresse aux contributeurs (nombreux, espérons le..) qui auront à participer à l'amélioration de la documentation JOnAS.
Il est fortement conseiller 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 profiter de ce changement pour intégrer la documentation dans SVN.
Le but du jeu est de faire passer petit à petit la documentation actuelle dans ce format.
Le document est organisé de la manière suivante:
Chapitre 1 , L'infrastructure de documentation JOnAS 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)
Chapitre 2, L'outillage de développement décrit brièvement l'utilisation d'un outil possible et conseillé pour écrire la doc en DocBook
Chapitre 3, Apprendre à maitriser 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.
Chapitre 4, Conventions et règles diverses, 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.
Les trois premiers chapitres sont spécifiques à la documentation JOnAS les trois autres peuvent être utilisés dans un autre contexte.
Last but not least, comme vous le voyez ce document est écrit en français contrairement a reste de la documentation JOnAS qui est écrite prioritairement en anglais. Il devra être traduit à terme.
Table des matières
La documentation JOnAS compose un nouveau module SVN jonas_doc du repository jonas4. Il apparaît pour la première fois dans la branche jonas_4_8.
Dans ce projet jonas_doc va être mis en oeuvre le DocBook Xslt Publishing Model qui est décrit dans ce diagramme
Le module SVN jonas_doc a la structure suivante:
Avec:
contient les fichiers html correspondant à l'ancienne doc JOnAS
contient les fichiers xml correspondants aux documents anglais écrits en docBook
contient les fichiers xml correspondants aux documents français écrits en docBook
contients les images, les stylesheets xls
ou css
contient le processeur Apache FOP utilisé pour fabriquer les documents pdf.
La génération de la doc se fait via ant en général sous eclipse (build.xml). Il existe une target par guide:
target | description | état de la doc |
configguide | permet de générer le configuration guide | relue par l'équipe JOnAS |
commandguide | génération du command référence guide | écrite, à relire |
adminguide | génération de l'administration guide | à écrire |
guides | génération des différents guides | n/a |
howto | génération du JOnAS Documentation How To (c'est à dire ce document) | en constante évolution |
dist | génération de la doc avec prise en compte de l'ancienne doc non encore réécrite | n/a |
war | permet de refabriquer le war
jonas-doc-en.war pour JOnAS | n/a |
Pour chaque guide il est possible de générer :
un document html unique via la target transform1html
un document partitonné en chunk via la target transformchunkhtml
les précédents documents avec le look du site JOnAS via la target integrated
un document en format XSL-FO[1] (formatting object) via la target transform1fo
un document pdf à partir du document XSL-FO via la target pdf
Les targets transform1html et transformchunkhtml s'expriment en terme de la target transform qui par défaut utilise xalan. Mais comme xalan ne sait pas traiter correctement les directives xi:include utilisées pour faire l'inclusion de documents xml un préprocessing est nécéssaire avec la commande xmllint.[2]
la target transform1 est équivalente à transform mais utilise xlstproc.
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 incluent d'autres que l'on considère se trouver sous /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl ce qui est une adhérence à notre environnement. |
Génération des guides (target guides):
L'ensemble des fichiers résultants de la génération de la
documentation se trouve dans la directory output/generation
du projet eclipse
jonasdocbook. Voici la structure d'ouput:
chunk où se trouve le document ségmentés en chunks
chunk-integrated: le même que précédemment mais intégré au site JOnAS
fo: se trouve le document sous forme XSL-FO
html: où se trouve le document sous forme d'un fichier html monolithique
integrated: le même que précédemment mais intégré au site JOnAS
pdf: le document en format pdf.
Génération du jonas-doc-en.war
pour JOnAS
(target war)
la target dist récupère les documents
html sous dist/integrated (ancienne doc comprise)
pdf sous dist/pdf
la target war contruit
jonas-doc-en.war
sous dist/war (la tagerget war depend de
dist).
Deux machines rentrent en ligne de compte jonas.forge.objectweb.org et jonas.objectweb.org
Sur ces deux machines la structure est identique:
dans la directory current :
doc la doc html générée (structure identique à output/dist/integrated)
jdoc la javadoc générée
dans la directory doc:
howto : encore les howto! pourquoi?....
jonas-dox : doc générée par dowygen sur JOnAS 4.4.0 !!
tutorial : un tutorial JOnAS 3.3
tutorial_old :un tutorial JOnAS 2.4
tutorial_portug : un mini tutorial JOnAS 3.3 en portugais
un ensemble de documents en pdf dont ceux correspondants au guides écrits en DocBook:
La publication de la doc se fait en deux phases:
Mise à jour de jonas.forge.objectweb.org pour cela il faut utiliser (sur linux) le gestionnaire de fichiers nautilus:
se positionner sur la machine locale sur<directory_projet_jonasdocbook>/output/dist/doc-en
sélectionner l'ensemble des fichiers (Ctrll A)
faire Edit>Copy
se connecter sur la machine distante jonas.forge.objectweb.org sur la directory /current/doc:
Faire File>Connect to Server il apparait une fenêtre du style
Dans la fenetre qui s'ouvre faire File>Paste
faire Edit>Copy sur la machine locale sur<directory_projet_jonasdocbook>/output/dist/resources
faire File>Paste sur jonas.forge.objectweb.org sur la directory /current/doc:
refaire l'opération pour le fichier <directory_projet_jonasdocbook>src/resources/index.hml
se positionner sur la machine locale
sur le directory <directory_projet_jonasdocbook>/output/dist/pdf
faire Edit>Copy pour tous les documents pdf que l'on veut transférer
se connecter sur la machine distante jonas.forge.objectweb.org sur la directory /doc
faire Edit>Paste pour les documents pdf
Mise à jour de jonas.objectweb.org :
Se mettre sous l'onglet admin de la forge JOnAS:
Cliquer sur le bouton de publication "Push Project Web Site from Development to Production Now!"
L'opération est souvent longue et on obtient une page web ressemblant à ça:
Results of your command: At revision 10320. Buildfile: build.xml clean: [delete] Deleted 1 directory from /var/www/work/jonas/update.10332/public_html [delete] Deleted 1 directory from /var/www/work/jonas/update.10332/cgi-bin [delete] Deleting 38 files from /var/www/work/jonas/web/common [delete] Deleted 6 directories from /var/www/work/jonas/web/common [delete] Deleting: /var/www/work/jonas/web/.build unzip_common_web: [unzip] Expanding: /var/www/work/jonas/web/common_web.zip into /var/www/work/jonas/web/common prepare: [mkdir] Created dir: /var/www/work/jonas/update.10332/public_html [mkdir] Created dir: /var/www/work/jonas/update.10332/cgi-bin [copy] Copying 1 file to /var/www/work/jonas/update.10332/public_html [copy] Copying 30 files to /var/www/work/jonas/update.10332/public_html/images [copy] Copying 220 files to /var/www/work/jonas/update.10332/public_html [copy] Copying 1 file to /var/www/work/jonas/update.10332/public_html/js [copy] Copying 2 files to /var/www/work/jonas/update.10332/cgi-bin check: [xmlvalidate] 20 file(s) have been successfully validated. html_print: real_html: [style] Transforming into /var/www/work/jonas/update.10332/public_html [style] Processing /var/www/work/jonas/web/xml/root/contacts.xml to /var/www/work/jonas/update.10332/public_html/contacts_print.html [style] Loading stylesheet /var/www/work/jonas/web/common/stylesheets/printable.xsl [style] Processing /var/www/work/jonas/web/xml/root/contrib.xml to /var/www/work/jonas/update.10332/public_html/contrib_print.html [style] Processing /var/www/work/jonas/web/xml/root/doc/index.xml to /var/www/work/jonas/update.10332/public_html/doc/index_print.html [style] Processing /var/www/work/jonas/web/xml/root/download/index.xml to /var/www/work/jonas/update.10332/public_html/download/index_print.html [style] Processing /var/www/work/jonas/web/xml/root/form.xml to /var/www/work/jonas/update.10332/public_html/form_print.html [style] Processing /var/www/work/jonas/web/xml/root/history.xml to /var/www/work/jonas/update.10332/public_html/history_print.html [style] Processing /var/www/work/jonas/web/xml/root/index_old.xml to /var/www/work/jonas/update.10332/public_html/index_old_print.html [style] Processing /var/www/work/jonas/web/xml/root/license.xml to /var/www/work/jonas/update.10332/public_html/license_print.html [style] Processing /var/www/work/jonas/web/xml/root/partners.xml to /var/www/work/jonas/update.10332/public_html/partners_print.html [style] Processing /var/www/work/jonas/web/xml/root/prototypes.xml to /var/www/work/jonas/update.10332/public_html/prototypes_print.html [style] Processing /var/www/work/jonas/web/xml/root/releaserules.xml to /var/www/work/jonas/update.10332/public_html/releaserules_print.html [style] Processing /var/www/work/jonas/web/xml/root/success.xml to /var/www/work/jonas/update.10332/public_html/success_print.html [style] Processing /var/www/work/jonas/web/xml/root/support.xml to /var/www/work/jonas/update.10332/public_html/support_print.html [style] Processing /var/www/work/jonas/web/xml/root/team.xml to /var/www/work/jonas/update.10332/public_html/team_print.html [style] Processing /var/www/work/jonas/web/xml/root/tests.xml to /var/www/work/jonas/update.10332/public_html/tests_print.html [style] Processing /var/www/work/jonas/web/xml/root/thanks.xml to /var/www/work/jonas/update.10332/public_html/thanks_print.html [style] Processing /var/www/work/jonas/web/xml/root/tools.xml to /var/www/work/jonas/update.10332/public_html/tools_print.html [style] Processing /var/www/work/jonas/web/xml/root/voteform.xml to /var/www/work/jonas/update.10332/public_html/voteform_print.html [style] Processing /var/www/work/jonas/web/xml/root/workplan.xml to /var/www/work/jonas/update.10332/public_html/workplan_print.html html: real_html: [style] Transforming into /var/www/work/jonas/update.10332/public_html [style] Processing /var/www/work/jonas/web/xml/root/contacts.xml to /var/www/work/jonas/update.10332/public_html/contacts.html [style] Loading stylesheet /var/www/work/jonas/web/common/stylesheets/browsable.xsl [style] Processing /var/www/work/jonas/web/xml/root/contrib.xml to /var/www/work/jonas/update.10332/public_html/contrib.html [style] Processing /var/www/work/jonas/web/xml/root/doc/index.xml to /var/www/work/jonas/update.10332/public_html/doc/index.html [style] Processing /var/www/work/jonas/web/xml/root/download/index.xml to /var/www/work/jonas/update.10332/public_html/download/index.html [style] Processing /var/www/work/jonas/web/xml/root/form.xml to /var/www/work/jonas/update.10332/public_html/form.html [style] Processing /var/www/work/jonas/web/xml/root/history.xml to /var/www/work/jonas/update.10332/public_html/history.html [style] Processing /var/www/work/jonas/web/xml/root/index_old.xml to /var/www/work/jonas/update.10332/public_html/index_old.html [style] Processing /var/www/work/jonas/web/xml/root/license.xml to /var/www/work/jonas/update.10332/public_html/license.html [style] Processing /var/www/work/jonas/web/xml/root/partners.xml to /var/www/work/jonas/update.10332/public_html/partners.html [style] Processing /var/www/work/jonas/web/xml/root/prototypes.xml to /var/www/work/jonas/update.10332/public_html/prototypes.html [style] Processing /var/www/work/jonas/web/xml/root/releaserules.xml to /var/www/work/jonas/update.10332/public_html/releaserules.html [style] Processing /var/www/work/jonas/web/xml/root/success.xml to /var/www/work/jonas/update.10332/public_html/success.html [style] Processing /var/www/work/jonas/web/xml/root/support.xml to /var/www/work/jonas/update.10332/public_html/support.html [style] Processing /var/www/work/jonas/web/xml/root/team.xml to /var/www/work/jonas/update.10332/public_html/team.html [style] Processing /var/www/work/jonas/web/xml/root/tests.xml to /var/www/work/jonas/update.10332/public_html/tests.html [style] Processing /var/www/work/jonas/web/xml/root/thanks.xml to /var/www/work/jonas/update.10332/public_html/thanks.html [style] Processing /var/www/work/jonas/web/xml/root/tools.xml to /var/www/work/jonas/update.10332/public_html/tools.html [style] Processing /var/www/work/jonas/web/xml/root/voteform.xml to /var/www/work/jonas/update.10332/public_html/voteform.html [style] Processing /var/www/work/jonas/web/xml/root/workplan.xml to /var/www/work/jonas/update.10332/public_html/workplan.html publish: [touch] Creating /var/www/work/jonas/web/.build BUILD SUCCESSFUL Total time: 10 seconds building file list ... done ./ JonasPublic.htm common.css contacts.html contacts_print.html contrib.html contrib_print.html form.html form_print.html history.html history_print.html index.htm index.html index.php index_old.html index_old_print.html jonasDocumentation.htm jonasDownload.htm jonasFormulaire.htm jonasHistory.htm jonasHomePage.htm jonasLicence.htm jonasNews.htm jonasOPL1_0.htm jonasPartners.htm jonasSuccessStories.htm jonasToolsIndex.htm jonasWhitePaper.htm license.html license_print.html partners.html partners_print.html prototypes.html prototypes_print.html releaserules.html releaserules_print.html site_preview.jpg success.html success_print.html support.html support_print.html team.html team_print.html tests.html tests_print.html thanks.html thanks_print.html tools.html tools_print.html voteform.html voteform_print.html workplan.html workplan_print.html current/doc/ current/doc/doc-en/ current/doc/doc-en/integrated/ current/doc/doc-en/integrated/Admin.html current/doc/doc-en/integrated/Cmi.html current/doc/doc-en/integrated/Deployer.html current/doc/doc-en/integrated/Domain.html current/doc/doc-en/integrated/JOnASWP.html current/doc/doc-en/integrated/JOnASWebServices.html current/doc/doc-en/integrated/MBeans.html current/doc/doc-en/integrated/PG_Client.html current/doc/doc-en/integrated/PG_Connector.html current/doc/doc-en/integrated/PG_Deployment.html current/doc/doc-en/integrated/PG_EarDeployment.html current/doc/doc-en/integrated/PG_Entity.html current/doc/doc-en/integrated/PG_Environment.html current/doc/doc-en/integrated/PG_J2eeApps.html current/doc/doc-en/integrated/PG_JmsGuide.html current/doc/doc-en/integrated/PG_LogModules.html current/doc/doc-en/integrated/PG_MsgDrvBean.html current/doc/doc-en/integrated/PG_Packaging.html current/doc/doc-en/integrated/PG_Security.html current/doc/doc-en/integrated/PG_Session.html current/doc/doc-en/integrated/PG_Transaction.html current/doc/doc-en/integrated/PG_War.html current/doc/doc-en/integrated/Services.html current/doc/doc-en/integrated/TMF.html current/doc/doc-en/integrated/ant-ejbjar.html current/doc/doc-en/integrated/clusterd.html current/doc/doc-en/integrated/clustering.html current/doc/doc-en/integrated/command_guide.html current/doc/doc-en/integrated/common.css current/doc/doc-en/integrated/configuration_guide.html current/doc/doc-en/integrated/fdf.html current/doc/doc-en/integrated/getting_started_guide.html current/doc/doc-en/integrated/index.html current/doc/doc-en/integrated/migration_guide.html current/doc/doc-en/integrated/.DAV/ current/doc/doc-en/integrated/howto/ current/doc/doc-en/integrated/howto/Clustering.html current/doc/doc-en/integrated/howto/Compile.html current/doc/doc-en/integrated/howto/Firewall.html current/doc/doc-en/integrated/howto/InteropCORBA.html current/doc/doc-en/integrated/howto/InteropWebloIIOP.html current/doc/doc-en/integrated/howto/InteropWebloWS.html current/doc/doc-en/integrated/howto/J2EEWebServicesDevelopment.html current/doc/doc-en/integrated/howto/JMSClustering.html current/doc/doc-en/integrated/howto/JORAMdistributed.html current/doc/doc-en/integrated/howto/JORAMdistributed_JOnAS_4_1.html current/doc/doc-en/integrated/howto/JOnASEmbHowTo.html current/doc/doc-en/integrated/howto/JOnASTransactionRecoveryHowTo.html current/doc/doc-en/integrated/howto/JSR160_support.html current/doc/doc-en/integrated/howto/JonasMBeansHowTo.html current/doc/doc-en/integrated/howto/MC4J.html current/doc/doc-en/integrated/howto/Migration.html current/doc/doc-en/integrated/howto/MigrationNewWorldCruise.html current/doc/doc-en/integrated/howto/WebServices_JOnAS_3_X.html current/doc/doc-en/integrated/howto/WebSphereMQ.html current/doc/doc-en/integrated/howto/Win32Service.html current/doc/doc-en/integrated/howto/common.css current/doc/doc-en/integrated/howto/howtoXdoclet.html current/doc/doc-en/integrated/howto/install_j2ee.html current/doc/doc-en/integrated/howto/install_jonas.html current/doc/doc-en/integrated/howto/install_juddi.html current/doc/doc-en/integrated/howto/.DAV/ current/doc/doc-en/integrated/howto/clusterdetails/ current/doc/doc-en/integrated/howto/clusterdetails/AutomaticClusterConfiguration.html current/doc/doc-en/integrated/howto/clusterdetails/ManualClusterConfiguration.html current/doc/doc-en/integrated/howto/clusterdetails/c-jdbc.html current/doc/doc-en/integrated/howto/clusterdetails/director.html current/doc/doc-en/integrated/howto/clusterdetails/mod_jk2-to-mod_jk.html current/doc/doc-en/integrated/howto/clusterdetails/mod_jk2_embeddedtomcat.html current/doc/doc-en/integrated/howto/clusterdetails/mod_jk_embeddedtomcat.html current/doc/doc-en/integrated/howto/clusterdetails/sequoia.html current/doc/doc-en/integrated/howto/clusterdetails/.DAV/ current/doc/doc-en/integrated/howto/emb-images/ current/doc/doc-en/integrated/howto/emb-images/emb-component.png current/doc/doc-en/integrated/howto/emb-images/emb-deps.png current/doc/doc-en/integrated/howto/emb-images/mfb.png current/doc/doc-en/integrated/howto/emb-images/.DAV/ current/doc/doc-en/integrated/howto/emb-images/src/ current/doc/doc-en/integrated/howto/emb-images/src/emb-component.svg current/doc/doc-en/integrated/howto/emb-images/src/emb-deps.svg current/doc/doc-en/integrated/howto/emb-images/src/mfb.svg current/doc/doc-en/integrated/howto/emb-images/src/.DAV/ current/doc/doc-en/integrated/howto/images/ current/doc/doc-en/integrated/howto/images/clusterfiles/ current/doc/doc-en/integrated/howto/images/clusterfiles/Apache.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Archi1.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Archi2.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Archi3.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Archi4.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Archi5.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Architecture.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/EJBCont.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/FullJOnAS.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/JOnASEJB.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/JOnASWeb.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Node.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/Thumbs.db current/doc/doc-en/integrated/howto/images/clusterfiles/WebCont.jpg current/doc/doc-en/integrated/howto/images/clusterfiles/common.css current/doc/doc-en/integrated/howto/images/clusterfiles/sampleCluster2Screen.GIF current/doc/doc-en/integrated/howto/images/clusterfiles/.DAV/ current/doc/doc-en/integrated/howto/images/jmsclustering/ current/doc/doc-en/integrated/howto/images/jmsclustering/joram.jpg current/doc/doc-en/integrated/howto/images/jmsclustering/joram_ha.jpg current/doc/doc-en/integrated/howto/images/jmsclustering/mdb.jpg current/doc/doc-en/integrated/howto/images/jmsclustering/mdb_config.jpg current/doc/doc-en/integrated/howto/images/jmsclustering/queue.jpg current/doc/doc-en/integrated/howto/images/jmsclustering/topic.jpg current/doc/doc-en/integrated/howto/images/jmsclustering/.DAV/ current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/ current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg1.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg2.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg3.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg4.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg5.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg6.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg7.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/recovimg8.jpg current/doc/doc-en/integrated/howto/images/jonastransactionrecoveryhowto/.DAV/ current/doc/doc-en/integrated/howto/ws/ current/doc/doc-en/integrated/howto/ws/sample-deploy.wsdd current/doc/doc-en/integrated/howto/ws/sample-server-config.wsdd current/doc/doc-en/integrated/howto/ws/sample-web.xml current/doc/doc-en/integrated/howto/ws/.DAV/ current/doc/doc-en/pdf/ current/doc/doc-en/pdf/command_guide.pdf current/doc/doc-en/pdf/configuration_guide.pdf current/doc/doc-en/pdf/getting_started_guide.pdf current/doc/doc-en/pdf/howtoJOnASDocBook.pdf current/doc/doc-en/pdf/migration_guide.pdf current/doc/doc-en/pdf/.DAV/ current/doc/resources/ current/doc/resources/images/ current/doc/resources/images/AreaGraph.png current/doc/resources/images/JonasAdmin.gif current/doc/resources/images/JonasAreas.png current/doc/resources/images/WP_distr.gif current/doc/resources/images/admintree.gif current/doc/resources/images/caution.png current/doc/resources/images/classloaders.png current/doc/resources/images/cluster1.gif current/doc/resources/images/clusterd.gif current/doc/resources/images/clustering.gif current/doc/resources/images/cmi-cluster-stub.gif current/doc/resources/images/cmi-jndi.gif current/doc/resources/images/cmi.gif current/doc/resources/images/connect.gif current/doc/resources/images/defilement.gif current/doc/resources/images/defilement.gif.save current/doc/resources/images/deployment.gif current/doc/resources/images/domain_new.gif current/doc/resources/images/draft.png current/doc/resources/images/eb_img_31.gif current/doc/resources/images/editbuttons.gif current/doc/resources/images/favicon.ico current/doc/resources/images/firstpage.gif current/doc/resources/images/forgeadmin.gif current/doc/resources/images/j2ee.gif current/doc/resources/images/jcaarch.gif current/doc/resources/images/jconsole.png current/doc/resources/images/jonas48repscenarios.jpg current/doc/resources/images/jonasTree.png current/doc/resources/images/jonas_doc.gif current/doc/resources/images/jonasarch.gif current/doc/resources/images/logo_jonas.jpg current/doc/resources/images/logoow.gif current/doc/resources/images/myTomcatCluster.gif current/doc/resources/images/myloadbalancer.gif current/doc/resources/images/note.png current/doc/resources/images/output.gif current/doc/resources/images/pix.gif current/doc/resources/images/publish.gif current/doc/resources/images/roles1.gif current/doc/resources/images/sfsb-rep.jpg current/doc/resources/images/ws_client.jpg current/doc/resources/images/ws_endpoint.jpg current/doc/resources/images/.DAV/ current/doc/resources/images/callouts/ current/doc/resources/images/callouts/1.png current/doc/resources/images/callouts/10.png current/doc/resources/images/callouts/11.png current/doc/resources/images/callouts/12.png current/doc/resources/images/callouts/13.png current/doc/resources/images/callouts/14.png current/doc/resources/images/callouts/15.png current/doc/resources/images/callouts/2.png current/doc/resources/images/callouts/3.png current/doc/resources/images/callouts/4.png current/doc/resources/images/callouts/5.png current/doc/resources/images/callouts/6.png current/doc/resources/images/callouts/7.png current/doc/resources/images/callouts/8.png current/doc/resources/images/callouts/9.png current/doc/resources/images/callouts/.DAV/ current/doc/resources/wikifiles/ current/doc/resources/wikifiles/arch-tmp.png current/doc/resources/wikifiles/bg.png current/doc/resources/wikifiles/bg_v.png current/doc/resources/wikifiles/bg_v_i.png current/doc/resources/wikifiles/browserdetect.js current/doc/resources/wikifiles/dynamic_menu.js current/doc/resources/wikifiles/feeds.png current/doc/resources/wikifiles/header.jpg current/doc/resources/wikifiles/jonas-5-small-blue.png current/doc/resources/wikifiles/prototype.js current/doc/resources/wikifiles/skin.js current/doc/resources/wikifiles/style.css current/doc/resources/wikifiles/xwiki.js current/doc/resources/wikifiles/.DAV/ demos/ demos/demo1/ demos/demo1/JOnASDemo.htm demos/demo1/JOnASDemo.swf demos/demo2/ demos/demo2/jonas_checkout7.htm demos/demo2/jonas_checkout7.swf doc/ doc/JOnAS_Support.pdf doc/command_guide.pdf doc/configuration_guide.pdf doc/disclaimer.txt doc/getting_started_guide.pdf doc/index.htm doc/index.html doc/index_print.html doc/migration_guide.pdf doc/architecture/ doc/architecture/JOnASArchi.html doc/architecture/JOnASArchi.pdf doc/architecture/common.css doc/architecture/images/ doc/architecture/images/JOnASJMX.gif doc/architecture/images/cluster1.gif doc/architecture/images/jonas_cmp.gif doc/architecture/images/jonasarch.gif doc/architecture/images/logo_jonas.jpg doc/howto/HowtoClientTrans.html doc/howto/HowtoDriver.html doc/howto/HowtoServiceNT.html doc/howto/JettyJonas.html doc/howto/MC4J.html doc/howto/SecurityExample.html doc/howto/Tomcat.html doc/howto/TomcatJonas2_6.html doc/howto/common.css doc/howto/howtodriver.gif doc/howto/jboss4_X-to-jonas4_X/ doc/howto/jboss4_X-to-jonas4_X/Makefile doc/howto/jboss4_X-to-jonas4_X/chapters.sgml doc/howto/jboss4_X-to-jonas4_X/guide.sgml doc/howto/jboss4_X-to-jonas4_X/style.sgml doc/howto/jboss4_X-to-jonas4_X/html/ doc/howto/jboss4_X-to-jonas4_X/html/cmp-configuration.html doc/howto/jboss4_X-to-jonas4_X/html/common-bean-configuration.html doc/howto/jboss4_X-to-jonas4_X/html/configuration-overview.html doc/howto/jboss4_X-to-jonas4_X/html/declaring-finders.html doc/howto/jboss4_X-to-jonas4_X/html/deployment-descriptors.html doc/howto/jboss4_X-to-jonas4_X/html/ejb-references.html doc/howto/jboss4_X-to-jonas4_X/html/further-reading.html doc/howto/jboss4_X-to-jonas4_X/html/generating-container-classes.html doc/howto/jboss4_X-to-jonas4_X/html/index.html doc/howto/jboss4_X-to-jonas4_X/html/introduction.html doc/howto/jboss4_X-to-jonas4_X/html/jboss2jonas.html doc/howto/jboss4_X-to-jonas4_X/html/message-driven-beans.html doc/howto/jboss4_X-to-jonas4_X/html/user-transactions.html doc/misc/ doc/misc/lbfts/ doc/misc/lbfts/LBFT.html doc/misc/lbfts/image002.gif doc/tests/ doc/tests/common.css doc/tests/index.html doc/tests/jonas-2-6-1.html doc/tests/jonas-3-0-beta0.html doc/tests/jonas-3-0.html doc/tests/jonas-3-1.html doc/tests/jonas-3-2.html doc/tests/jonas-3-3.html doc/tests/JONAS_4_0_0/ doc/tests/JONAS_4_0_0/README.txt doc/tests/JONAS_4_0_0/cmi-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_0_0/iiop-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_0_0/jeremie-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_0_0/jrmp-Linux-PostgreSQL-to-rhaps5-1.4.2_03_BEA-rhaps.html doc/tests/JONAS_4_0_0/jrmp-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_0_0/jrmp-Linux-postgreslocal-1.4.2_04-Standalone.html doc/tests/JONAS_4_1/ doc/tests/JONAS_4_1/README.txt doc/tests/JONAS_4_1/cmi-Linux-HSQL1-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/cmi-Linux-MysqlWallis-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/cmi-Linux-OracleAcores-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/cmi-Linux-PostgresLocalMururoa-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/cmi-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/iiop-Linux-MysqlWallis-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/iiop-Linux-OracleAcores-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/iiop-Linux-OracleAcores-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/iiop-Linux-PostgresLocalMururoa-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/iiop-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/iiop-Windows 2000-PostgreSQL1-1.4.2_03-Tomcat.html doc/tests/JONAS_4_1/jeremie-Linux-HSQL1-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jeremie-Linux-MysqlWallis-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jeremie-Linux-OracleAcores-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jeremie-Linux-OracleAcores-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/jeremie-Linux-Postgres-1.4.2_04-Standalone.html doc/tests/JONAS_4_1/jeremie-Linux-PostgresLocalMururoa-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jeremie-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/jrmp-Linux-HSQL1-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jrmp-Linux-MysqlWallis-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jrmp-Linux-OracleAcores-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jrmp-Linux-OracleAcores-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/jrmp-Linux-Postgres-1.4.2_04-Standalone.html doc/tests/JONAS_4_1/jrmp-Linux-PostgresLocalMururoa-1.4.2_04-jetty5.html doc/tests/JONAS_4_1/jrmp-Linux-PostgresLocalMururoa-1.4.2_04-tomcat5.html doc/tests/JONAS_4_1/jrmp-Windows 2000-HSQL1-1.4.2_03-Tomcat.html doc/tests/JONAS_4_1_2/ doc/tests/JONAS_4_1_2/cmi-Linux-HSQL1-1.4.2_05-jetty5.html doc/tests/JONAS_4_1_2/cmi-Linux-MysqlLocal-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/cmi-Linux-PostgresLocalMururoa-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/iiop-Linux-HSQL1-1.4.2_05-jetty5.html doc/tests/JONAS_4_1_2/iiop-Linux-MysqlLocal-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/iiop-Linux-OracleAcores-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/iiop-Linux-PostgresLocalMururoa-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/jeremie-Linux-HSQL1-1.4.2_05-jetty5.html doc/tests/JONAS_4_1_2/jeremie-Linux-MysqlLocal-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/jeremie-Linux-OracleAcores-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/jeremie-Linux-PostgresLocalMururoa-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/jrmp-Linux-HSQL1-1.4.2_05-jetty5.html doc/tests/JONAS_4_1_2/jrmp-Linux-MysqlLocal-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/jrmp-Linux-OracleAcores-1.4.2_05-tomcat5.html doc/tests/JONAS_4_1_2/jrmp-Linux-PostgresLocalMururoa-1.4.2_05-tomcat5.html doc/tests/jonas-3-3-6/ doc/tests/jonas-3-3-6/README.txt doc/tests/jonas-3-3-6/cmi-Linux-OracleAcores-1.4.2_03-jetty.html doc/tests/jonas-3-3-6/cmi-Linux-PostgresLocalMururoa-1.4.2_03-tomcat.html doc/tests/jonas-3-3-6/iiop-Linux-OracleAcores-1.4.2_03-jetty.html doc/tests/jonas-3-3-6/iiop-Linux-OracleAcores-1.4.2_03-tomcat.html doc/tests/jonas-3-3-6/iiop-Linux-PostgresLocalMururoa-1.4.2_03-tomcat.html doc/tests/jonas-3-3-6/jeremie-Linux-OracleAcores-1.4.2_03-jetty.html doc/tests/jonas-3-3-6/jeremie-Linux-PostgresLocalMururoa-1.4.2_03-tomcat.html doc/tests/jonas-3-3-6/jrmp-Linux-OracleAcores-1.4.2_03-jetty.html doc/tests/jonas-3-3-6/jrmp-Linux-OracleAcores.properties-1.4.2_01-Standalone.html doc/tests/jonas-3-3-6/jrmp-Linux-PostgresLocalMururoa-1.4.1_02-tomcat.html doc/tests/jonas-3-3-6/jrmp-Linux-PostgresLocalMururoa-1.4.2_03-tomcat.html doc/tests/jonas-3-3-6/jrmp-Linux-postgreslocal-1.4.2-Standalone.html doc/tests/jonas3.3/ doc/tests/jonas3.3/cmilpt.html doc/tests/jonas3.3/iioplot.html doc/tests/jonas3.3/jersoj.html doc/tests/jonas3.3/jrmplms.html doc/tests/jonas3.3/jrmplpj.html doc/tests/jonas3.3/jrmplpt.html doc/tutorial/index.html download/index.html download/index_print.html dtds/ dtds/jonas-client_3_2.dtd dtds/jonas-connector_3_0.dtd dtds/jonas-ejb-jar_2_4.dtd dtds/jonas-ejb-jar_2_5.dtd dtds/jonas-ejb-jar_3_0.dtd dtds/jonas-ejb-jar_3_2.dtd dtds/jonas-realm_1_0.dtd dtds/jonas-web-app_2_6.dtd dtds/jonas-web-app_3_1.dtd images/ images/ast.gif images/bodyconsortium.gif images/bodyforge.gif images/bodymiddleware.gif images/bodymyobjectweb.gif images/bodyproject.gif images/bodysolutions.gif images/bodytemplate.gif images/bodywelcome.gif images/coming.gif images/favicon.ico images/fond1.gif images/jonas.jpg images/latest.gif images/logo_jonas.jpg images/logo_jonas2.jpg images/logoow.gif images/news.gif images/objectweb.gif images/pix.gif images/printer.gif images/theserverside.gif images/top.gif images/valid-html401.png images/vcss.gif images/menu/ images/menu/barre.gif images/menu/boutonok1.gif images/menu/boutonok2.gif images/menu/boutonprint1.gif images/menu/boutonprint2.gif images/menu/boutonsearch1.gif images/menu/boutonsearch2.gif images/menu/boutonsubscribe1.gif images/menu/boutonsubscribe2.gif images/partners/ images/partners/MDKsoft.jpg images/partners/RHCLogoHRJ.jpg images/partners/bull.png images/partners/dyade.gif images/partners/enhydra.gif images/partners/evidian.gif images/partners/exo-platform-logo-200x75.gif images/partners/francetelecom.jpg images/partners/francetelecomrd.jpg images/partners/inria.gif images/partners/libelis.gif images/partners/librados-FtoI-348-x-90.gif images/partners/logo_BSF_200.gif images/partners/logo_scub.gif images/partners/lynx.jpg images/partners/scalagent.jpg images/partners/tfe_0160.gif images/success/ images/success/ATSLogo.jpg images/success/LBS-Logo.png images/success/NeWare_splash.gif images/success/NeoSavant_SucceedFaster.gif images/success/QUIPSY.gif images/success/efb2.gif images/success/emm_logo_web.jpg images/success/hisi.jpg images/success/ingenosya.gif images/success/kovair.gif images/success/logocotranet.jpg images/success/lutris.gif images/success/openuss.jpg images/success/sportmaschine_234_60_de.gif images/success/teraportal.gif images/success/venetica.gif js/ js/objectweb.js ns/ ns/jonas-application_4_1_4.xsd ns/jonas-client_4_0.xsd ns/jonas-client_4_1.xsd ns/jonas-client_4_1_2.xsd ns/jonas-client_4_1_4.xsd ns/jonas-client_4_2.xsd ns/jonas-connector_4_0.xsd ns/jonas-connector_4_1.xsd ns/jonas-connector_4_2.xsd ns/jonas-connector_4_4.xsd ns/jonas-deployment-plan_0_1.xsd ns/jonas-domain_4_7.xsd ns/jonas-ejb-jar_4_0.xsd ns/jonas-ejb-jar_4_1.xsd ns/jonas-ejb-jar_4_1_2.xsd ns/jonas-ejb-jar_4_1_4.xsd ns/jonas-ejb-jar_4_2.xsd ns/jonas-ejb-jar_4_3.xsd ns/jonas-ejb-jar_4_6.xsd ns/jonas-ejb-jar_4_7.xsd ns/jonas-ejb-jar_4_8.xsd ns/jonas-web-app_4_0.xsd ns/jonas-web-app_4_1.xsd ns/jonas-web-app_4_1_2.xsd ns/jonas-web-app_4_1_4.xsd ns/jonas-web-app_4_2.xsd ns/jonas_j2ee_4_0.xsd ns/jonas_j2ee_4_1.xsd ns/jonas_j2ee_4_1_2.xsd ns/jonas_j2ee_4_1_4.xsd ns/jonas_j2ee_4_2.xsd ns/jonas_j2ee_web_services_4_0.xsd ns/jonas_j2ee_web_services_4_1_2.xsd ns/jonas_j2ee_web_services_4_1_4.xsd ns/jonas_j2ee_web_services_4_2.xsd ns/jonas_j2ee_web_services_4_5.xsd deleting current/doc/doc-en/integrated/GettingStarted.html sent 11907775 bytes received 10822 bytes 366726.06 bytes/sec total size is 229315432 speedup is 19.24 building file list ... done ./ questionnaire1.cgi vote.cgi sent 2542 bytes received 70 bytes 5224.00 bytes/sec total size is 9002 speedup is 3.45 Files successfully copied to production Web server: http://jonas.objectweb.org/
Il y a trois niveaux de personnalisation possibles
personnalisation des transformations Docbook->autres formats (HTML ou XSL-FO)
L'idée est de fournir une couche de personnalisation (Customization layer) 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...
pour une transformation DocBook->HTML les paramètres que l'on peut positionner sont décrits ici.
pour une transformation DocBook-> XSL-FO les paramètres positionnables sont décrits ici.
les feuilles de styles utilisées pour la doc JOnAS se
trouve dans la dirictory resources
et sont:
utilisée dans la génération d'un document monolitique
utilisée dans la génération d'un document segmenté. (elle aurait besoin d'amélioration).
utilisée dans la génération d'un document pdf
pour trouver des renseignements sur les Customization layer se reporter au Chapter 8. Customization methods du livre DocBook XSL: The Complete Guide - 3rd Edition
personnalisation de la présentation des documents HTML
Il faut mieux éviter de positionner des caractéristiques de
présentation dans le document DocBook lui même mais plutôt de les
positionner dans des Cascading Style Sheets (.css).
On peut se reporter au chapitre Using CSS to style HTML pour plus de renseignements
Il y a deux feuilles de styles utilisées
Utilisée pour les documents html non intégré au site JOnAS
Utilisée pour les documents html intégré au site JOnAS
personnalisation de la présentation des documents pdf
Pour cette personnalisation il faut apprendre à connaitre le langage XSL-FO!
on peut se reporter:
au tutoriel W3C Introduction to XSL-FO
La feuille de style
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.
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:
Essai2 avec <span><a name="appserver"></a>JOnAS</span></a></span>
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).
Le workaround utilisé est de procésser les fichier html générés et remplacer <a name="appserver"></a> par rien (car par chance seule la string variable JOnAS apparit dans des href)
Table des matières
via la command xxe
un manuel d'utilisateur en français se trouve ici
Dans notre environnement standard se trouve xmlMind 3.1.0 qui permet de faire des transformations docBook -> html (en 1 ou plusieurs fichiers) via le menu DocBook> Convert document > Convert to HTML [one page] cf Section 2.3.1, « Générer un html monolithique à partir du xml »
La conversion docBook -> pdf demande un addon supplementaire mais seuls des addons pour la version xmlMind 3.5.1 sont accessible sur le site et dans la version xmlMind 3.5.1 les menus de conversion précédents n'existent que dans la version professionnelle...
Pour pouvoir bénéficier d'un squelette de document nous préconisons d'utiliser un template spécifique quand on veut écrire un nouveau book.
Ceci permet d'avoir pour chacun des livres une structure identique pour la partie bookinfo.
Pour personnaliser son environement xmlmind il faut:
se créer une directory ~/.xxe/addon et y copier les deux fichiers suivants:
jonasbook.xxe:
<?xml version="1.0" encoding="UTF-8"?> <configuration name="jonasbook" xmlns="http://www.xmlmind.com/xmleditor/schema/configuration" xmlns:cfg="http://www.xmlmind.com/xmleditor/schema/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.xmlmind.com/xmleditor/schema/configuration ../../../../addon/config/configuration/xsd/configuration.xsd"> <detect> <dtdPublicId>-//XMLmind//DTD Example1//EN</dtdPublicId> </detect> <template name="JOnAS book" location="jonasbook.xml" /> </configuration>
jonasbook.xml:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <book> <bookinfo> <title></title> <authorgroup> <author> <surname>Coq</surname> <firstname>Philippe</firstname> </author> <author> <surname>Danes</surname> <firstname>Adriana</firstname> </author> <corpauthor>JOnAS Team</corpauthor> </authorgroup> <copyright> <year>2007</year> <holder>ObjectWeb consortium</holder> </copyright> <abstract> <para>This document ....</para> </abstract> <date>April 2007</date> </bookinfo> </book>
positionner dans les options d'edit (Options>Options>Edit) le toggle XInclude.
Ces customisations permettent:
de bénéficier d'un template de book pour JOnAS quand on fait File > New...
de bénéficier des fonctionialites d'inclusion de tout ou partie de document.
DocBook> Convert document > Convert to HTML [one page]
Utiliser la commande
convertdoc docb.toHTML configuration_guide.xml -u output
Par défaut il y a un chunk par section de niveau 1 dans un chapitre. ils sont nommés :
index.html
ch01.html
ch01s01.html
Pour avoir le contrôle des noms de fichiers générés par l'outil positionner l'attribut id de la section qui délimitera un chunk
Si on veut un chunk pour les sections de niveau 1 et 2 il faut faire la commande suivante:
convertdoc -p chunk.section.depth 2 docb.toHTML configuration_guide.xml -u output
ils sont nommés:
index.html
ch01.html
ch01s01.html
ch01s02.html
ch01s02s01.html
...
Table des matières
Il n'est pas dans mes intention d'écrire un manuel DocBook je vais indiquer quelques liens qui peuvent être utiles.
Ensuite je voudrais aider à resoudre quelques problèmes plus ou moins communs
DocBook XSL: The Complete Guide
C'est la bible! un peu mastoc mais il faut y revenir régulièrement il est incontournable...
pas mal non plus on y trouve parfois des choses différentes que dans le précédent
a le mérite d'être en français...
DocBook-XML et éditeur XMLmind (en français)
excellente introduction rapide à DocBook (une sorte de DocBook pour les nuls...)
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...?
Il suffit de rajouter l'attribut lang="fr" dans l'élément book ainsi:
<book lang="fr">
liens à l'interieur d'un document
il y a deux manières de faire:
xref
il faut positionnner l'attribut linkend avec l'id de la section, chapitre,... ou on veut aller la chaine sensible sera le titre de la section,chapitre,...
l'insertion d'un élément xref ne peut se faire via le menu.
exemple d'un lien xref vers une section ???
link
cet élément contient une chaine de caracteres qui deviendra sensible et un attribut linkend contenant l'id de l'endoit ou on veut aller
l'insertion peut se faire en surlignant la chaine à rendre sensible et utiliser le menu a>link
exemple d'un lien link vers une partie de la section suivante
documentation plus complete ici
liens à l'exterieur d'un document
ulink
l'insertion peut se faire en surlignant la chaine à rendre sensible et utiliser le menu a>ulink puis position l'attribut url via l'editeur d'attribut
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
exemple de lien vers objectweb
exemple de lien vers le chapitre glossaire
olink
est la manière de faire si on veut faire un lien vers une partie d'un autre document xml. la mise en oeuvre est compliquée (voir ici)
Pour obtenir ceci:
carol.protocols=jrmpcarol.jrmp.url=rmi://localhost:1099
![]()
Il faut un <screen> (ou <programlisting>) avec des éléments <co> à l'endroit que l'on veut annoter avec un identifiant comme attribut id
suivi d'un <calloutlist> ayant le meme nombre d'éléments <callout> que d'annotations, chacun des calloutayant un attribut arearefs contenant l'id de l'annotation correspondante.
Voici le code xml correspondant:
<para><screen>carol.protocols=jrmp <co id="id1" /> carol.jrmp.url=rmi://localhost:1099 <co id="id2" /> </screen><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></para>
A noter que l'insertion des annotations dans la ligne se fait trés simplement avec xxe.
inserer une nouvelle note :
insérer un élément footnote
exemple : voici un exemple de note[3]
code correspondant:
<para>exemple : voici un exemple de note<footnote> <para>première note de bas de page</para> </footnote></para>
insérer une note pointant sur une note existante:
positionner l'attribut id de la note existante
insérer un élément footnoteref l'attribut linkend a pour valeur l'attribut id de la note existante
exemple: voici une note[3] référençant la précédente
code correspondant:
<para>exemple: voici une note<footnoteref linkend="firstnote" /> référençant la précédente</para>
le fichier variables.xml
est un fichier
caché utilisé uniquement pour définir le contenu de chaines de
caractères qui risquent de changer (nom de projet, Numéro de version,
etc...):
le fichier variables.xml est consitué d'une section et d'un ensemble de <para> ressemblant à: <para><phrase id="objectweb">ObjectwebV2</phrase></para>
avec
ObjectwebV2 étant la chaine à expanser
id="objectweb" étant un identifiant introduit via l'éditeur d'attributs dans xxe
Le plus simple pour créer une nouvelle chaine est de copier insérer après un <para> existant et de modifier la chaine et l'id (qui doit être unique dans le document.
Pour inserer une chaine dans un autre document xml :
cliquer sur la chaine voulue dans variable.xml
faire Edit>Document Reference>Copy as reference
faire paste a l'endroit voulu dans le document referencant
Pour produire le document html correspondant
se mettre sous le document referencant
faire DocBook> Convert Document >Convert to HTML
Si Convert to HTML -> génération dans directory out de index.html, html.css, ch01s01.html et de la directoty images
Si Convert to HTML [one page] -> génération a l'endroit voulu sous un nom voulu
Si Convert to HTML [one page, no TOC] -> idem que précédemment sans la TOC
cette manip est en partie manuelle. Sous xmlmind :
s'assurer que dans les options d'edit (Options>Options>Edit) le toggle XInclude est positionné
se mettre dans le document a référencer et clicker quelque part.
faire Ctrl+Shift+C (Edit>Document Reference>Copy as reference )
faire paste dans le document qui reference
sous eclipse ou emacs supprimer la partie xpointer="..." genere
pour modifier le document inclu :
cliquer sur une partie de celui-ci puis Edit > Document Reference> Edit Referenced Document
ou cliquer sur l'icone de droite que l'on voit ci-dessous
pour revenir au document référençant :
cliquer sur l'icone de gauche de la figure ci-dessus (en haut à gauche de l'ecran)
ou faire Edit > Document Reference> Edit Referencing Document.
Pour obtenir ceci une barre de défilement permettant de scroller une zone d'information importante :
la barre de défilement n'apparaitra que dans le document html, évidemment:
jonas check JONAS_BASE set to /home/coqp/jb - JONAS_ROOT value: /home/coqp/JONAS_4_8_5 - JONAS_BASE value: /home/coqp/JONAS_4_8_5 - JOnAS Services: registry,jmx,jtm,db,dbm,security,resource,ejb,ws,web,ear - Contents of 'jonas.properties': jonas.service.security.realm.jndi.registration = false jonas.service.db.user1 = jonas:jonas jonas.service.mail.factories = jonas.service.jtm.remote = false jonas.service.jms.mom = org.objectweb.jonas_jms.JmsAdminForJoram jonas.service.ejb.auto-genic = true jonas.service.resource.threadwaittimeout = 60 jonas.service.ejb.descriptors = jonas.service.mail.class = org.objectweb.jonas.mail.MailServiceImpl jonas.service.resource.resources = jonas.service.web.descriptors = jonas.service.ws.factory.class = org.objectweb.jonas.ws.axis.JAxisServiceFactory jonas.security.manager = true jonas.service.ws.wsdlhandlers = file1 jonas.service.ha.jgroups.conf = jgroups-ha.xml jonas.service.registry.mode = collocated jonas.service.dbm.datasources = HSQL1 jonas.service.resource.class = org.objectweb.jonas.resource.ResourceServiceImpl jonas.service.security.class = org.objectweb.jonas.security.JonasSecurityServiceImpl jonas.service.resource.parsingwithvalidation = true jonas.service.discovery.class = org.objectweb.jonas.discovery.DiscoveryServiceImpl jonas.service.ear.descriptors = jonas.service.thread.class = org.objectweb.area.jonas.AreaService jonas.service.resource.execworktimeout = 0 jonas.service.registry.class = org.objectweb.jonas.registry.RegistryServiceImpl jonas.service.jms.queues = sampleQueue jonas.service.discovery.multicast.address = 224.224.224.224 jonas.service.db.port = 9001 jonas.service.ejb.parsingwithvalidation = true jonas.service.web.parsingwithvalidation = true jonas.security.context.check.keystoreFile = /tmp/keystore jonas.service.thread.ejbareaname = EJB jonas.service.db.dbname = db_jonas jonas.service.ejb.autoloaddir = autoload jonas.service.jms.class = org.objectweb.jonas.jms.JmsServiceImpl jonas.security.propagation = true jonas.service.discovery.multicast.port = 9080 jonas.security.context.check = false jonas.service.thread.file = jonas_areas.xml jonas.service.discovery.ttl = 1 jonas.service.ha.datasource = jdbc_1 jonas.service.security.ws.realm = memrlm_1 jonas.service.ejb.minworkthreads = 3 jonas.service.dbm.class = org.objectweb.jonas.dbm.DataBaseServiceImpl jonas.service.ws.wsgen.generator.factory = org.objectweb.jonas_ws.wsgen.generator.ews.EWSGeneratorFactory jonas.service.ws.class = org.objectweb.jonas.ws.axis.AxisWSServiceImpl jonas.service.resource.autoloaddir = autoload jonas.service.jmx.class = org.objectweb.jonas.jmx.JmxServiceImpl jonas.log.configfile = trace jonas.service.ejb.maxworkthreads = 80 jonas.service.resource.minworkthreads = 5 jonas.service.web.autoloaddir = autoload jonas.service.ha.timeout = 600 jonas.service.ha.gcl = jgroups jonas.service.ear.parsingwithvalidation = true jonas.service.ear.autoloaddir = autoload jonas.service.resource.maxworkthreads = 80 jonas.service.ws.parsingwithvalidation = true jonas.security.context.check.keystorePass = keystorepass jonas.service.db.class = org.objectweb.jonas.db.hsqldb.HsqlDBServiceImpl jonas.service.ear.class = org.objectweb.jonas.ear.EarServiceImpl jonas.service.jtm.class = org.objectweb.jonas.jtm.TransactionServiceImpl jonas.service.ha.class = org.objectweb.jonas.ha.HaServiceImpl jonas.service.ejb.threadwaittimeout = 60 jonas.service.ha.jgroups.groupname = jonas-rep jonas.csiv2.propagation = true jonas.service.ejb.class = org.objectweb.jonas.container.EJBServiceImpl jonas.service.jms.topics = sampleTopic jonas.service.jtm.timeout = 60 jonas.service.jms.collocated = true jonas.service.security.csiv2.realm = memrlm_1 jonas.service.web.class = org.objectweb.jonas.web.wrapper.catalina55.CatalinaJWebContainerServiceWrapper jonas.security.context.check.alias = FB jonas.service.discovery.source.port = 9888 jonas.services = registry,jmx,jtm,db,dbm,security,resource,ejb,ws,web,ear jonas.transaction.propagation = true - Check 'jonas-realm.xml': File is present. - Check 'JORAM configuration': Ok The JOnAS environment seems correct.
Ce n'est pas un problème DocBook mais un problème de présentation qui peut être résolu via la feuille de style.css
Ici je passe par un élément <programlisting> car dans l'html généré il apparaitra comme une classe programlisting que l'on pourra customiser dans la feuille de style .css
code DocBook associé:
<programlisting> jonas check JONAS_BASE set to /home/coqp/jb - JONAS_ROOT value: /home/coqp/JONAS_4_8_5 - JONAS_BASE value: /home/coqp/JONAS_4_8_5 ..... ..... .... </programlisting>
code html généré:
<pre class="programlisting">jonas check JONAS_BASE set to /home/coqp/jb - JONAS_ROOT value: /home/coqp/JONAS_4_8_5 - JONAS_BASE value: /home/coqp/JONAS_4_8_5 <pre class="programlisting">jonas check JONAS_BASE set to /home/coqp/jb - JONAS_ROOT value: /home/coqp/JONAS_4_8_5 ..... ..... .... </pre> </p> </div>
code css associé:
.programlisting {
overflow:auto;width:75%;height:200px;
border-top: 5px solid #FFFFFF;
border-bottom: 5px solid #FFFFFF;
border-color:black;
margin: 10px;
padding:5px;
}
Voici le résultat attendu (dans un document HTML):
Table des matières
dans ce § un certain nombre de règles sont énumérées afin d'obtenir une documentation homogène:
Eviter le style direct du genre
First of all, we need to define or you have to type the following command.
(sauf dans un tutorial)
limiter les liens, utiliser l'inclusion
Conventions typographiques pour les differents éléments textuels:
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 .css
.
Donc, éviter emphasis et utiliser les éléments possibles de DocBook comme filename, classname, property,etc...
dans xmlmind pour connaitre les éléments possibles surligner
la chaine de caractères puis faire ctrl-T (ou
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 filename on peut préciser l'attribut
class avec les valeurs suivantes:
directory, devicefile, extension,etc...
nom de directory:
$JONAS_ROOT/conf
utiliser filename + attribut class=directory
nom de fichier
jonas.properties
utiliser filename
nom de propriete de configuration
jonas.services
utiliser property
nom de variable d'environnement
JONAS_ROOT
utiliser envar
valeur de variable d'environnement
/home/jr48
dépend du type de la valeur , si c'est un path filename+directory si c'est une valeur prendre literal
nom de classe java ou package :
javax.mail.internet.MimePartDataSource
.
utiliser classname
pour un ensemble de commandes ou le contenu d'un fichier utiliser l'élément screen.
exemples:
export JONAS_BASE=~/my_jonas_base cd $JONAS_ROOT ant create_jonasbase
# jonas rmi activation (jrmp, iiop, jeremie, or cmi) carol.protocols=jrmp # RMI JRMP URL carol.jrmp.url=rmi://localhost:1099
Voici un tableau permettant de controler le rendu pour les différents éléments textuels(compte tenu de notre feuille de style utilisée) :
string | elements/attributs | rendu |
logger.root.level | aucun | logger.root.level |
logger.root.level | emphasis | logger.root.level |
logger.root.level | emphasis[bold] | logger.root.level |
logger.root.level | filename | logger.root.level |
logger.root.level | filename + class=directory | logger.root.level |
logger.root.level | filename + class=extension | logger.root.level |
logger.root.level | literal | logger.root.level |
logger.root.level | classname | logger.root.level |
logger.root.level | command | logger.root.level |
logger.root.level | envar | logger.root.level |
logger.root.level | interfacename | logger.root.level |
logger.root.level | package | logger.root.level |
logger.root.level | property | logger.root.level |
logger.root.level | function | logger.root.level |
logger.root.level | ulink | logger.root.level |