Wml Howto

Attention ! Le site april.org a été migré sous Drupal en octobre 2008. Cette page n'est donc plus d'actualité et est conservée pour raison historique

• HOWTO-WML*

_WML en 21 secondes (ou plus)_

Benjamin Drieu <bdrieu A april.org> Mise à jour par Benoît Sibaud <bsibaud A april.org>

Ce document a pour but d'expliquer comment utiliser WML pour mettre à jour le site web. C'est une pré-version qui n'explique que les choses propres au site de l'April. Pour une documentation complète de WML, lire la documentation fournie avec les sources que nous avons placée sur notre partie "développeurs".

1. Introduction

La structure d'un document est assez simple. En fait, il suffit d'ajouter une appel à un modèle (template) au début du document, ce qui générera automatiquement la page HTML (en-tête et pied de page compris). Il ne reste plus qu'à insérer le contenu dans la page, qui sera placé à l'endroit adéquat de la page.

L'en-tête et le pied de page du document doivent pourvoir être personnalisables à partir du corps du document, c'est pourquoi plusieurs balises WML ont été définies afin d'assurer cette fonction. Il s'agit des balises <sujet></sujet> et <auteur></auteur>.

2. Exemple basique de document

1. use wml::april::template ID="$Id$"

<sujet>Page de test</sujet> _BALISE OK_ <auteur><duglu /></auteur> _BALISE OK_

3. Explications

Expliquons pas à pas les lignes de cet exemple :

