Htmldoc


Htmldoc est, au départ, un programme développé par une société commerciale pour ses besoins internes. Elle la finalement diffusé sous Licence GNU/GPL afin que chacun puisse profiter librement de cet outil.

Le format html, dérivé du SGML, permet de structurer un ensemble d'informations mais ne peut prendre en compte des paramètres de mise en page. Les seuls formats (libres) qui puissent gérer un document structuré et avec mise en page sont le Postcript et le PDF. La fonction de Htmldoc est donc de pouvoir générer des documentations parfaitement imprimables sans perdre la structure du document. D'un côté, Htmldoc utilise un ficher source en HTML et il va en sortir un document Postscript ou PDF. Ce programme reconnaît la majorité des balises HTML 3.2 et peut générer des fichiers PDF au format 1.2 et 1.3, encryptés ou non.
 

Installation

A moins de vouloir compiler HTMLdoc, dans ce cas il vous faudra la bibliothèque de widgets FLTK, l'installation est relativement simple. Htmldoc est aussi disponible pour Windows. Après avoir téléchargé et décompressé l'archive sur le site d"ESP (http://www.easysw.com/htmldoc), vous pouvez lancer l'installation en lançant le script d'installation  htmldoc.install en tant que root. Htmldoc est opérationnel. Pour lancer le programme il suffit de saisir dans une console : htmldoc.

Utilisation de HTMLDOC

Configuration des entrées "Input"

Le premier Onglet concerne la configuration des entrées (Input). Le Type de document vous permet de préciser que vous souhaitez simplement transformer une page web en fichier PDF (type web page) et l'autre optiion "book" vous permet de suivre la structure du document HTML afin de pouvoir générer automatiquement un index de la documentation. Dans ce mode vous devez faire attention à bien respecter la stuctrure du document sinon Htmldoc peut avoir une erreur fatale.

