NAWAK
NAWAK
NAWAK 0.1 User's guide
par Jean-Christophe
NAWAK : Another Web Authoring Kit.
Introduction
Ca y est, je l'ai écrite cette doc ! ;) Bon ben alors c'est la doc de mon Web Meta Langage et de son compilateur, NAWAK, écrit en langage PERL.
Concepts
NAWAK se comporte comme un compilateur, c'est à dire qu'il ne traite qu'un seul fichier source (un fichier HTML standard) pour en faire un fichier résultant (également, bien sûr, un fichier HTML standard). Pour générer un site web complet, on lance autant de fois NAWAK que nécessaire pour générer chaque page du site. Une méthode recommandée pour ce faire est d'utiliser Make, qui gère les dépendances entre fichiers et permet de relancer la génération de toute page pour laquelle un fichier dont elle dépend aurait été modifié.
NAWAK applique différentes templates (ou modèles) au fichier source afin de produire le fichier résultant. Les templates sont de simples fichiers HTML et peuvent comporter (c'est même recommandé ;) des tags HTML spéciaux qui seront parsés et interprétés par NAWAK en fonction des données présentes à la fois dans les templates et dans le fichier source.
Ces tags se présentent sous la forme de commentaires SGML, commençant et se terminant par '%', et comprenant une commande interprétée par NAWAK. Par exemple, le tag <!--%generated format="jj-mm-aaaa"%--> se verra remplacé lors de la compilation par la date de génération, au format donné.
Cette façon de faire permet d'utiliser un logiciel classique pour éditer les pages source, et même les templates. Par exemple, vous pouvez utiliser Netscape composer ou StarOffice pour ce faire. Cela permet de gagner du temps dans la réalisation du site, ainsi que de changer facilement de look un site entier, en ne modifiant que quelques fichier (les templates) puis en relançant la génération. De plus la souplesse et l'ouverture de NAWAK permettent de faire virtuellement n'importe quoi (!) :)
Pré-requis
Les pages source doivent respecter certains prérequis afin de contenir les bonnes données au bon endroit, afin que NAWAK s'y retrouve.
Les consignes données sur cette page résument bien ce qu'il faut faire pour :
- une génération optimale du site,
- une facilité de réutilisation des fichiers source (pour évolution, ou changement de look).
Une page spécifique concernant uniquement les pré-requis sur les pages pour NAWAK sera écrite plus tard, mais en attendant, la page des contributeurs est largement suffisante.
Les templates
Cinq type de templates peuvent être utilisées simultanément par NAWAK :
- la template de définition de nouveaux éléments (variables globales, nouveaux tags...), optionnelle,
- la template d'entête HTML (ce qui est compris entre le début d'un fichier HTML jusqu'à la balise </HEAD> comprise), optionnelle,
- la template d'entête de page, optionnelle,
- la template de corps (également appelée template de base), obligatoire,
- la template de pied de page, optionnelle.
Voici ce qu'il advient de ces templates dans la page générée. D'abord la template de définition de nouveaux éléments est interprétée, et peut permettre de positionner des variables globales, de définir de nouveaux tags... Voir la partie traitant de l'extensibilité de NAWAK. Remarque : toute éventuelle sortie générée par cette template sera ignorée.
| Fichier résultant | Commentaires |
<HTML> <HEAD> ... </HEAD> |
En tête du fichier HTML, se trouve le résultat de la template d'entête HTML (comme son nom l'indique ;), c'est à dire ce qui se trouvait entre les tags <BODY> et </BODY> de cette template, parsé et interprété par NAWAK. Si cette template n'est pas définie, NAWAK génère une entête par défaut. |
<BODY ... > |
Dans sa version actuelle, NAWAK copie ici le contenu du tag <BODY...> de la template de base. |
| en-tête de page | Si elle existe, contenu de la template d'entête de page, parsé et interprété. |
| corps de la page | Contenu de la template de corps (ou template de base), parsé et interprété. |
| pied de page | Si elle existe, contenu de la template de pied de page, parsé et interprété. |
</BODY> </HTML> |
Généré. |
Remarques :
- A cause de sa structure spéciale (les tags <html>, <head>, </head>... dans son corps), la template d'entête HTML doit être éditée dans un simple éditeur de texte (voir annexe). Les autres templates peuvent être éditées dans un logiciel standard d'édition de pages Web, mais il est recommandé de vérifier leur contenu avec un éditeur de texte, car ces logiciels ne font pas toujours ce que vous pensez :-(
- Le "contenu de la template" cité dans le tableau correspond à ce qui se trouve dans le corps de la template (c'est-à-dire entre ses tags <body> et </body>), qui est parsé et dont les tags spéciaux sont interprétés par NAWAK.
Usage: nawak -s sourcefile
-o outputfile
[-a headtemplate]
[-t headertemplate]
-b basetemplate
[-f footertemplate]
[-e newelementstemplate]
[-D variable="valeur",...]
nawak -h
prints this help
Entre crochets : facultatif.
Exemple de ligne de commande (sur une seule ligne) :
[jice@taz ~jice/site/-src/docs]$ nawak -s contribs.htm -o ../../docs/contribs.htm -a ../_templates/head.htm -t ../_templates/headertmpl.htm -f ../_templates/footertmpl.htm -b ../_templates/chaptmpl.htm -D root="../"
La ligne de commande ci-dessus signifie : générer le fichier ../../docs/contribs.htm à partir du fichier source contribs.htm avec comme templates, respectivement :
- pour l'entête HTML : ../_templates/head.htm,
- pour l'entête de page : ../_templates/headertmpl.htm,
- pour le corps : ../_templates/chaptmpl.htm,
- pour le pied de page : ../_templates/footertmpl.htm,
ceci en positionnant la variable $root à la valeur "../". La possibilité de positionner cette variable peut par exemple être utilisée dans les templates afin de gérer des chemins relatifs par rapport au répertoire courant. Par exemple, la même template pourra être utilisée dans tout le site, quelque soit le répertoire, si on utilise une variable $root et que l'on adapte les tags comme : <IMG SRC="<!--%$root%-->images/titre.png" ALT="Titre"> ou <!--%inserefichier nomfichier=$root."_templates/sections.htm"%-->
Le Métalangage
Le langage de NAWAK est composé de tags qui se présentent sous la forme de commentaires SGML, commençant et se terminant par '%', et comprenant une commande interprétée par NAWAK, utilisant un ou plusieurs arguments. Les arguments sont entourés de guillemets (") ou de quotes ('), et peuvent même ne pas être entourés s'ils sont constitués d'un seul mot :
<!--%commande (nom_argument=["|']valeur_argument["|'])*%-->
Par exemple, le tag <!--%generated format="jj-mm-aaaa"%--> se verra remplacé lors de la compilation par la date de génération, au format donné (commande = generated, augument = format).
Un fichier source, une template... peut contenir n'importe quoi, NAWAK le lira, trouvera ces tags (c'est ce qu'on appelle parser le fichier), et remplacera ces tags par la chaîne de caractère qu'ils ont produite (c'est ce qu'on appelle interpréter les tags).
Certains de ces tags utilisent des variables, dont on va voir ci-dessous la définition.
Les variables
Les variables sont définies dans l'en-tête HTML du fichier source, via des tags META. Par exemple, le tag suivant : <META NAME="Author" CONTENT="Jean-Christophe Cardot"> définit une variable $author contenant "Jean-Christophe Cardot".
Les variables suivantes sont indispensables car utilisées par les tags spécifiques : Nom de l'auteur de la page :
<meta name="Author" content="Jean-Christophe Cardot">
Date de création du fichier :
<meta name="created" content="19991102;00000000">
Dernière personne ayant modifié le fichier :
<meta name="changedby" content="JCC">
Date de dernière modification du fichier :
<meta name="changed" content="19991225;00000000">
Les dates sont construites de la manière suivante : année sur 4 chiffres, suivie du mois sur 2 chiffres, puis le jour sur deux chiffres. Enfin un point virgule et huits chiffres quelconques.
On peut également définir autant de variables que l'on souhaite, qui pourront servir par la suite, par exemple en étant appelées dans une template, ou bien dans certains tags. Les deux exemples ci-dessous montrent ce qu'on peut faire avec les variables :
Dans l'entête HTML du fichier source, on a :
<meta name="ressources" content="_ress_contribs.htm">.
La variable $ressources ainsi définie peut être utilisée dans une template par un tag : qui insère à sa place le contenu du fichier dont le nom est dans la variable $ressources. Cela permet d'insérer un fichier différent pour chaque fichier source au même endroit de la template. Pour faire apparaître des remerciements éventuels à la fin de chaque chapitre, on peut définir dans l'entête HTML du fichier source :
<meta name="merci" content="Merci à BooK pour son aide.">,
le contenu de cette variable sera alors utilisé dans la template des chapitres par ce tag placé vers la fin du template :
<!--%perlcode print qq(<hr width="100%">$merci<br>) if $merci; %-->,
qui affiche une ligne horizontale suivie du message de remerciement, uniquement si celui-ci est défini.
Remarque : À cause de la façon de définir (et de lire...) les variables, il faut remplacer certains caractères selon la table suivante :
| remplacer | par |
| < | \074 |
| > | \076 |
| " | \042 |
(ce sont les codes ASCII en octal des caractères correspondants) Par exemple, vous pouvez définir un lien hypertexte dans la variable $merci par :
<META NAME="merci" CONTENT="Merci à \074A HREF=\042mailto:taz98@altern.org\042\076 Jicé\074/a\076 pour l'aide apportée.">
qui s'affichera comme : Merci à Jicé pour l'aide apportée.
Les tags
Liste des tags compris par NAWAK : (les parties facultatives sont entre crochets avec leurs valeurs par défaut.)
| tag | commentaire |
<!--%<b>planchapitre </b> [link="yes"] [separator1="\n<BR>"] [separator2=" "] [levels="1-99"]%--> |
Affiche le plan du fichier source.
|
<!--%<b>planfichier </b> nomfichier="fichier.htm" [nbcolonnes="1"] [link="yes"] [separator1="\n<BR>"] [separator2=" "] [levels="1-99"]%--> |
Affiche le plan du fichier passé en paramètre.
|
<!--%<b>author</b>%--> |
Insère le contenu de la variable $author définie dans l'entête HTML du fichier source. |
<!--%<b>created</b> [format="aaaa"]%--> |
Insère le contenu de la variable $created définie dans l'entête HTML du fichier source. L'argument format est une chaîne contenant jj, mm, aaaa, qui seront remplacés respectivement par le jour du mois, le numéro du mois et l'année. |
<!--%<b>changedby</b>%--> |
Insère le contenu de la variable $changedby définie dans l'entête HTML du fichier source. |
<!--%<b>changed</b> [format="jj/mm/aaaa"]%--> |
Insère le contenu de la variable $changed définie dans l'entête HTML du fichier source. L'argument format est une chaîne contenant jj, mm, aaaa, qui seront remplacés respectivement par le jour du mois, le numéro du mois et l'année. |
<!--%<b>generated</b> [format="jj/mm/aaaa-hh:mm:ss"] %--> |
Insère la date de génération de la page (date courante). L'argument format est une chaîne contenant jj, mm, aaaa, hh, mm, ss, qui seront remplacés respectivement par le jour du mois, le numéro du mois, l'année, l'heure, les minutes et les secondes. |
<!--%<b>title</b>%--> |
Insère le titre de la page. Le titre (variable $title) est ce qui se trouve entre les tags <title> et </title> de l'entête HTML de la page source. |
<!--%<b>fichierchapitre</b>%--> |
Insère le nom du fichier source. (variable $sourcefile). |
<!--%<b>textechapitre</b>%--> |
Insère le corps du fichier source, lui même parsé et dont les éventuels tags ont été interprétés. |
<!--%<b>titresection</b> [link = "yes"] [href = "index.html"] [class = ""]%--> |
Insère le titre de la section.
|
<!--%<b>listechapitres </b> [link = "yes"]%--> |
Affiche la liste des chapitres de la section.
|
<!--%<b>inserefichier</b> nomfichier="fichier.html" ou "$variable" %--> |
Insere le corps du fichier dont le nom est passé par l'argument nomfichier. Le fichier inséré est parsé et les éventuels tags présents dans le corps du fichier sont interprétés. Si nomfichier commence par $, cela indique à NAWAK de prendre le nom du fichier dans la variable dont le nom a été passé par nomfichier. |
<!--%<b>wmlprint</b> varname="la_variable" ou "$la_variable" %--> Synonyme : <!--%$la_variable%--> |
Affiche le contenu de la variable dont le nom est passé par l'argument varname.
La deuxième forme affiche le contenu de la variable également. Le $ est dans ce cas obligatoire. |
<!--%<b>perlcode </b> #le STDOUT de ce code perl #sera inséré dans le résultat du_code_perl; %--> |
Insère le STDOUT (sortie standard) du code PERL dans le fichier résultat.
Allez, tellement il est bien ce tag, je vous en met une partie spécifique sur lui :)(voir ci-dessous) |
Le tag PERLCODE
Ca tag vous permet d'exécuter du code PERL au beau milieu de vos pages (enfin... uniquement à la génération ;). Dans ce tag, vous avez accès à toutes les variables définies en entête HTML du fichier source. Vous pouvez également appeler les tags spécifiques de NAWAK, en positionnant éventuellement les arguments, de la manière suivante :
<!--%perlcode $nomfichier = "toto.html" # argument(s), puis : $r = inserefichier(); # nom du tag suivi de "()". print $r; %-->
Ce qui est équivalent à :
<!--%inserefichier nomfichier="toto.html"%-->
Attention : l'appel d'une fonction de tag réinitialise à undef les variables "arguments".
Vous pouvez aussi positionner des variables qui pourront resservir dans un tag suivant, et utiliser les fonctions helpers définies ci-dessous. Vous pouvez définir de nouvelles fonctions, voire de nouveaux tags, puis les appeler. Par exemple, vous définissez le tag toto dans la template d'entête de page par :
<!--%perlcode sub toto { $link = "no" if !$link; if (($link =~ /yes/)|($link =~ /true/)) { $result = qq(<A HREF="toto.html">TOTO</A>); } else { $result = getTitle("toto.html"); } undef $link; $return; }--%>
Et ensuite vous pouvez l'appeler n'importe où par , et NAWAK vous affichera un joli lien vers toto.html ! (bon je sais c'est pas très utile ce nouveau tag, mais d'ailleurs c'est pour ça qu'il est pas défini par défaut ;)
Extensibilité de NAWAK
Définir de nouveaux tags
Vous avez de plus la possibilité de définir de nouveaux tags, dans la template "de définition de nouveaux éléments" par exemple. Cette définition peut se faire de trois manières différentes. Les trois tags suivants (dont deux nouveaux) définissent tous la même chose : un nouveau tag <!--%nom_du_tag arg1="val1" arg3="val3" [arg2="val2"] [arg4="val4"]%-->, avec 4 arguments, arg1 et arg3 (obligatoires), arg2 et arg4 (optionnels, dont la valeur par défaut est respectivement "defaut2" et "defaut4"). Si les arguments obligatoires ne sont pas présents, ce nouveau tag retourne "defaut".
| tag |
<!--%<b>perlcode
</b>sub nom_du_tag {
return "defaut" if !$arg1;
return "defaut" if !$arg3;
$arg2="defaut2" if !$arg2;
$arg4="defaut4" if !$arg4;
... du code perl qui renvoie une valeur ...
}
%-->
|
<!--%<b>newsimpletag </b> name="nom_du_tag" arguments="arg1,arg2,arg3,arg4" defaultvalues=",defaut2,,defaut4" mandatoryargs="arg1,arg3" defaultreturn="defaut" returnvalue="une_expression" }%--> |
<!--%<b>newtag </b> name="nom_du_tag" arguments="arg1,arg2,arg3,arg4" defaultvalues=",defaut2,,defaut4" mandatoryargs="arg1,arg3" defaultreturn="defaut" perlcode="du code perl positionnant la variable $result" }%--> |
Voyons par exemple la définition d'un nouveau tag COUNT qui affiche tous les entiers de 1 à n, utilisable comme <!--%count from="1" to="12"%-->, l'argument to étant obligatoire, from optionnel avec comme valeur par défaut 1. Avec chacune des trois définitions possibles, cela donne l'exemple suivant :
| définition de <!--%count from="1" to="12"%--> |
<!--%<b>perlcode
</b>sub count {
return if !$to;
$from="1" if !$from;
$result = join ",", ($from..$to);
undef $to;
$result;
}
%-->
|
<!--%<b>newsimpletag </b> name="count" arguments="to,from" defaultvalues=",1" mandatoryargs="to" returnvalue='join ",", ($from..$to)' }%--> |
<!--%<b>newtag </b> name="count" arguments="from,to" defaultvalues="1" mandatoryargs="to" perlcode=' $separator = ","; $result = join $separator, ($from..$to);' }%--> |
Positionner des variables globales
La template "de définition de nouveaux éléments" étant évaluée en premier, vous pouvez définir dedans des variables globales (via un tag PERLCODE), qui seront éventuellement écrasées par les variables locales aux fichier source et templates utilisés. Exemple, l'auteur par défaut :
<!--%perlcode $author="Jean-Christophe Cardot" %-->
Ainsi, les fichiers source ne spécifiant pas d'auteur seront automatiquement attribués à l'auteur par défaut, tandis que ceux spécifiant un auteur dans leur entête (META NAME="author") utiliseront cette valeur.
Les fonctions "helpers"
Les fonctions helpers sont des fonctions internes de NAWAK que vous pouvez appeler dans vos tags PERLCODE, afin de vous aider (comme leur nom l'indique) à accomplir certaines tâches.
getTitle ( $nomfichier );
Renvoie le titre (tag <title>) du fichier passé en paramètre (ou dans $_ à défaut).
getVariableContent ( $nomfichier, $varname );
Renvoie la valeur de la variable $varname du fichier $nomfichier.
Remarque : la variable est définie par <meta name="var" content="val"> dans l'entête HTML du fichier $nomfichier.
warning ( $endroit , $message );
Affiche un message d'avertissement sur STDERR, sous la forme : "NAWAK:$endroit: warning: $message\n".
Un exemple de site
Afin d'illustrer l'utilisation de NAWAK, nous allons décrire ci-dessous son utilisation conjuguée avec make.
Remarque : cet exemple reprend la structure du site "Linux - aide aux débutants".
Make et les makefiles
Tout ça c'est bien beau, mais si on doit se taper les 12 lignes de commande à la main (pour un site de 12 pages !), c'est trop pénible. C'est pour ça qu'on va utiliser make, et donc écrire des fichiers Makefile. Les infos ci-dessous sont une première approche de make, pour plus d'infos, consultez la documentation de make.
Pour simplifier les makefiles et leur maintenance, il est recommandé de définir des variables. Cela se fait simplement en écrivant la ligne "nomvariable = valeur" ; ces variables s'appellent ensuite par $(nomvariable) dans le makefile. On peut aussi regrouper des définitions communes à plusieurs makefiles dans un fichier et les inclure par la commande "include nomfichier".
Ensuite, on définit les "cibles" (c'est à dire par exemple les fichiers résultants), les fichiers dont elles dépendent, et la manière de les obtenir :
cible: fichier_dependant1 fichier_dependant2...
commande pour obtenir la cible
Voir les exemples de makefiles ci-dessous.
Structure du site
Comme un exemple vaut mieux qu'un long discours, regardez les fichiers de l'exemple ci-dessous : (Si la présentation vous saoûle, passez par les fichiers source...)
Commencez par regarder le Makefile principal (répertoire _src), puis parcourez le reste.
Site
|
+--index.htm
+--_src
| |
| +--Common.Makefile
| +--Makefile
| +--edito.htm
| +--index.htm
| +--toto.htm
| +--_tmpl
| | |
| | +--header.htm
| | +--base.htm
| | +--basei.htm
| | +--head.htm
| | +--sections.htm
| +--section1
| | |
| | +--_noms.htm
| | +--_ress_file12.htm
| | +--Makefile
| | +--index.htm
| | +--file11.htm
| | +--file12.htm
| +--section2
| |
| +--_noms.htm
| +--Makefile
| +--index.htm
| +--file21.htm
+--section1
| |
| +--index.htm
| +--file1.htm
+--section2
|
+--index.htm
+--file1.htm
Pour générer le site entier, il suffit de se placer dans le répertoire _src et de lancer la commande 'make' :
et uniquement les fichiers nécessaires sont regénérés.
Annexe : exemple de template
Template d'entête HTML (head.htm)
<html> <head>
<!-- c'est normal que ce fichier ait l'air bizarre :) c'est juste le template des <HEAD>... -->
</head>
<body><!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="robots" content="follow">
<meta name="GENERATOR"
content="/">
<meta name="Description" content="">
<meta name="KeyWords" content="mot1, mot2, mot3">
<meta name="Author" content="">
<style type="text/css"><!--
.yellowb { color:#FFCC99;font-size:medium;font-weight:700; }
.blueb { color:#0080C0;font-size:medium;font-weight:700; }
--> </style>
<title></title> </head>
</body> </html>