• • • • #use wml::april::template ID="$Id$" c'est la ligne qui inclut le fichier de modèle. La directive #use prend en argument un ensemble de trois chaînes séparées par deux double-points. On sait que le fichier de modèle s'appelle template, qu'il fait partie de la collection april, et qu'il se situe dans l'ensemble plus général wml. Notez qu'à la fin de la ligne nous incluons la chaine ID="$Id$". Il s'agit d'une chaîne utilisée par SVN pour conserver les modifications apportées à la page. Lorsque vous créez une nouvelle page, n'oubliez pas cette chaîne. Si vous éditez une page déjà créée, ce champ a été modifié par SVN. N'y touchez pas, car il sera édité automatiquement. Si de plus c'est le nom du contributeur précédent qui apparaît en bas de page à la place du vôtre, c'est normal. Il sera remplacé lors de la prochaine mise à jour du serveur web.
      • <sujet>Page de test</sujet> Cette balise définie par nos soins permet de fixer le titre de la page. Ce titre apparaîtra à la fois dans la barre de titre de la fenêtre du navigateur (s'il s'agit d'un navigateur en mode graphique), et en haut du corps de la page comme titre
        .
      • <auteur><duglu /></auteur> Cette balise permet de définir l'auteur du texte, et pas de la personne qui la met sur le web. En effet, SVN permet d'insérer le nom de l'utilisateur qui a effectué les dernières manipulations (champ $Id$). En revanche, cette balise permet de conserver l'auteur original. Elle ne devrait pas être utilisée de manière systématique, mais uniquement pour les textes de tierces parties mis en forme en WML, ou pour les articles d'opinion. Notez que dans cet exemple, l'argument passé est une autre balise (<duglu /> pour laquel il ne faut pas oublier d'insérer un espace et / avant > puisque notre site est en XHTML). Pour plus de commodité, nous avons créé des balises particulières pour nos collaborateurs réguliers. Ainsi, la balise <benj /> est remplacée par <a href="~mailto:bdrieu A april POINT org">Benjamin Drieu</a>. Cela nous évite de dupliquer inutilement du texte, et permet de modifier sans douleur les coordonnées d'un collaborateur.

4. Compilation de ce document

Normalement à ce point là, vous disposez d'un répertoire htdocs issu de l'arbre SVN du web (vous avez normalement fait un "svn checkout svn+ssh://votre_login@april.org/var/lib/svn/web/trunk/htdocs/le fichier qui vous intéresse". Vous y avez apporté des modifications, et vous désirez les visualiser. Il vous reste à compiler le document pour produire de l'HTML.

4.1 Installation du compilateur

La compilation d'un document wml implique qu'on ait installé wml auparavant. Il est disponible sur :

• • • • http://thewml.org/distrib/wml-2.0.11.tar.gz pour les sources
      • http://www.debian.org/Packages/stable/web/wml.html pour l'archive Debian
      • ...

Je vous laisse installer ce logiciel tout seul. Si la compilation des sources vous pose un problème, allez faire un tour sur http://www.april.org/groupes/doc/install_ll/ pour y lire une excellente documentation écrite par un jeune informaticien plein de promesses et d'avenir.

4.2 Compilation

La compilation s'effectue très simplement (dans le cas où le fichier à compiler est toto.wml par :

$ wmk -f toto.wml

Si la compilation se passe bien, une jolie animation ASCII apparaît pour vous faire patienter pendant la compilation qui est assez longue, et enfin le programme s'arrête silencieusement. Un fichier toto.html est créé dans le répertoire courant. Vous pouvez le visualiser dans votre navigateur favori.

4.3 Heu... j'ai essayé avec un des fichiers du web de l'April et ça a planté !

C'est normal. Je parie que l'erreur vient du fait que wmk n'a pas pu trouver le fichier template.wml. Un des avantages de wml est de pouvoir inclure des fichiers comme on utilise des fichiers d'en-tête en programmation. C'est ce que nous avons fait, et cela vous demande d'utiliser des fichiers spécifiques.

Pour cela nous avons créé un module SVN nommé include contenant les fichiers d'include nécessaires à WML.

La procédure à suivre est la suivante :

• • • • faire un svn checkout .../include pour récupérer les fichiers d'include WML. Voir le SvnHowto. Vous disposerez des fichiers d'include dans le répertoire include. Déplacez le répertoire include où vous voulez, par exemple en /home/moi/svnapril/include. (Sur le serveur de l'April, ce répertoire est /var/www/www.april.org/include/.)
      • Créez un fichier .wmlrc dans votre /home/moi. Ce fichier doit contenir les lignes suivantes:

o -I /home/moi/svnapril/include Cette ligne doit pointer vers l'endroit où vous avez déplacer le répertoire d'includes WML. Ce répertoire doit contenir un répertoire april. o -D HOME~. Cette ligne assigne le répertoire courant . à la variable locale HOME. Elle pourra être lue par de différentes manières. o -D INCLUDE_PATH="/home/moi/svnapril/include" Cette ligne assigne le répertoire d'include à la variable INCLUDE_PATH. Elle doit contenir le même répertoire que la 1ère ligne (-I) o quelques autres variables générales, voir l'exemple ci-dessous:

Ce fichier ressemble donc à ça: $ cat /home/moi/.wmlrc

-W2,--expansion=2
-I /home/moi/svnapril/include
-D HOME~~.
-D INCLUDE_PATH="/home/moi/svnapril/include"
-D CHARSET="iso-8859-1"
-D KEYWORDS="April, Logiciels Libres, Logiciel Libre, GNU, Richard Stallman, France, GPL"
-D DESCRIPTION="Association pour la Promotion et la Recherche en Informatique Libre"
-D COPYRIGHT="April"
-D CSS_SCREEN="css/cg2005/style.css"
-D CSS_PRINT="css/print.css"
-D CSS_JS="css/cg2005/misc.js"
-D FAVICON="favicon.ico"
-D GENERIC_TITLE="April"

Si vous voulez que WML effectue une vérification syntaxique de vos pages, vous pouvez changer expansion=2 par expansion=0

Attention, vous devez aussi avoir généré le fichier personnes.wml (voir Personnes de l'association) et urls.wml.

Une fois ces manipulations effectuées, réessayez. Si ça ne marche pas, contactez-nous à l'adresse webmaster@april.org.

Bien, maintenant vous êtes prêt à écrire un document complet.

5. Référence de WML

Il est hors de question de vous expliquer ici toutes les balises WML. Nous nous contenterons de vous citer ceux que nous avons définis nous même ou que nous utilisons couramment.

Chaque section correspond à un des fichiers de l'archive include.tar.gz, cité entre parenthèses.

5.1 Abréviations (abbrevs.wml)

<april> _BALISE OK_

Cette balise est remplacée par la chaîne "Association Pour la Promotion et la Recherche en Informatique Libre".

5.2 Couleurs (couleurs.wml)

<<couleur_clair>> _BALISE OBSOLETE_

Cette macro-fonction est remplacée par la couleur claire en vigueur dans la page en cours.

<<couleur_fonce>> _BALISE OBSOLETE_

Cette macro-fonction est remplacée par la couleur foncée en vigueur dans la page en cours.

<<couleur_noir>> _BALISE OBSOLETE_

Cette macro-fonction est remplacée par du noir (mais on ne sait jamais, ça peut changer).

<<couleur_blanc>> _BALISE OBSOLETE_

Cette macro-fonction est remplacée par du blanc (mais on ne sait jamais, ça peut changer).

5.3 Documentation (doc.wml)

<doc-header> _BALISE A VERIFIER // à la feuille de style_

Cette balise produit un en-tête pour une documentation du groupe de travail du même nom. Les arguments utilisés sont :

• • • • url : le nom de fichier de la documentation. Celle-ci doit être placée dans un sous-répertoire du projet documentation qui porte son nom. Par exemple, la documentation install_ll.sgml se trouve dans le répertoire install_ll.
      • nom : le nom complet de la documentation
      • date : la date de publication de la documentation
      • version : la version de la documentation
      • auteur : l'auteur de la documentation

5.4 Multi-langues (lang.wml)

Le principe est que wml est capable de compiler un document wml et d'en produire plusieurs documents html de langues différentes. Le serveur web se chargera d'effectuer la sélection des documents html ou alors l'utilisateur en spécifiant une url explicitement.

La compilation s'effectue obligatoirement en passant des arguments magiques à wml. Ne cherchez pas à la comprendre, recopiez les tels quel :

-o(ALL-LANG_)+LANG_FR:%BASE.html -o(ALL-LANG_)+LANG_EN:%BASE.html.en

Ou alors, plus simple: rajoutez la ligne suivante au début du document, SUR LA PREMIÈRE LIGNE.

1. !wml -o(ALL-LANG_)+LANG_FR:%BASE.html -o(ALL-LANG_)+LANG_EN:%BASE.html.en

Puis autorisez le compilateur à utiliser les extensions April multilingues en ajoutant la ligne suivante avant le #use wml::april::template.

1. use wml::april::lang

C'est tout !

Ensuite, si vous voulez utiliser le multilingue, il suffit d'utiliser les deux balises <fr> et <en> pour des texte respectivement en français et en anglais. Ce sont des balises qui nécessitent des balises fermantes. Par exemple :

<fr> _BALISE OK_ Bonjour ! </fr> <en> _BALISE OK_ Hello ! </en>

<fr:texte français> et <en:english text> _BALISE OBSOLETE_

Évidemment, il ne sert à rien de mettre sous balises fr et en dans les balises HTML.

Quelques remarques :

• • • • La table des matières doit être similaire dans toutes les langues. Il n'est pas possible d'avoir des sections supplémentaires dans une langue particulière (par exemple, ajouter une annexe pour les non-francophones n'est pas possible).
      • Il faut systématiquement mettre la version française juxtaposée aux versions étrangères, y compris dans les titres. Faire

<fr>tout le document</fr><en>the whole document</en>

pose des problèmes de génération de table des matières (les deux tables des matières, française et anglaise, sont générées).

Il faut donc écrire les différentes versions linguistiques pour chaque élément (paragraphe, titre, etc.). Par exemple, une section s'écrit (* désigne ici un numéro quelconque de section) :

<sect><en:patati><fr:papata></sect>

5.5 Personnes de l'association (personnes.pl)

Ces personnes sont définies dans les macros WML pour faciliter les références à leurs coordonnées (si mon adresse mail change, je me contente de changer une définition plutôt que 50 pages).

Le fichier de référence est le fichier include/april/personnes.dat. C'est lui qui contient les données.

Pour générer le fichier personnes.wml nécessaire à la compilation des fichiers wml, faîtes :

cd $MON_REP_SVN/include/april ./personnes.pl > personnes.wml

où $MON_REP_SVN désigne votre répertoire svn.

Si vous désirez faire partie de cette liste, envoyez un courriel aux webmestres.

Pour être référencé dans ce fichier, la procédure est la suivante :

• • • • Rajoutez une entrée dans le fichier include/april/personnes.dat sur le modèle des entrées déjà existantes et commitez ce fichier.
      • Logguez-vous en tant que l'utilisateur http sur la machine de l'April, via su par exemple (demandez le mot de passe aux webmasters ou demandez-leur d'exécuter eux-même la suite) et faîtes un svn update dans le répertoire /var/www/www.april.org/include/april.

5.6 Insertion de divers textes (text.wml)

<important></important> _BALISE A VERIFIER // à la feuille de style_

Met en gras et d'une couleur foncé le texte encadré par cette balise. Seul un texte important devrait utiliser cette balise.

<gros></gros> _BALISE OBSOLETE_

Met le texte encadré par cette balise en plus gros.

<myfont></myfont> _BALISE OBSOLETE à remplacer ?_

Change la police du texte encadré par cette balise (en helvetica).

<legende></legende> _BALISE A VERIFIER // à la feuille de style_

Met le texte en plus petit et en italiques. Il s'agit de la légende d'une image.

<personnes></personnes> _BALISE A VERIFIER // à la feuille de style_

Met le texte en italiques. Cette balise est utilisée pour encadrer un nom. Chaque nom introduit pour la première fois dans un texte devrait utiliser cette balise.

<citation></citation> _BALISE A VERIFIER // à la feuille de style_

Tout texte cité devrait être encadré par cette balise.

5.7 Table des matières (toc.wml)

<toc /> _BALISE OK_

Cette balise permet d'insérer une table des matières générée automatiquement en analysant les balises <Hn>.

<sectn> _BALISE OBSOLETE_

Ces balises remplissent le même rôle que les balises <hn>. <sect> correspond à une section du document, <sect1> à une sous-section, etc...

N'utilisez ces balises que si vous comptez insérer une table des matières. Dans le cas contraire, utilisez les balises traditionnelles <hn>.

Astuce :

pour éviter que le titre général de la page soit inclus dans la table des matières, vous pouvez appelez <toc /> après <sujet> :

____________________

1. use wml::april::template ID="$Id$"

<sujet>Lettre d'information de l'April du xx/xx/xx</sujet>

1. use wml::std::toc style=ol type=1a

_____________

5.8 URLs (urls.wml) _BALISE à supprimer ?_

• • • • <url:articles> : url de la page contenant les articles écrits par l'association
      • <url:groupes> : url de la page contenant un lien vers les différents groupes de travail
      • <url:association> : url de la page contenant la présentation de l'association
      • <url:gnu> : url de la page contenant la présentation du projet GNU
      • <url:actions> : url de la page contenant la liste des actions passées ou en cours
      • <url:serveur> : url de la page relative au serveur
      • <url:labo> : url de la page du groupe de travail laboratoire
      • <url:doc> : url de la page du groupe de travail documentation
      • <url:gnufr> : url de la page du groupe de travail traduction de la philosophie GNU
      • <url:texinfo> : url de la page du groupe de travail conversion de la documentation GNU en HTML
      • <url:entretiens> : url de la page du groupe de travail entretiens
      • <url:brevets> : url de la page sur les brevets
      • <url:faq> : url de la FAQ de Cédric
      • <url:divers> : url de la page contenant les divers articles écrits par l'association
      • <url:communiqués> : url de la page contenant les communiqués de presse de l'association
      • <url:images> : url de la page contenant les images
      • <url:miroir_gnu> : url du miroir de GNU local

5.9 Diverses balises (util.wml)

<footer_infos> _BALISE A VERIFIER // à la feuille de style_

Cette balise est remplacée par la date et la personne qui génère la page (pour le moment, la personne spécifiée par le tag <author>.

<cadre_fin></cadre_fin> _BALISE A VERIFIER // à la feuille de style_

Met un cadre fin et de couleur foncée autour du texte encadré par cette balise.

<actualite></actualite> _BALISE A VERIFIER // à la feuille de style_

Met un cadre fin et de couleur foncée autour du texte encadré par cette balise, et préfixe le texte du mot "Actualité" en gros.

<nouveaute></nouveaute> _BALISE A VERIFIER // à la feuille de style_

Met un cadre fin et de couleur foncée autour du texte encadré par cette balise, et préfixe le texte du mot "Nouveauté" en gros.

<vspace> _BALISE OBSOLETE_

Passe n lignes, où n est un argument passé à la balise. Par exemple : <vspace 3>.

<question></question> _BALISE OK_

À utiliser dans le cas d'un entretient.

<reponse></reponse> _BALISE OK_

À utiliser dans le cas d'un entretient.

_BALISE A VERIFIER // à la feuille de style_

Encadre un code source.

<traduction> _BALISE A VERIFIER // à la feuille de style_

Utilisé en bas de la traduction d'un texte. Il s'agit de donner les crédits nécessaires.

<<urlup>> _BALISE A VERIFIER // à la feuille de style_

Affiche l'url du document se trouvant au niveau au dessus de la page courante.here.