<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!--
# Copyright (c) 2001 Raphaël Hertzog, Logidée
# 
# Permission is granted to copy, distribute and/or modify this document
# under the terms of the GNU Free Documentation License, Version 1.1
# or any later version published by the Free Software Foundation;
# with no Invariant Sections, with no Front-Cover Texts, and with
# no Back-Cover Texts.
# A copy of the license is available at&nbsp;:
# http://www.gnu.org/copyleft/fdl.html 
-->
<!DOCTYPE module PUBLIC "-//Logidee//DTD logidee-tools V1.2//EN" "../dtd/module.dtd">
<module>
  <info>
    <title>Les outils logidee-tools</title>
    <ref>logidee_tools</ref>
    <description>
    <para>Ce module décrit l'installation et l'utilisation
          de logidee-tools.</para>
    </description>
    <objectives>
      <item>Maitriser les outils &quot;logidee-tools&quot;</item>
    </objectives>
    <ratio value="50/50"/>
    <duration value="1" unit="h"/>
    <!--
    <prerequis></prerequis>
    <dependance>
      <ref></ref>
    </dependance>
    <suggestion>
      <ref></ref>
    </suggestion>
    -->
    <version number="1.0">
      <author>Raphaël Hertzog</author>
      <email>raphael@ouaza.com</email>
      <comment>Première version</comment>
      <date>22 Juin 2001</date>
    </version>
    <level value="1"/>
    <state finished="true" proofread="true"/>
    <proofreaders>
      <item>Stéphane Casset</item>
    </proofreaders>
  </info>

<page>
<title>Présentation générale</title>

<section>
<title>Vue d'ensemble</title>
<para>
Logidee-tools est un ensemble de fichiers (feuilles de style, classe TeX,
Makefile, ...) qui sont regroupés dans un répertoire comme
<file>/usr/share/logidee-tools</file>. Ces makefiles permettent
de transformer les fichiers XML supports de formation en fichiers
exploitables, c'est-à-dire en PDF directement imprimables et consultables,
en HTML prêt à être mis sur le web.
</para>
<para>
Les documents peuvent être soit intégrés dans l'arborescence de
logidee-tools soit dans une arborescence à part. Dans ce second cas, il
est nécessaire de préparer l'arborescence des documents afin de
pouvoir exploiter logidee-tools. La section &quot;Installer les makefiles&quot;
décrira cela en détail.
</para>
</section>

<section>
<title>Changements</title>
<section>
<title>Version 1.2</title>
<para>Cette version est bien plus &quot;propre&quot; que la précédente. 
<list>
<item>Il n'y a plus besoin de faire attention à utiliser les entités
&amp;ud; et autres pour s'assurer que le fichier TeX généré soit
correct. La feuille de style TeX fait désormais ce travail.</item>
<item>Toutes les balises ont des noms anglais. La feuille de style
<file>xsl/upgrade-1.2.xsl</file> permet de générer des
documents conformes à la nouvelle DTD à partir des anciens. Cf
la page sur les conversions pour les détails.</item>
<item>Il est possible de ne rédiger qu'un diaporama avec la balise
slideshow.</item>
<item>On peut récupérer des documents docbook-xml dans les outils Logidée
avec la feuille de style <file>xsl/db2logidee.xsl</file>. Cf la page sur
les conversions.</item>
<item>On peut générer des documents dans plusieurs langues. Les textes
introduits par les outils Logidée (type "Sommaire", "Exercice") sont
disponibles en plusieurs langues. Les outils sont internationalisés et
prêts à recevoir d'autres traductions.</item>
</list>
</para>
</section>

<section>
<title>Version 1.0</title>
<para>Première version publique</para>
</section>
</section>

</page>

<page>
<title>Installation des outils</title>

<section>
<title>Dépendances</title>
<para>Pour exploiter la totalité des fonctionnalités des outils
Logidée vous devez disposer de&nbsp;:
<list>
<item>xsltproc, le transformateur XSLT de Gnome</item>
<item>TeTeX (et tetex-extra) pour le support LaTeX</item>
<item>package euro pour TeTeX (cf tetex-eurosym)</item>
<item>make</item>
<item>imagemagick pour convertir des images .eps en .png</item>
</list>
</para>
</section>

<section>
<title>Pour les utilisateurs de Debian</title>
<para>Les heureux utilisateurs de Debian disposent de paquets prêts à 
l'emploi. Il suffit de configurer apt pour pointer vers la source
fournie par Logidée et d'utiliser
<cmd>apt-get install logidee-tools</cmd>. Pour rajouter
la source Logidée à apt il faut ajouter ces deux lignes
au fichier <file>/etc/apt/sources.list</file>&nbsp;:
<code><![CDATA[
deb http://www.logidee.com/tools/ packages/
deb-src http://www.logidee.com/tools/ packages/
]]></code>
</para>
</section>