Le bouton "add files" vous permet d'insérer les fichiers sources en HTML, vous pouvez en spécifier plusieurs, ils seront lus dans l'ordre indiqué (c'est pour cela que vous avez des boutons "Move up et Move down" au cas où vous auriez besoin de modifier l'ordre des fichiers.

Le champ "logo image" vous permet de spécifier une imgage d'en-tête pour votre documentation, elle sera répétée sur chaque page, nous pourrons paramétrer par la suite l'emplacement de ce logo sur chaque page.

Le champ "Title File/image" vous permet de préciser un logo pour la page d'acceuil mais cela peut être aussi un document précis au format HTML qui contiendra votre page de garde.

Vous pouvez enregistrer votre travail grâce au bouton "save as", htmldoc créera un fichier .book dans le répertoire indiqué.

Le bouton "Generate" permet de lancer la création du document, mais il faudra d'abord spécifier les paramètres de sortie avant de lancer cette commande.

Les paramètres de sortie "Output"

Les différents formats de sortie :

Dans cet onglet vous pouvez choisr entre obtenir une sortie au format Postscript (PS) , Portable Document Format (PDF) ou HTML. Dans le champ "outpout path", vous pouvez préciser ici un nom de fichier.
Des cases à cocher vous permettent de spécifier si vous souhaitez avoir une page de garde (Title page); et si vous souhaitez utiliser la compression jpeg pour le format PDF, les tirettes vous autorisent la modification du taux de compression.

L'onglet Page

Dans cet onglet vous allez pouvoir indiquer le format de page pour la sortie PDF ou PS (universal, A4, letter). La case "2-sided" permet de générer des documents recto verso et la case "Landscape" permet d'orienter le document en mode paysage.

Les quatre cases correspondent aux marges du document.

La section "Header et Footer" (En-tête et pied de page) se subdivisent en 3 parties, qui correspondent au côté gauche, milieu et côté droit du document. Vous avez plusieurs possibilités pour le remplissage de ces champs :

L'onglet TOC

Cet onglet n'est disponible que si vous êtes dans le mode Book (Onglet Input). Vous pouvez spécifier ici l'apparence de votre page d'index, qui affiche la structure complète du document.

Vous pouvez préciser le nombre de niveaux,  et comme pour l'onglet précédent, les en-têtes.

Onglet Color

Permet de paramétrer certains attributs de page :

Onglet Font :

Dans cet onglet vous pouvez préciser la taille des polices, l'espacement entre les lignes, le type de Police (Times, Helvetica ou courrier) pour le corps, les en-têtes et pied de page et l'encodage (pour nous Français, c'est ISO 8859-1)

Onglet PS :

Si vous avez opté pour une sortie en Postscript, vous pouvez spécifer si vous souhaiter un postscritp de niveau 1, 2 ou 3.

Onglet PDF :

Cet onglet permet de paramétrer certaines options disponibles pour le format PDF.

Onglet Encrytion

Vous pouvez protéger vos oeuvres de la copie, des modifications, de l'impression grâce à cet onglet. Il suffit de préciser que vous souhaitez encrypter votre document et de lui indiquer les modes. N'oubliez pas de donner un mot de passe.

Onglet Option

Html editor : Vous pouvez préciser un éditeur html externe , celui-ci sera lancé quand vous ferez un double clic sur le nom du fichier HTML dans l'onglet Input.

Browser width : paramètre important car cela va permettre à htmldoc de simuler une largeur de page.

Search path : dans certains cas,  les images sont insérées avec des liens relatifs dans le code HTML, vous pouvez préciser ici un lien absolu à suivre.

Premier essai

Pour faire un premier test, je vais utiliser une documentation que j'ai faite sur la réalisation de pages HTML. Cette documentation possède la structure suivante :
 
Plan général

Paramétrage de Htmldoc

Nous allons d'abord lui indiquer le fichier source en HTML, ici c'est index.html, je vais aussi lui indiquer une image que je vais insérer dans chaque page de ma documentation comme en-tête.

Dans l'onglet Output, nous lui précisons que nous souhaitons une sortie au format PDF, que nous voulons utiliser la compression JPG (pour une diffusion sur le web) et que nous ne voulons pas de page de garde. N'oublions pas de lui préciser le nom du fichier de sortie : votre_nom.pdf

Dans l'onglet Page, nous précisons que nous souhaitons avoir un format A4 et nous allons diminuer la marge gauche à 0.5. En en-tête nous indiquons que nous souhaitons avoir notre image "Logo" au centre et que nous souhaitons obtenir une numérotation relative en pied de page.

Dans l'onglet Index, nous précisons les mêmes paramètres pour l'en-tête et le pied de page. En titre, nous mettrons table des matières.

Dans l'onglet Colors, nous laisserons les couleurs comme elles sont.

Avec l'onglet Font, nous précisons que nous souhaitons Helvetica pour le corps du texte.

Dans l'onglet PDF, nous allons laisser les paramètres par défaut

Dans l'onglet Options, nous allons mettre une valeur de 900 comme largeur du navigateur car cette documentation contient de grandes images qui occuperaient trop de place. Généralement une valeur de 800 suffit.

Génération du document

Nous lançons l'opération de génération du PDF en cliquant sur le bouton Generate et voici ce que nous obtenons avec Adobe Acrobat en ouvrant le ficher PDF créé :

Vous pourrez constater que mon document fait 18 pages, que la structure définie par le format HTML est parfaitement conservée et reprise dans la table des matières sur le côté gauche d'Acrobat Reader.
Tout pourrait être parfait et s'arrêter ici, mais HTMLDOC a quelques inconvénients sur la mise en page que nous allons résoudre.
 

Résolution des problèmes souvent rencontrés

 

Mise en page

Le problème de HTMLdoc est qu'il ne respecte pas toujours une mise en page parfaitement optimisée. Par exemple, si il manque un peu d'espace pour mettre une image, il la mettra sur la page suivante en vous laissant un grand blanc. Cela vous oblige à reprendre le ficher source en HTML est à essayer d'enlever des retours de chariots pour faire tenir l'image dans la page. La solution la plus radicale est de réduire la taille de l'image dans le source HTML.

Retraits

Un autre problème rencontré est une mauvaise gestion des retraits.


Les zones entourées indiquent que le retrait n'est pas repecté, ces paragraphes devraient s'aligner sur le trait bleu. Pour corriger cela, il faut ajouter un retrait suplémentaire dans les zones concernées. Cela se produit en général après une image  et à la suite d'une liste à puce.

Quand c'est une image, cela se produit si elle est centrée, il suffit de laisser l'alignement à gauche pour ne plus avoir le problème ou bien d'augmenter le retrait.

Dans le cas d'une liste à puce, seule la solution d'augmenter le retrait fonctionne.

Voici mon document après correction :

 

Texte autour d'une image

Le dernier problème que l'on peut rencontrer et la gestion du texte autour d'une image. Les attributs d'image peuvent parfois suffire, mais ce n'est souvent pas le cas.
Un exemple de ce qui peut se produire

Ici, le texte titre (h1) , titre de Section (h2) et titre de sous-section devraient se trouver le long de l'image et non pas au dessous. Pour corriger le problème nous allons utiliser un tableau transparent avec 2 colonnes, une contenant l'image et une autre le texte. Dans l'exemple ci-dessous, j'ai laissé le cadre du tableau pour une meilleure compréhension.


Vous constaterez un mieux mais cela ne correspond pas tout à fait à ce que je souhaitais. En effet, le texte n'est pas collé sur l'image.

En fait, je n'ai pas spécifié une largeur spécifique (en pixels) pour ce tableau, ni la largeur des colonnes. On dévourvre là un des points fort de HTMLdoc pour la mise en page : une bonne gestion des tableaux. Il suffit de préciser la taille exacte du tableau et de chaque cellule pour obtenir une mise en page parfaite. Je vais donc spécifier une largeur de 700 pixels pour le tableau, 128 pour la cellule contenant l'image et 572 pour l'autre cellule. Notre problème est résolu.

Vous pouvez faire disparaître le cadre du tableau en lui donnant une valeur de 0 dans votre source HTML. Sachant que HTMLDoc respecte les couleurs des cellules et la taille des tableaux, on peut faire des mises en pages propres et efficaces. Ci-dessous, un exemple de mes cours pour http://technoresto.org où j'ai utilisé ces astuces pour obtenir des mises en page correctes.

Conclusion

Ce didacticiel vous a permis de découvrir qu'il était possible de réaliser de belles documentations avec de simples outils. Pas la peine d'aller courrir acheter le dernier word 9 pour faire votre rapport de stage. Un simple éditeur de texte et HTMLdoc peuvent suffire, mais c'est quand même plus simpe de travailler avec des outils Wysiwyg pour générer les fichiers HTML : Amaya, Netscape Composer, Staroffice offrent déjà l'essentiel pour aucune licence à payer.

Les puristes me reprocheront de ne pas avoir parlé de Lyx et de Latex qui permettent de faire des documentations complètes et structurées. Là aussi, il est possible d'obtenir des documents PDF en passant par le format Postscript. Je rappelle que le but de cette documentation était de proposer une solution multiplateformes, malheureusement Lyx n'est disponible que pour Unix.

Pour des mises en pages plus complexes, qui ressemblent d'avantage à de la PAO, il faut en passer par le module de dessin vectoriel de Staroffice, qui gère le blocs de texte, puis faire une impression en Postscript pour ensuite le transformer en PDF via la commande ps2pdf.

Copyleft 2001 Toussaint Frédéric