3. Usage

Préparation des fichiers IDML

Un guide de formatage indique comment préparer les fichiers InDesign. Même s’il n’est pas obligatoire de suivre ces recommandations pour utiliser le convertisseur, la qualité du résultat obtenu peut varier grandement selon la manière dont vous avez conçu votre document.

Correspondance des styles

Une fois la version modifiée de Pandoc installée, Pandoc sera en mesure d’interpréter les attributs role des éléments des fichiers DocBook obtenus après conversion. Ces rôles sont ensuite considérés comme des classes par Pandoc grâce au filtre roles-to-classes.lua.

Les attributs role correspondent aux styles de paragraphes et de caractères précisés dans InDesign. Comme illustré dans le fichier maps/sample.json, il est possible d’associer ces styles de paragraphes et de caractères à des traitements particuliers :

role : remplace le rôle du fichier source par une ou plusieurs classes ;
type : change le type d’élément DocBook (par défaut, para pour tous les éléments) vers un nouveau type ;
level : si type est un titre DocBook (balise title), level spécifie le niveau du titre ;
delete : supprime les éléments avec cet attribut role ;
wrap : enveloppe l’élément dans un autre, nécessaire pour les listes lorsqu’elles sont juste spécifiées par un simple style de paragraphe (itemizedlist, orderedlist) et les citations (blockquote) ;
unwrap : déplie le contenu de ces éléments dans l’élément parent ;
br : ajoute un saut de ligne avant l’élément concerné ;
cut : crée un nouveau fichier avant chaque élément ayant ce role ;
empty : conserve les éléments vides portant ce role (tous les autres éléments vides sont supprimés, sauf si l’option -e/--empty est active) ;
Si l’entrée est vide ({}) alors l’attribute role est supprimé.

Le script idml2docbook/map.py aide à constituer ces fichiers JSON. Ce script prend un fichier sorti de idml2xml-frontend et un fichier JSON de correspondance, et détaille la correspondance de styles qui va être appliquée via par exemple la commande suivante :

python idml2docbook/map.py file.xml maps/db.json

Commandes de base

Il est possible d’utiliser ce convertisseur de diverses manières :

Avec le package idml2docbook, puis en exécutant Pandoc sur le résultat produit ;
Avec le lecteur Lua idml.lua ;
Avec le script batch.sh.

idml2docbook

Ce package Python est la contribution principale de ce dépôt. Il offre une API permettant de convertir un fichier fichier IDML en un ou plusieurs fichiers DocBook.

Convertir un fichier IDML et l’enregistrer dans un fichier DocBook :

python -m idml2docbook hello_world.idml -o hello_world.xml

Il est aussi possible de directement envoyer le résultat de la conversion dans l’entrée standard de Pandoc :

pandoc -f docbook -t markdown <(python -m idml2docbook hello_world.idml)

Afficher l’aide à l’utilisation avec l’option -h/--help :

python -m idml2docbook -h 

idml.lua

Ce fichier fait le pont entre Pandoc et idml2docbook. Il permet de prendre le résultat de ce dernier pour l’insérer dans Pandoc. Pandoc ne permet pas de spécifier d’arguments arbitraires en ligne de commande, ce qui implique que seul modifier le fichier .env peut influencer le comportement de idml2docbook quand exécuté au travers de idml.lua.

Convertir un fichier IDML vers Markdown, avec par exemple le filtre roles-to-classes.lua :

pandoc -f idml.lua -t markdown --lua-filter=lua-filters/roles-to-classes.lua hello_world.idml

batch.sh

Avant toute chose, il est nécessaire de spécifier la version de Pandoc à utiliser dans le fichier .env. Il est aussi nécessaire de donner les droits d’exécution à ce script :

chmod +x batch.sh

Ce petit script shell permet de faciliter la liaison entre Pandoc et idml2docbook lorsque ce dernier est utilisé avec l’option -c/--cut pour séparer le résultat de la conversion en plusieurs fichiers (ou chapitres).

Cette commande prend deux dossiers en arguments : un dossier d’entrée et un de sortie. Il est ainsi possible de chaîner les commandes, par exemple :

python -m idml2docbook file.idml --output docbook_folder --cut ; ./batch.sh docbook_folder md_folder

Détail de la commande de conversion du recueil Déborder Bolloré

La commande pour compiler les contributions du recueil Déborder Bolloré, dont on peut retrouver le résultat sur le dépôt deborderbollore/articles, est la suivante :

python -m idml2docbook db.idml \
  --output docbook \
  --map maps/db.json \
  --cut \
  --typography \
  --thin-spaces \
  --names \
  --raster jpg \
  --vector svg \
  --media-folder images ;
./batch.sh docbook articles

En détails :

-o/--output : permet de préciser le dossier où seront contenus les fichiers DocBook produits ;
-m/--map : spécifie les opérations à effectuer sur certains styles de caractères et de paragraphes, voir Correspondance des styles ;
-c/--cut : coupe le résultat en plusieurs fichiers DocBook autonomes ;
-t/--typography : refait totalement l’orthotypographie (espaces autour des signes de ponctuation, etc.) ;
-l/--thin-spaces : l’orthotypographie utilise seulement des espaces fines ;
-n/--names : génère les noms des fichiers finaux à partir des contenus des titres de niveau 1 ;
-r/--raster : remplace les extensions des images matricielles par jpg dans les URL des fichiers de sortie ;
-v/--vector : idem pour les images vectorielles ;
-f/--media-folder : remplace l’URL absolue des médias dans les fichiers de sortie par images/.

D’autres paramétrages encore sont exposés via les options de ce package (voir l’aide avec -h/--help).

Enfin, le script batch.sh convertit les fichiers DocBook obtenus en Markdown, en précisant la saveur markdown_phpextra, et avec les filtres Lua nécessaires. Il transforme aussi les sauts de ligne Markdown (espaces doubles) en des balises HTML <br/>.