</page>


<page>
<title>Générer les supports de cours</title>

<section>
<title>Installer les makefiles</title>

<section>
<title>Dans l'arborescence logidee-tools</title>
<para>Si vous avez une copie de l'arborescence logidee-tools
obtenue soit depuis les sources soit simplement en copiant
<file>/usr/share/logidee-tools</file>, alors vous pouvez
placer vos documents XML dans le sous-répertoire <file>xml</file>
et sans rien modifier, vous n'avez qu'à lancer
<cmd>make makefiles</cmd> depuis la racine de l'arborescence
logidee-tools. Vous devriez voir ceci&nbsp;:
   <code><![CDATA[
   $ make makefiles
   Creating Makefile in doc
   Creating Makefile in xml
   $ 
   ]]></code>
</para>
</section>

<section>
<title>Dans une arborescence à part</title>
<para>Si vous avez choisi (et c'est un choix très raisonnable) d'avoir
vos documents dans une arborescence à part, alors vous devez préparer
cette arborescence afin de pouvoir utiliser logidee-tools sur vos
documents XML. Pour effectuer cette tâche vous allez utiliser
<cmd>setup-logidee-tools</cmd> (correspondant à <file>bin/setup</file>
dans l'archive source). Ce petit script doit être lancé depuis la racine
de l'arborescence de documents. Il accepte en paramètre une liste des
sous-répertoires contenant des documents XML. Vous pouvez également
préciser à l'aide du paramètre «&nbsp;-r&nbsp;» le répertoire où sont
présents les fichiers de logidee-tools que vous souhaitez utiliser.
Si vous ne précisez pas ces paramètres, le script va vous interroger
de manière interactive. Deux exemples d'utilisation&nbsp;:
<code><![CDATA[
$ setup-logidee-tools -r /usr/share/logidee-tools \
  programmation outils reseau
Creating Makefile in programmation
Creating Makefile in outils
Creating Makefile in reseau
$ setup-logidee-tools
Where is the main directory of logidee-tools ?
Main directory of logidee-tools: /usr/share/logidee-tools

Which directories may contain xml documents ?
Give a space delimited list of directories&nbsp;: programmation \
  outils reseau
Creating Makefile in programmation
Creating Makefile in outils
Creating Makefile in reseau
$
]]></code>
</para>
<note icon="attention">Dans tous les cas, il est souhaitable que les
documents XML soient dans des sous-répertoires de premier niveau de
l'arborescence des documents. Ceci est souhaitable pour harmoniser les
inclusions de documents et des images. Le détail de ces problèmes est
donné dans la partie traitant de la rédaction des documents.
</note>
</section>
</section>


<section>
<title>Utiliser les makefiles</title>
<para>Générer les PDF et autres pages HTML n'est qu'une question d'appeler
les bonnes cibles des fichiers Makefile que l'on vient d'installer.
Voici les cibles génériques qui vous seront les plus utiles&nbsp;:
<list>
<item><cmd>make pdf</cmd>&nbsp;: génère tous les documents PDF possibles, y
compris les diaporamas&nbsp;;
</item>
<item><cmd>make ps</cmd>&nbsp;: génère tous les documents PostScript
possibles&nbsp;;
</item>
<item><cmd>make 2pp</cmd>&nbsp;: génère tous les documents PostScript
possibles en mode 2 pages par feuille&nbsp;;
</item>
<item><cmd>make tex</cmd>&nbsp;: génère tous les documents LaTeX
possibles&nbsp;;
</item>
<item><cmd>make html</cmd>&nbsp;: génère tous les documents HTML
possibles&nbsp;;
</item>
<item><cmd>make slideshow</cmd>&nbsp;: génère tous les diaporamas
possibles&nbsp;;
</item>
<item><cmd>make check</cmd>&nbsp;: vérifie la validité de l'ensemble des
fichiers «&nbsp;;*.xml&nbsp;;» vis à vis de la DTD&nbsp;;
</item>
<item><cmd>make clean</cmd>&nbsp;: supprime tous les fichiers intermédiaires
créés mais conserve les .ps, .pdf et .html générés&nbsp;;
</item>
<item><cmd>make realclean</cmd>&nbsp;: supprime tous les fichiers
intermédiaires et tous les fichiers générés.
</item>
</list>
Voici une revue d'ensemble des autres cibles disponibles&nbsp;:
<list>
<item><cmd>make formations</cmd>&nbsp;: génère tous les supports de cours
«&nbsp;formation*.pdf&nbsp;» à partir des documents
«&nbsp;formation*.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make formations_show</cmd>&nbsp;: génère tous les diaporamas
«&nbsp;formation*_slideshow.pdf&nbsp;» à partir des documents
«&nbsp;formation*.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make formations_2pp</cmd>&nbsp;: génère tous les supports
de cours «&nbsp;formation*_2pp.ps&nbsp;» en version 2 pages par feuille
à partir des documents «&nbsp;formation*.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make themes</cmd>&nbsp;: génère tous les supports de cours
«&nbsp;theme*.pdf&nbsp;» à partir des documents
«&nbsp;theme*.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make themes_show</cmd>&nbsp;: génère tous les diaporamas
«&nbsp;theme*_slideshow.pdf&nbsp;» à partir des documents
«&nbsp;theme*.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make themes_2pp</cmd>&nbsp;: génère tous les supports
de cours «&nbsp;theme*_2pp.ps&nbsp;» en version 2 pages par feuille
à partir des documents «&nbsp;theme*.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make fichier</cmd>&nbsp;: génère le support de cours 
«&nbsp;fichier.pdf&nbsp;» et le diaporama
«&nbsp;fichier_slideshow.pdf&nbsp;» à partir de
«&nbsp;fichier.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make fichier.pdf</cmd>&nbsp;: génère le PDF adéquat à partir
de «&nbsp;fichier.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make fichier_2pp.ps</cmd>&nbsp;: génère le fichier
«&nbsp;fichier_2pp.ps&nbsp;» avec 2 pages par feuille à partir
de «&nbsp;fichier.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make module.html</cmd>&nbsp;: génère les pages HTML
«&nbsp;module.html/*.html&nbsp;» à partir de «&nbsp;module.xml&nbsp;».
Le répertoire <file>module.html</file> est prêt à l'emploi, vous
pouvez le copier sur votre site web sans rien changer&nbsp;;
</item>
<item><cmd>make module.txt</cmd>&nbsp;: génère une version texte
«&nbsp;module.txt&nbsp;» à partir de «&nbsp;module.xml&nbsp;»&nbsp;;
</item>
<item><cmd>make fichier.xml-check</cmd>&nbsp;: vérifie la validité de
«&nbsp;fichier.xml&nbsp;».
</item>
</list>
</para>
<para>
Il est possible de définir des variables d'environnement pour altérer la
génération des documents.
<list>
<item>CHARTE&nbsp;: valeur par défaut «&nbsp;default&nbsp;». Cette variable
permet de choisir la charte graphique utilisée pour générer les
documents&nbsp;; </item>
<item>TRAINER&nbsp;: valeur par défaut «&nbsp;false&nbsp;». En positionnant
cette variable à «&nbsp;true&nbsp;» vous incluerez les notes réservées aux
formateurs&nbsp;;</item>
<item>SELECTION&nbsp;: valeur par défaut «&nbsp;none&nbsp;». En positionnant
cette variable à un ou plusieurs mots-clés (séparés par des espaces) vous
n'incluerez que les données spécifiques à ce(s) mot(s)-clé(s) (cf attribut
&quot;restriction&quot;) et laisserez de côté les données spécifiques aux
autres mots-clés&nbsp;;</item>
<item>CYCLE&nbsp;: valeur par défaut «&nbsp;false&nbsp;». En positionnant cette
variable à «&nbsp;true&nbsp;», vous indiquez que la présentation doit utiliser
en cycle une série de fonds d'écran indiquées dans la charte
graphique&nbsp;;</item>
<item>LANG&nbsp;: valeur par défaut «&nbsp;en&nbsp;» (langue anglaise). En
positionnant cette variable à «&nbsp;fr&nbsp;» vous pouvez générer des
documents totalement en langue française&nbsp;;</item>
<item>SLIDE&nbsp;: valeur par défaut «&nbsp;true&nbsp;», permet d'afficher les
diapo dans le support papier, il suffit de la positionner à «&nbsp;false&nbsp;»
pour ne plus les afficher&nbsp;;</item>
<item>DESC&nbsp;: valeur par défaut «&nbsp;true&nbsp;», permet d'afficher les
descriptions et objectifs dans le support papier, il suffit de la positionner à
«&nbsp;false&nbsp;» pour ne plus les afficher.</item>
</list>

Exemple&nbsp;:
  <code><![CDATA[
  $ make formations SELECTION=debian TRAINER=true LANG=fr
  ]]></code>
</para>
</section>
</page>


<page>
<title>Rédiger des supports de cours</title>

<section>
<title>Avec un éditeur de texte</title>
<para>
Les documents XML ne sont que de simples documents textes. Il suffit donc
d'un éditeur de texte pour les rédiger. Toutefois il est quelque peu
rébarbatif de saisir régulièrement les mêmes balises. C'est pourquoi il
est intéressant de disposer de quelques raccourcis clavier lors de la
saisie.
</para>
<para>Pour les utilisateurs de vim 6 et supérieur, vous trouverez quelques fichiers dans le répertoire <file>vim/</file>. Installez ces fichiers de la manière suivante&nbsp;:
</para>
<para>
<list>
<item><file>xml.vim</file> =&gt; <file>~/.vim/ftplugin/xmllogidee.vim</file></item>
<item><file>syntax.vim</file> =&gt; <file>~/.vim/syntax/xmllogidee.vim</file></item>
<item><file>filetype.vim</file> =&gt; <file>~/.vim/filetype.vim</file></item>
</list>
</para>
<para>Ces fichiers fournissent une coloration syntaxique
adaptée pour le XML et un ensemble de raccourcis clavier
pour le mode insertion. Tous les raccourcis commencent par une virgule.
Ainsi «&nbsp;,xm&nbsp;» permet d'insérer la ligne d'en-tête XML et
«&nbsp;,in&nbsp;» insère un bloc d'en-tête info. Consultez le fichier
<file>xml.vim</file> pour découvrir les autres raccourcis.
</para>
</section>

<section>
<title>Ce qu'il faut savoir en rédigeant</title>

<section>
<title>Les chemins d'accès aux fichiers</title>
<para>
Il faut être particulièrement vigilant avec les chemins d'accès aux
fichiers  aussi bien lorsque vous incluez des images
(avec la balise image) que des documents (avec la balise include).
En effet, le jeu des inclusions peut changer le &quot;répertoire courant&quot;
et fausser les données.
</para>
<para>
Imaginez un répertoire <file>module</file>
contenant tous les modules et un répertoire <file>theme</file>
contenant l'ensemble des thèmes. Supposez que <file>theme/theme_un.xml</file> inclue un module avec une balise
include similaire à celle ci&nbsp;:
   <code><![CDATA[
   <xi:include href="../module/sujet.xml"/>
   ]]></code>
Supposez également que le module <file>sujet.xml</file> inclue
une image <file>schema.eps</file> (présente dans le répertoire
<file>module</file>) avec un élément&nbsp;:
   <code><![CDATA[
   <image src="schema.eps"/>
   ]]></code>
Que va t'il se passer lorsque l'on va essayer de transformer
<file>theme_un.xml</file> ? Et bien <file>theme_un.xml</file> va
contenir une balise image listant <file>schema.eps</file> qui n'est
pas disponible dans le répertoire <file>theme</file> et il va y avoir une
erreur. D'où la nécessité de mettre des chemins d'accès aux fichier plus
explicites même si l'image est dans le même répertoire que le module&nbsp;:
   <code><![CDATA[
   <image src="../module/schema.eps"/>
   ]]></code>
</para>
</section>

<section>
<title>Le format des images</title>
<para>
Les images qui sont inclues dans les documents XML doivent être au format
«&nbsp;.eps&nbsp;». Même si ce format ne convient pas pour toutes les
sorties (HTML notamment), c'est le format de référence choisi. L'image
sera automatiquement convertit en PNG pour les besoins de la version HTML.
</para>
</section>

</section>
</page>

<page>
<title>Conversions</title>

<section>
<title>Passage de la version 1.0 à 1.2</title>
<para>
Entre la version 1.0 et 1.2, la DTD des outils Logidée a été traduite en
anglais. Afin de continuer à exploiter les documents rédigés dans
l'ancienne DTD, il est fourni une feuille de style pour générer des
documents valides selon la nouvelle DTD à partir des anciens fichiers.
Il s'agit de <file>xsl/upgrade-1.2.xsl</file>. Pour générer un
nouveau document à partir d'un ancien, il suffit de se placer
dans le répertoire racine de vos documens et de lancer&nbsp;:
<code><![CDATA[
$ xsltproc xsl/upgrade-1.2.xsl xml/ancien.xml > xml/nouveau.xml
]]></code>
</para>
</section>

<section>
<title>Récupération de documents docbook-xml</title>
<para>
Si vous avez des documents existants en docbook-xml et que vous souhaitez
migrer vers le format exploité par les outils Logidée, vous pouvez
utiliser la feuille de style <file>xsl/db2logidee.xsl</file>. Une fois
placé dans le répertoire des outils Logidée vous pouvez utiliser une
commande similaire à celle ci&nbsp;:
<code><![CDATA[
$ xsltproc xsl/db2logidee.xsl xml/docbook.xml > xml/logidee.xml
]]></code>
Docbook-xml étant une DTD très vaste, il est possible (voire probable)
que la feuille de style ne convertisse pas parfaitement le document.
Il vous faudra reprendre manuellement le document généré sachant que
l'essentiel du travail aura déjà été fait. Les documents docbook à peu près
supportés sont les "book", "chapter" et "article".
</para>
</section>

</page>


<page>
<title>Fonctionnalités avancées</title>

<section>
<title>Les chartes graphiques</title>
<para>
Une charte graphique de nom &quot;&lt;charte&gt;&quot; est constitué&nbsp;:
<list>
<item>d'une classe TeX avec le fichier <file>charte/&lt;charte&gt;/tex/logidoc.cls</file>. Vous pouvez personnaliser ce fichier pour adapter à vos besoins la sortie .pdf des supports de cours et des présentations&nbsp;;
</item>
<item>d'une feuille de styles CSS (<file>charte/&lt;charte&gt;/default.css</file>)
utilisée pour la sortie HTML&nbsp;;
</item>
<item>de plusieurs fichiers HTML, <file>charte/&lt;charte&gt;/footer.html.&lt;lang&gt;</file> pour les pieds de page HTML, et
<file>charte/&lt;charte&gt;/html/&lt;lang&gt;/*.html</file> pour des fichiers
additionnels (au contenu fixe)&nbsp;;
</item>
<item>d'un jeu d'icônes dans le répertoire <file>charte/&lt;charte&gt;/icones/</file>&nbsp;;
</item>
<item>d'un document XML <file>charte/&lt;charte&gt;/charte.xml</file> 
donnant les correspondances entre les noms symboliques des icônes et le
nom réel des icônes présentes dans le répertoire précédemment cité&nbsp;;
</item>
<item>et d'un autre document XML <file>charte/&lt;charte&gt;/messages.xml</file>
listant les traductions du vocabulaire utilisé par les outils.</item>
</list>
</para><para>
Par défaut, c'est la charte graphique nommée «&nbsp;default&nbsp;» qui
est utilisée. Si la mise en page des sorties n'est pas satisfaisante pour
vos besoins, il est possible de l'adapter en créant une nouvelle charte
graphique dérivée de celle par défaut. Il suffit de recopier les fichiers
ci-dessus et de les modifier selon les besoins.
</para>
<para>Deux chartes sont fournies avec logidee-tools. Voici leurs
caractéristiques&nbsp;:
<list>
<item><em>default</em> est une charte &quot;restrictive&quot; qui inclue des
mentions &quot;Reproduction interdite&quot; et qui d'une manière générale
réserve tous les droits aux auteurs. Le logo utilisé est le célèbre
pingouin Tux.
</item>
<item><em>gfdl</em> est une charte &quot;libre&quot; qui inclue des mentions
signalant que le document est disponible sous la licence <em>Gnu Free
Documentation License</em>. Le logo utilisé est le gnou, symbole du
projet GNU.
</item>
</list>
</para>
</section>
<section>
<title>Localisation d'une charte</title>
<para>Si vous souhaitez localiser une charte dans une nouvelle langue,
c'est possible. Il suffit de&nbsp;:
<list>
<item>rajouter les traductions dans
      <file>charte/&lt;charte&gt;/messages.xml</file>&nbsp;;</item>
<item>fournir des fichiers
      <file>charte/&lt;charte&gt;/html/&lt;lang&gt;/*.html</file> et
      <file>charte/&lt;charte&gt;/footer.html.&lt;lang&gt;</file>&nbsp;;
</item>
<item>modifier <file>charte/&lt;charte&gt;/tex/messages.inc</file> pour
rajouter un bloc <em>\DeclareOption{&lt;lang&gt;}{ ... }</em> similaire
à ceux déjà présents&nbsp;;
</item>
<item>modifier <file>charte/&lt;charte&gt;/tex/logidoc.cls</file> pour
inclure le paquet TeX correspondant à la nouvelle langue pour Babel
dans la ligne <cmd>\usepackage[french,english]{babel}</cmd>&nbsp;;
</item>
<item>modifier <file>Makefile.generic</file> et <file>xsl/charte.xsl</file>
afin d'autoriser une nouvelle valeur pour les paramètres indiquant la
langue.
</item>
</list>
N'hésitez pas à nous envoyer les traductions que vous faites afin de
les inclure dans la version officielle des outils Logidée.
</para>
</section>
</page>

</module>
