2. Installation

Dépendances

Le format IDML est complexe, et il est difficile d’en extraire les informations. Dans l’idéal, ce dépôt consisterait en un seul fichier Haskell, comme les autres lecteurs de Pandoc. Cependant, cela prendrait un temps fou à développer.

D’autres se sont penché·es sur la question de la lecture de fichiers IDML, en particulier le projet idml2xml-frontend, distribué sous licence FreeBSD. Nous construisons notre convertisseur en continuant ce travail, en proposant un binding entre idml2xml-frontend et Pandoc, c’est-à-dire en convertissant la sortie Hub XML de idml2xml-frontend vers le format DocBook 5.1.

Les principales dépendances sont :

  • Python 3.x ;

  • Java 1.7+ ;

  • les dépendances du package Python idml2docbook ;

  • idml2xml-frontend.

Pour comprendre l’utilité de chacune des dépendances, voir le graphe de conversions.

Installation avec install.sh

Premièrement, commencez par cloner le dépôt idml-pandoc-reader :

git clone https://gitlab.com/deborderbollore/idml-pandoc-reader

Ensuite, un script d’installation install.sh pour Mac et Linux a été développé afin de faciliter la prise en main de ce logiciel. L’installation sur Windows est elle aussi possible en adaptant les étapes détaillées ci-dessous, mais celle-ci pas pu être encore testée. Ce script a principalement pour fonctions de :

  • vérifier que Java (>= 7.0.0) est installé ;

  • vérifier que Git est installé ;

  • installer idml2xml-frontend ;

  • vérifier que Python 3 et pip (>= 21.0) sont installés ;

  • installer les dépendances Python à partir de requirements.txt ;

  • génèrer un simple fichier d’environnement .env ;

  • installer éventuellement le module idml2docbook via pip install . ;

  • exécuter une commande de test pour vérifier la validité de l’installation.

Pour exécuter ce script, commencez par lui donner les droits d’exécution :

chmod +x ./install.sh

Vous pouvez ensuite lancer l’installation :

./install.sh

Note : Pour les fichiers IDML les plus lourds, il peut être nécessaire d’augmenter la taille du tas Java, par exemple à 2048m ou 4096m.

Configuration de l’environnement .env

Le fichier .env.sample montre l’exemple d’un fichier de fichier de configuration.

A minima, pour fonctionner, ce convertisseur nécessite d’exécuter idml2xml-frontend. La ligne IDML2HUBXML_SCRIPT_FOLDER du fichier .env correspond donc au chemin absolu menant au dossier idml2xml-frontend présent sur votre machine. Il s’agit sûrement de la ligne la plus utile de votre fichier .env. Cette ligne est normalement renseignée automatiquement avec le script d’installation.

Les paires clé/valeur du fichier .env permettent de remplacer les valeurs par défaut du package idml2docbook. Pour plus d’informations sur ces différentes variables, consultez la liste des options.

Pandoc

Pandoc n’est pas une dépendance à proprement parler étant donné que le convertisseur idml2docbook n’en a pas besoin pour fonctionner.

Cependant, une version un peu modifiée de Pandoc a été développée pour supporter la lecture des styles de paragraphes et de caractères. Pour l’utiliser, il faut la compiler depuis la source.

Il est aussi possible d’utiliser la version principale de Pandoc, mais alors sans Correspondance des styles. Une pull request est en bonne voix d’intégrer ces nouvelles fonctionnalités dans la branche principale de Pandoc.

Test de la configuration avec la version modifiée de Pandoc

Pour vérifier que les dépendances ont bien été installées et le fichier .env bien paramétré, vous pouvez tester le convertisseur dans votre terminal avec la commande suivante :

pandoc hello_world.idml -f idml.lua -t markdown

Le résultat devrait alors être :

::: {wrapper="1" role="NormalParagraphStyle"}
Hello world!
:::