Introduction
La première partie du tutoriel permet à un utilisateur de créer un site de toutes pièces. La page de référence d'Achille lui procure suffisament d'éléments pour écrire un bon nombre d'articles.
Cette seconde partie à l'introduction d'Achille est plus axée sur le format des pages générées et leur cohabitation dans un site existant, ou au contraire l'import de pages existantes ou de documents divers dans un site généré à l'aide d'Achille.
A propos des images
Avant de rentrer dans vif du sujet, il est intéressant de s'attarder un instant sur le cas des images. La page de référence d'Achille contient un chapitre présentant les élément de la DTD DocBook qui peuvent être utilisés : <MediaObject> et <InlineMediaObject>. Leur différence tient au seul fait que l'image introduite dans le document par le second élément fait partie intégrante du paragraphe (ou autre bloc) auquel elle appartient, tandis que l'image introduite par le premier élément est affichée comme un bloc elle-même.
Ce qu'il est intéressant de noter ici, et qui n'est pas explicité dans la page de référence, c'est que l'élément <MediaObject> sert aussi à générer les icones des articles, qui apparaissent sur les pages d'index, générées par Achille. Pour cela, Achille vérifie si un élément <MediaObject> existe dans l'entête du document, c'est à dire dans son élément <ArtHeader> :
<artheader>
<address>
<ulink url="/about.xml">Lire la suite...</ulink>
</address>
<productnumber>9</productnumber>
<date>08/04/2003</date>
<title>Bienvenue...</title>
<mediaobject>
<imageobject>
<imagedata fileref="/images/achille-icon-black.png"/>
</imageobject>
<textobject>
<phrase>Icone Achille</phrase>
</textobject>
</mediaobject>
<abstract>
<para>
Ce site est généré par <emphasis>Achille</emphasis>.
<emphasis>Achille</emphasis> est un ensemble de scripts et de
feuilles de style destinés à générer un site statique à
partir de documents XML suivant la DTD <ulink
url="http://www.docbook.org">Docbook</ulink>. Ces pages
démontrent les capacités de ce système. Pour en profiter
pleinement, vérifiez que vous utilisez un navigateur conforme
aux normes <ulink url="http://www.w3.org/TR/xhtml11/">XHTML
1.1</ulink> et
<ulink url="http://www.w3.org/TR/REC-CSS2/">CSS 2</ulink>.
</para>
</abstract>
</artheader>
A propos des index
Achille génère deux types de pages. Les pages d'index, à raison d'un page par section, et une page dite sommaire sous la racine du site. Les pages d'index sont construites sur la base des éléments <ArtHeader> de chaque article de la section, sans aucun tri particulier. La page sommaire quant à elle, est construite seulement ensuite, et sur la base du contenu de toutes les pages d'index générées. Elle applique en outre un tri sur les articles listés. Par défaut, tous les articles sont triés du plus récemment modifié au plus ancien.
Comme on l'a vu dans la première partie de ce tutoriel, il est possible de définir une section directement sous la racine, ce qui permet notament de générer une entrée de plus dans le menu. Dans ce cas, la page d'index de cette section est créée au même moment que les autres, mais est tout de suite remplacée par le sommaire du site.
On peut voir dans le précédent exemple un élément utile à la génération du sommaire : <ProductNumber>. Cet élément permet de modifier l'ordre d'apparition d'un article sur le sommaire du site. Lorsqu'il est absent, un article possède un numéro d'ordre nul. Un numéro plus élévé, jusqu'à 9, est positionné avant dans la page. Lorsque deux articles possèdent un numéro d'ordre identique, c'est leur date de modification qui permet de les départager. En dernier lieu, si leur date est aussi équivalente, leur ordre d'apparition est indéfini.
Le sens de l'élément <ProductNumber> est ici détourné par Achille. Cela sera corrigé seulement dans les versions 2.0 et ultérieure, avec le portage en Python.
Travailler sur des branches
La structure utilisée par Achille peut ne pas correspondre à la structure souhaitée pour un site donné. Il est aussi possible qu'il existe déjà une base pour ce site, ou encore que le site comporte des parties dynamiques et statiques bien définies. Achille peut s'intégrer ainsi dans un existant, ou accueillir des portions non générées.
L'option prefix
Par défaut, Achille génère ses pages directement sous le répertoire défini dans l'entrée target du descripteur. Ces pages devraient être placées judicieusement sur un serveur Web, car les liens à l'intérieur du site sont tous définis par rapport à sa racine.
Ce comportement pose problème si l'on envisage d'utiliser Achille pour ne générer qu'une partie d'un site. Pour s'en affranchir, Achille introduit la notion de préfixe. Une entrée prefix dans le descripteur permet de définir un décalage entre la racine du site complet, et la racine de la partie générée par Achille et définie dans ce descripteur. Un exemple éclaircira cet imbroglio :
target /home/dsoulayrol/public_html prefix /test/achille
Dans cet exemple, le site est généré sous le répertoire /home/dsoulayrol/public_html. Ce répertoire constitue la racine du site. Si un serveur Apache correctement configuré tourne actuellement sur la même machine, l'URL nom_machine/~dsoulayrol permet de voir correctement les pages générées.
Imaginons que le répertoire /home/dsoulayrol/public_html contienne déjà de nombreux fichiers. Nous souhaitons que les pages générées avec Achille ne soient visibles que dans un sous-répertoire de ce site, disons avec l'URL nom_machine/~dsoulayrol/test/achille. Nous ne pouvons pas tout simplement changer l'entrée target du descripteur, car alors les liens contenus dans les pages générés seraient cassés. Au lieu de cela, il faut employer la ligne prefix comme ci-dessus. Les pages seront bien générées sous /home/dsoulayrol/public_html/test/achille, et les liens seront correctement créés
L'option import
Le mot-clef import permet de résoudre le problème contraire de prefix. Là où prefix permet de placer des pages générées par Achille au milieu d'un site existant, import permet d'apporter dans un site généré par Achille toutes sortes de fichiers.
Une entrée import dans le fichier decripteur du site importe un répertoire et tout son contenu, récursivement dans la hiérarchie du site. Si le répertoire cible existe déjà, rien n'est fait. Ainsi, si le répertoire source a changé, il vaut mieux à la génération entrer make distclean puis make afin de s'assurer que le site généré est bien à jour.
Le mot-clef prend deux arguments. Le premier spécifie le répertoire cible dans le structure du site. Le second le répertoire source.
import /src ./src import /images ./doc/images
Modifier le style
Comme cela a été vu précédemment, les pages générées par Achille sont conçues pour s'appuyer sur une feuille de style CSS afin d'être complètement personnalisables. Le site peut comporter une ou plusieurs feuilles de styles, les unes appelant les autres. Mais seule la feuille common.css est requise, car appelée directement depuis les pages HTML.
Un autre moyen de personnaliser le site est de se pencher sur les feuilles de transformation XSLT : index.xsl et page.xsl. Ces feuilles constituent le modèle des pages du site. Elles créent les divisions communes à toutes les pages : le titre de la page, une division pour le menu, le pied de page, etc.
Bien qu'elles soient écrites de manière à générer un modèle relativement standard, il est tout à fait envisageable de les modifier. Pour faire cela de manière propre, il est recommandé de les duppliquer sous le répertoire de travail du site en cours, par exemple dans un répertoire sample/xsl. Il faut ensuite modifier le descripteur du site pour prendre en compte les nouvelles feuilles :
xslt .sample/xsl
Les feuilles page.xsl et index.xsl font appel à la feuille docbook.xsl qui contient, ou fait appel elle-même aux feuilles qui contiennent les règles de base, communes à tout document, pour transformer le marquage de la DTD DocBook en éléments HTML. Lorsque l'on crée ses propres feuilles, il faut s'assurer que le chemin vers docbook.xsl est correct.