Spécifications fonctionnelles

Ceux qui suivent ce blog savent que j'apprécie l'outil Concordion  (lire [1], [2], [3], [4], [5]).
J'apprécie sa simplicité et son ambition de rendre les spécifications à la fois lisible (rédaction libre contrairement à FIT ou Fitnesse) et chaînée au code.
Armé d'un tel outil et en suivant les recommandations de Joel Spolky, j'étais convaincu d'avoir trouvé la solution pour avoir des spécifications vivantes (merci Concordion), claires (merci Joel),  et donc lues ...
Hélas, ce ne fut pas le cas, et après avoir cherché à comprendre ce qui n'allait pas, il semble que la lecture des spécifications était freinée pour une raison assez incroyable : une arborescence de fichiers html fait peur au lecteur !
Le format html fait penser à "site web" mais pas à "document de référence" et une arborescence de fichiers semble effrayé le lecteur qui croit qu'il va oublier de lire des pages.
Pour vérifier cette hypothèse, j'ai donc décidé de convertir mes spécifications html arborescentes et un seul document pdf (pdf :  ça, au moins, ça fait sérieux !).
Les taches à réaliser pour parvenir à 1 seul pdf sont :

1. la lecture du sommaire pour déterminer l'ordre et la liste des spécifications
le sommaire est une page html qui référence d'autres pages html. Le plus simple pour parser cela est, à mon avis, PHP avec simplexmlelement. 
2. la conversion d'une page html en pdf.
Première pensée : xslt et xsl-fo, je vais y passer des heures... seconde pensée : un navigateur comme chrome fait cela très bien mais une ligne de commande serait beaucoup plus confortable. La solution : wkhtmltopdf. Sur ubuntu, pour l'installer il suffit de demander : sudo apt-get install wkhtmltopdf
3. la fusion de toutes les pages.
La encore, première pensée : fusionner les pages html; oui mais chaque page a ces balises html, head, body, qu'il faut remplacer cela par des div (en gérant les sauts de pages  via les attributs page-break-after/page-break-before). Mais finalement, il y a plus simple : fusionner les pdf; Une simple recherche sur google "pdf merge command" m'a permis de voir que GhostScript (gs) faisait cela très bien. Et bien sur, gs est de base sur Ubuntu !

Résultat : une dizaine de lignes php ! 

 
<?php  
    function pdfify($html){   // transform html to pdf thx to wkhtmltopdf
 $pdf = str_replace('.html','.pdf',$html);
        exec("wkhtmltopdf $html $pdf");
        return $pdf;
    }

 // first page containing concordion:run in
 $in = 'index.html';  
 // convert first page to pdf
 $pdfs[]=pdfify($in);  
 // parse index to find child files
 $names = simplexml_load_file($in)->xpath('//li/a'); 
 // generate pdf for each of them
 foreach($names as $name) { $pdfs[]=pdfify($name['href']);}
 exec("gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -sOutputFile=STL.pdf ".implode(' ',$pdfs)); 
 // clean temporary pdfs
 foreach($pdfs as $pdf) { unlink($pdf);}