Archive

Posts Tagged ‘docbook’

Makefile et squelette qui va bien pour docbook vers PDF

March 14th, 2011 No comments

Étant donné mon futur changement professionnel (vous en saurez plus dans un futur proche), je me suis confronté au problème de la production des documents (principalement technique). Plusieurs solutions s’offraient à moi, la plus facile, en tant qu’utilisateur de Mac OS X, est d’utiliser Pages, de la suite iWork. Bien que ce dernier soit un produit très adapté pour produire rapidement un joli document, je trouve que la construction d’un thème from scratch n’est pas très facile, et de toute façon, il n’est utilisable que sous Mac, donc difficile en clientèle par exemple. La seconde solution, est d’utiliser OpenOffice ou LibreOffice, cependant, après quelques années d’expériences, je trouve que ce n’est pas très pratique sur le long terme, de plus, l’avenir des deux produits me semble incertain, le premier est devenu payant, le second, communautaire, ne me rassure pas quant à son avenir.

Les deux solutions restantes sont docbook et LaTeX. Le dernier, bien que connu pour être très bien, me parait coûteux en temps, principalement sur la personnalisation du rendu (PDF dans mon cas). Me reste donc docbook (si vous êtes anti XML, passé votre chemin). Pour ma part, il me semble absolument indispensable de différencier le contenu de son style (le rendu). Bien que beaucoup (mais ce n’est probablement pas votre cas, cher lecteur) pensent que <important>mon texte</important> soit équivalent à <gras>mon texte</gras>, ce n’est pas mon cas. Je peux pouvoir écrire un document (un contenu) à un instant t et le rendre en PDF mais surtout pouvoir modifier le style (couleur du titre, etc.) sans toucher le document d’origine, et ce plusieurs mois après la rédaction du fichier. C’est pourquoi je me suis tourné vers docbook.

Après quelques heures perdues, j’ai réussi à obtenir un squelette de production de mes documents, que je vais décrire dans le présent billet.

Les fichiers

Pour commencer, voici la liste des fichiers impliqués dans la production d’un document :

  • documentation.xml, c’est mon fichier source docbook, le contenu que je veux produire en pdf ;
  • default.xsl, ce fichier est une transformation XML (xsl) qui me permet de modifier le fichier docbook d’origine, pour par exemple rajouter automatique la partie sur l’auteur si elle n’est pas présente dans le document d’origine. Autant essayer de ne pas dupliquer l’information autant que faire se peut. ;
  • monstyle.xsl, c’est le fichier qui me permet de surcharger la transformation docbook vers FO (une étape intermédiaire avant transformation en PDF). C’est là que je vais définir les couleurs (ou tout paramètre disponible par la XSL de Walsh), ou bien encore surcharger un template précis ;
  • et finalement, un fichier Makefile qui me permet d’automatiser tout cela.

Le Makefile

Comme expliqué précédemment, ce fichier me permet d’automatiser la transformation d’un fichier docbook vers un fichier PDF. Et comme je galère un peu sur Makefile, je vais profiter de ce billet pour me faire un mémo.

DOCUMENTS=documentation.xml

FOP=/Users/bbonfils/tools/fop-1.0/fop
FOP_XSL=xsl/docbook.xsl
FOP_CONF=conf/fop.xconf
DEFAULT_XSL=xsl/default.xsl
XSLTPROC=xsltproc
XMLLINT=xmllint
TMP=tmp
ENV=LC_ALL=en_US.UTF-8
FOP_ENV=FOP_OPTS=-Djava.awt.headless=true

default: $(DOCUMENTS:.xml=.pdf)

%.pdf: %.xml
   $(ENV) $(XSLTPROC) $(DEFAULT_XSL) $? | $(XMLLINT) -format - > $(TMP)/$?
   $(ENV) $(FOP_ENV) $(FOP) -c $(FOP_CONF) -xml $(TMP)/$? -xsl $(FOP_XSL) -pdf $@

clean:
   @rm -f *.pdf

Les premières lignes définissent des variables, notamment DOCUMENTS qui me permet de lister les fichiers docbook à transformer en PDF. Ensuite, je défini la règle implicite suivante: :

%.pdf: %.xml
   $(ENV) $(XSLTPROC) $(DEFAULT_XSL) $? | $(XMLLINT) -format - > $(TMP)/$?
   $(ENV) $(FOP_ENV) $(FOP) -c $(FOP_CONF) -xml $(TMP)/$? -xsl $(FOP_XSL) -pdf $@

qui décrit la manière de compiler (transformer dans mon cas) un fichier XML vers un PDF. La première ligne permet d’appliquer ma XSL default.xsl qui permet de rajouter les informations de l’auteur si elles n’existent pas. La deuxième ligne applique la transformation docbook vers FO puis de FO vers PDF.

Et finalement, je définis la cible par défaut default en lui demande de me transformer la liste des fichiers renseignés par la variable DOCUMENTS en PDF, par substitution de l’extension.

Voilà, voilà, je dois avouer que ce billet est plus un memento personnel, mais tant qu’a faire, autant partager avec le monde. Pour les lecteurs avertis, vous aurez remarque que je traite que des fichiers textes qui sont donc parfaitement adaptés pour un gestionnaire de source tel que Subversion ou Git.

Categories: Business tools Tags: