Manuel du contributeur

Ce document décrit brièvement comment est réalisé le (projet de) site web pour Caml, et comment il est possible de contribuer.

Organisation technique

Emplacement des fichiers

Les fichiers sources qui servent à réaliser le site web sont rangés dans le repository CVS de Caml sur pauillac, dans le module website. Il est subdivisé en deux répertoires:

htdocs/ pour les pages du site,
utils/ pour un ensemble d'outils utilisés par le site web, par exemple les scripts CGI, le vérificateur de liens, etc.

À priori, vous n'avez besoin que du premier répertoire. Pour l'obtenir, il suffit donc d'utiliser la commande:

  cvs -d /net/pauillac/caml/repository/ co website/htdocs

Le répertoire `htdocs/`

La structure du répertoire htdocs/ correspond à celle du site web tel qu'il apparaît sur le serveur. Ses sous-répertoires sont les suivants:

about, caml-light, ocaml et oasis contiennent les pages des quatre grandes parties du site,
styles contient les feuilles de style CSS, et les images utilisées par celles-ci,
dtd contient des DTD,
xslt contient les feuilles de styles XSLT,
data contient quelques fichiers XML auxiliaires.

(Le rôle des fichiers des deux derniers répertoires est expliqué plus bas.) Notons que le site web comporte un répertoire supplémentaire, pub/. Il contient des fichiers qui ne sont pas placés dans l'archive CVS pour ne pas l'alourdir, comme les distributions des compilateurs, ou les versions en ligne de la documentation.

XML et compagnie

Le site web est réalisé en utilisant les standards récents du W3C: XHTML (1.0) et CSS (niveau 2). XHTML est une version de HTML “compatible avec XML”: plus précisément, un document XHTML est un document XML qui vérifie une certaine DTD. L'intérêt est que le XHTML ressemble beaucoup au HTML, et est ainsi compris par les anciens navigateurs (et écrivains de page web). Le XHTML (strict) ne contient aucune information de mise en forme: celle-ci est donnée dans la feuille de style CSS.

Le répertoire htdocs/ de l'archive CVS ne contient toutefois aucun fichier XHTML: les pages du site sont écrites dans un autre sous-ensemble de XML, à partir duquel est généré le XHTML. Cela permet en particulier:

De regrouper les différentes traductions (anglais et/ou français pour l'instant) d'une page dans le même fichier source, pour simplifier leur mise à jour coordonnée,
D'abstraire les constructions communes aux différentes pages du site, comme par exemple la barre de navigation, de manière à obtenir un site homogène,
De fournir quelques “macros” pour faciliter l'écriture des pages, par exemple pour les liens hypertextes.

À partir d'un fichier a.xml, on génère deux pages HTML: a.en.html, qui contient la version anglaise de la page, et a.fr.html, pour la version française. La forme du fichier source, a.xml, est décrite plus bas. Indiquons cependant qu'il s'agit d'un ersatz de XHTML, il vous sera donc rapidement familier si vous connaissez HTML.

Pour les curieux, la transformation du fichier XML en fichiers XHTML est effectuée à l'aide d'une feuille de style XSLT (à ne pas confondre avec feuille de style CSS): ce langage (incroyable) permet de décrire des transformations d'arbres XML. Un processeur XSLT permet d'appliquer une feuille de style XSLT à un document XML source pour obtenir le XML résultat. Mentionnons que le code XSLT est assez trivial, il pourrait être réécrit dans tout langage permettant de manipuler simplement du XML.

Le plan du site (`data/sitemap.xml`)

Le plan du site est décrit sous une forme arborescente dans le fichier data/sitemap.xml. Chaque page du site est référencée par un élément <page> dans ce fichier. Par exemple, pour la page d'accueil:

  <page name="home"
    fr="yes" title-fr="Page d'accueil"
    en="yes" title-en="Caml's Home Page"
    href="~/index$"
  >
    [...]
  </page>

Les informations relatives à la page sont données par les attributs de l'élément:

L'attribut name est un identifiant unique de la page,
Les attributs fr et en peuvent prendre les valeurs yes et no (en cas d'omission, no est pris par défaut). Ils indiquent respectivement si la page est disponible en français ou en anglais.
Les attributs title-fr et title-en donnent les titres français et anglais de la page. Notons qu'il est souhaitable de donner un titre français aux pages qui ne sont traduites qu'en anglais, de manière à ce que les liens qui pointent dessus s'affiche en français dans les pages en français.
L'attribut href donne le chemin du fichier (la signification des signes ~/ et $ est expliquée plus bas).

Les pages filles sont naturellement données à l'intérieur de l'élément <page>, à la place des [...].

Le langage pre-XHTML

Structure générale de la page

Voici un squelette du fichier .xml source d'une page:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE page PUBLIC
   "-//CamlWebSite//DTD CamlWebSite pre-xhtml//EN"
   "http://caml.inria.fr/dtd/pre-xhtml.dtd">

<?xml-stylesheet href="http://caml.inria.fr/xslt/html.xsl" type="text/xsl"?>

<page name="home" 
  fr="yes" title-fr="Caml"
  en="yes" title-en="Caml's Home Page"
>

  <author name="Vincent Simonet" url="http://cristal.inria.fr/~simonet/"/>
  <author name="Xavier Leroy" mail="Xavier.Leroy@inria.fr"/>

  <navigation>
    <panel auto="toc"/>
    <panel auto="related"/>
  </navigation>

  <content>
    [...]
  </content>
</page>

Tout ce qui apparaît avant la ligne <page name="home" fait partie de la bureaucratie XML: <?xml ... ?> indique la version XML et le jeu de caractères, <!DOCTYPE ... > donne la DTD et <?xml-stylesheet ... ?> la feuille de style XSLT.
La racine du XML est un élément <page>. Ses attributs (name, fr, title-fr, etc.) sont identiques à ceux donnés dans le fichier sitemap.xml.
Les éléments <author> permettent de préciser les auteurs de la page. On peut en mettre 0, 1 ou plusieurs. On doit donner pour chaque auteur un nom (attribut name), ainsi qu'éventuellement un adresse e-mail (attribut mail) et une URL (attribut url). Les auteurs apparaissent en bas des pages.
Les éléments <panel> donnent les cadres de navigation qui apparaissent en haut à droite des pages.
Enfin, le corps de la page est donné dans l'élément <content>.

Le contenu de la page (`<content>`)

À l'intérieur de l'élément <content>, vous pouvez utiliser toutes les constructions habituelles du XHTML 1.0 Strict (c'est-à-dire grosso-modo du HTML 4.0 Strict). Les principales différences sont les suivantes:

Les tags doivent être “bien parenthésés”: <b><i>en gras italique</i></b> est correct, <b><i>en gras italique</b></i> ne l'est pas. Les éléments vides doivent être fermés: <br/> est correct, <br> ne l'est pas.
Les noms d'éléments et d'attributs doivent être en minuscule: <b>en gras</b> est correct, <B>en gras</B> ne l'est pas.
Les valeurs des attributs doivent être entre guillemets: <a href="http://caml.inria.fr/">caml</a> est correct, <a href=http://caml.inria.fr/>caml</a> ne l'est pas.
Les entités doivent être terminées par un ;. On écrit par exemple ©.

Vous risquez de plus de trouver le validateur relativement fasciste, mais, ma bonne dame, la norme, c'est la norme. Voici quelques erreurs fréquentes:

On ne peut pas mettre du texte directement dans l'élément racine <content>. Il faut le mettre à l'intérieur d'un paragraphe <p> ... </p>.
On ne peut pas mettre une liste <ul> ou <ol> à l'intérieur d'un paragraphe <p>. Il faut d'abord fermer le paragraphe, mettre la liste puis rouvrir un paragraphe. De même, pour les titres de sections <h2>, <h3>, etc.

Sections

Vous pouvez structurer le contenu de vos pages en utilisant des titres de section <h2>, et éventuellement des sous-sections <h3>. Ces éléments peuvent être munis d'un attribut name. Dans ce cas, une ancre est générée à ce point du document, permettant de faire un lien vers une section particulière d'une page:

<h2 name="foo">
  Section à propos de foo
</h2>
[...]
<a href="#foo"/>

(Notons que, si vous ne précisez pas d'attribut name, un identifiant unique est généré, en particulier pour le sommaire de chaque page. Cependant, cet identifiant peut changer à chaque recompilation du site.)

Langues

À l'intérieur d'un bloc (titre de section, paragraphe, item de liste, etc.), vous pouvez utiliser les éléments <fr> et <en> pour donner les différentes traductions du texte.

<h2>
  <fr>Titre en français</fr>
  <en>Title in English</en>
</p>
<p>
  <fr>Voici une phrase en français.</fr>
  <en>This is the same sentence in English.</en>
</p>

On peut utiliser les balises de sélection des langues à peu près à toutes les positions de l'arbre XML source. Cependant, il est conseillé de diviser le texte paragraphe par paragraphe: si on divise à un plus petit niveau, le source est rapidement illisible; à un plus grand niveau, la correspondance entre les deux langues est plus difficile à vérifier. Pour ne pas dupliquer les URLs, vous pouvez déclarer des entités XML dans le préambule du document. Pour un exemple, vous pouvez regarder le source de cette page ~/htdocs/manual.xml.

Les URLs

Plusieurs facilités sont offertes pour l'écriture des URLs (par exemple dans l'attribut href des éléments a):

Une URL de la forme !name est remplacée par le chemin de la page nommée name (dans le fichier sitemap.xml). Le processeur choisit automatiquement la bonne langue. Par exemple, !ocaml est expansé en ocaml/index.en.html sur une page en anglais, et ocaml/index.fr.html sur une page en français.
Lorsqu'une URL commence par ~/ elle est interprétée par rapport à la racine du site: par exemple ~/ocaml/distrib.en.html correspond à http://caml.inria.fr/ocaml/distrib.en.html. Cette URL est cependant réécrite de manière relative par rapport à la page courante: par exemple sur la page ~/about/overview.xml, l'URL ~/ocaml/distrib.en.html est traduite en ../ocaml/distrib.en.html.
Un $ dans une URL est remplacé par .{langue}.html où {langue} est fr ou en, suivant que l'on génère la version anglaise ou française d'une page.

Les URLs internes au site doivent être écrite sous la forme !name (cette forme permet de déplacer facilement des pages) ou sous la forme ~/chemin/de/la/page$. Dans les deux cas, les liens générés sont toujours relatifs (ce qui permet de faire des copies du site, e.g. sur un CD-ROM ou pour un miroir), et pointent vers la langue choisie par le lecteur.

Les cadres de navigation (`<panel>`)

Les boîtes de navigation qui apparaissent en haut à droite des pages sont générées à partir des éléments <panel> donnés au début de la description de la page. Le contenu de ces cadres est le plus souvent généré automatiquement par le processeur XSLT, comme indiqué par l'attribut auto:

<panel auto="toc"/> produit une table des matières de la page courante, en utilisant les titres de section <h2>.
<panel auto="related"/> produit une liste de liens vers les pages voisines. Par défaut, il s'agit de la page mère et des pages soeurs. Si on ajoute l'attribut mode="sub", les pages filles sont affichées.

On peut aussi créer un cadre avec un contenu libre:

  <panel>
    <caption>Titre du cadre</caption>
    <content>Contenu du cadre</content>
  </panel>

Comment contribuer?

Programmes requis

Pour compiler les pages du site sur votre station, vous avez besoin des deux programmes suivants (en plus de GNU-Make):

xsltproc, le processeur XSLT de la libxslt,
xmllint, le validateur XML de la libxml,

Ces deux programmes sont disponibles ici. Ils sont présents dans la plupart des distributions Linux (essayez les commandes xsltproc et xmllint).

Édition d'une page

Après avoir récupéré l'arbre du site sur votre compte, vous pouvez modifier les fichiers .xml. Pour voir le résultat, il vous suffit de lancer make dans le répertoire htdocs/: les pages html sont compilées à partir des sources. La compilation de chaque page s'effectue en trois étapes:

Vérification du fichier source vs. la DTD pre-xhtml.
Compilation du xml en xhtml par le processeur XSLT.
Vérification que le fichier produit vérifie la DTD xhtml.

Si le fichier source (resp. le fichier produit) n'est pas valide, la compilation échoue. Un message s'affiche pour permettre de localiser l'erreur.

Une fois la compilation terminée, vous pouvez visualiser votre copie locale du site avec un navigateur (en utilisant une URL file://...). Les URLS internes étant toutes relatives, vous pouvez suivre les liens en restant sur votre copie locale.

Ajout d'une page

Créez un nouveau fichier .xml à l'emplacement voulu dans l'arborescence, en utilisant le modèle donné ci-dessus, et remplissez les attributs de l'élément <page>.
Ajoutez l'entrée correspondante dans le fichier data/sitemap.xml.
Exécutez la commande make files, de manière à re-générer la liste des cibles du Makefile (fichier Files) à partir du plan data/sitemap.xml.
Pensez enfin à commettre vos modifications dans le CVS.

ChangeLog

Merci de notifier les modifications que vous apportez au site dans le fichier ~/htdocs/ChangeLog.

Foire aux Questions

Pourquoi un fichier `.fr.html` est-il généré pour une page qui n'est disponible qu'en anglais ?

Je n'aime pas l'apparence de pages, que puis-je faire ?

Vous pouvez essayer l'un des autres styles disponibles (avec Mozilla, menu View, puis use Style). Vous pouvez également proposer votre style en donnant une nouvelle CSS.