|
Ce document a pour but de décrire toutes les étapes de la rédaction de documents sur le site https://www.esup-portail.org en utilisant le format docbook. |
| Dates de modification | ||
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
S'inspirant du format docbook, une DTD allégée (docbook_allege_esup.dtd) a été écrite pour la rédaction de documents techniques.
Il existe deux éditeurs proposés par ESUP Portail pour la rédaction de documents en docbook:
En attendant l'utilisation du CMS inJAC sur le site ESUP, la transformation des documents docbook vers HTML se fait en local via une target ANT.
Il existe plusieurs fichiers de déploiement de ANT disponibles:
build.properties et build.xml des canaux auquel on a ajouté les balises nécessaires à la transformation XSLT
build.xml pour la transformation de documents techniques non liés à des canaux
Important
Lors de votre première génération de documents, vous devez impérativement être connecté au réseau. Ceci n'est pas nécessaire lors de l'utilisation de la target "prepare".
La target prepare crée, en plus de l'arborescence classique, un dossier docbook dans docs comme suit:
Ce dossier va contenir les librairies nécessaires à la transformation XSLT. Lors de la première transformation, les fichiers saxon.jar et saxon-jdom.jar seront chargés depuis le site ESUP vers ce dossier.
Tout comme pour le dossier lib, celui-ci sera peuplé lors de la première transformation. La feuille XSL docbookEsup.xsl y sera déposée pour la génération du HTML.
C'est dans ce dossier que seront enregistrées les documents XML et HTML comme suit:
Tous vos documents docbook relatifs aux canaux doivent être rangés à la racine de ce dossier. Si vos documents comportent des images ou autres éléments, ils doivent IMPERATIVEMENT être stockés dans le dossier media.
Les noms de fichiers sont normés comme suit:
presentation.xml
installation.xml
utilisation.xml
Note
Notons que cette configuration n'est pas uniquement réservée aux canaux et peux être utilisée pour la rédaction de documents d'installation et d'utilisation de tout autre application (serveur, etc.).
Cette target lance la procédure de transformation du HTML depuis le docbook. Un dossier htmlgen est alors créé dans le dossier pages. Dans ce dossier, un répertoire du nom du canal est aussi généré.
Le dossier media contenu dans xml est recopié dans htmlgen/nom_canal et les fichiers docbook sont transformés comme suit:
index.html (présentation du canal)
installation.html
utilisation.html
Cette target fait les mêmes actions que la target docbook.to.html, sauf qu'aucune table des matières n'est générée dans les fichiers.
La target prepare crée les dossiers lib, pages, xml, media et xsl nécessaires:
Ce dossier va contenir les librairies nécessaires à la transformation XSLT. Lors de la première transformation, les fichiers saxon.jar et saxon-jdom.jar seront chargés depuis le site ESUP vers ce dossier.
Tout comme pour le dossier lib, celui-ci sera peuplé lors de la première transformation. La feuille XSL docbookEsup.xsl y sera déposée pour la génération du HTML.
C'est dans ce dossier que seront enregistrées les documents XML et HTML comme suit:
Tous vos documents docbook doivent être rangés à la racine de ce dossier. Si vos documents comportent des images ou autres éléments, ils doivent IMPERATIVEMENT être stockés dans le dossier media.
Cette target lance la procédure de transformation du HTML depuis le docbook. Un dossier htmlgen est alors créé dans le dossier pages.
Le dossier media contenu dans xml est recopié dans htmlgen et les fichiers docbook générés sont également copiés dans ce dossier.
Cette target fait les mêmes actions que la target docbook.to.html, sauf qu'aucune table des matières n'est générée dans les fichiers.
Toutes les instructions qui vont suivre ne sont à respecter qu'en attendant l'utilisation de inJAC.
Les sources docbook des canaux ne sont pas à déposer sur le site ESUP. Celles-ci doivent être incluses au package du canal avec les pages HTML générées. En revanche, tout le contenu du dossier htmlgen/nom_canal doit être déposé sur le site.
Pour déposer les documents techniques sur le site ESUP, vous devez créer un dossier dans lequel vous allez déposer le contenu des dossiers xml et htmlgen. Le lien vers cette documentation sera faite sur les pages HTML par la personne qui dépose les documents.
Important
Notons que par la suite, lors de l'utilisation de inJAC, seuls les documents XML seront déposés sur le serveur, la transformation XSLT se faisant à la volée.