Version du 6 juin 2013 à 14:43

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  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="images/titre.png" ALT="Titre"> ou

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 :

Par exemple, le tag  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.

@@ Ligne 21 : / Ligne 21 : @@
 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 [[NAWAK Consignes pour les contributions|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, [[NAWAK#Extensibilité de NAWAK|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'[[NAWAK#Extensibilité de NAWAK|extensibilité]] de NAWAK. Remarque : toute éventuelle sortie générée par cette template sera ignorée.
+<table border="">
+<tr align="CENTER">
+<td width="20%"><b>Fichier résultant</b></td>
+<td><b>Commentaires</b></td>
+</tr>
+<tr>
+<td>
+<pre>&lt;HTML&gt;
+&lt;HEAD&gt;
+...
+&lt;/HEAD&gt;</pre>
+</td>
+<td>En tête du fichier HTML, se trouve le résultat de la <b>template d'entête HTML</b> (comme son nom l'indique <tt>;)</tt>, c'est à dire ce qui se trouvait entre les tags <tt>&lt;BODY&gt;</tt> et <tt>&lt;/BODY&gt;</tt> de cette template, parsé et interprété par NAWAK. <br>Si cette template n'est pas définie, NAWAK génère une entête par défaut.</td>
+</tr>
+<tr>
+<td>
+<pre>&lt;BODY ... &gt;</pre>
+</td>
+<td>Dans sa version actuelle, NAWAK copie ici le contenu du tag <tt>&lt;BODY...&gt;</tt> de la template de base.</td>
+</tr>
+<tr>
+<td>en-tête de page</td>
+<td>Si elle existe, contenu de la <b>template d'entête de page</b>, parsé et interprété.</td>
+</tr>
+<tr>
+<td>corps de la page</td>
+<td>Contenu de la <b>template de corps</b> (ou template de base), parsé et interprété.</td>
+</tr>
+<tr>
+<td>pied de page</td>
+<td>Si elle existe, contenu de la <b>template de pied de page</b>, parsé et interprété.</td>
+</tr>
+<tr>
+<td>
+<pre>&lt;/BODY&gt;
+&lt;/HTML&gt;</pre>
+</td>
+<td>Généré.</td>
+</tr>
+</table>
+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 [[NAWAK#Annexe : exemple de template|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 [[NAWAK#Métalangage|tags spéciaux]] sont interprétés par NAWAK.
+<div class="code">
+Usage:
+nawak -s sourcefile
+       -o outputfile
+       [-a headtemplate]
+       [-t headertemplate]
+       -b basetemplate
+       [-f footertemplate]
+       [-e newelementstemplate]
+       [-D variable="valeur",...]
+nawak -h
+       prints this help
+</div>
+Entre crochets : facultatif.
+Exemple de ligne de commande (sur une seule ligne) :
+<div class="code">
+[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="../"
+</div>
+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 :
+<NOWIKI>
+<IMG SRC="<!--%$root%-->images/titre.png" ALT="Titre">
+</NOWIKI>
+ou
+<NOWIKI>
+<!--%inserefichier nomfichier=$root."_templates/sections.htm"%-->
+</NOWIKI>
+== 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 :
+<NOWIKI> <!--%commande (nom_argument=["|']valeur_argument["|'])*%--> </NOWIKI>
+Par exemple, le tag <NOWIKI> <!--%generated format="jj-mm-aaaa"%--> </NOWIKI> 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 :
+ <!--%inserefichier nomfichier="$ressources"%-->
+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 &agrave; 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 :
+ <NOWIKI><!--%perlcode
+ print qq(<hr width="100%">$merci<br>) if $merci; %-->,</NOWIKI>
+qui affiche une ligne horizontale suivie du message de remerciement, uniquement si celui-ci est défini.

« NAWAK » : différence entre les versions

Version du 6 juin 2013 à 14:43

Sommaire

NAWAK

Introduction

Concepts

Pré-requis

Les templates

Le Métalangage

Les variables

Menu de navigation

« NAWAK » : différence entre les versions

Version du 6 juin 2013 à 14:43

NAWAK

Introduction

Concepts

Pré-requis

Les templates

Le Métalangage

Les variables

Menu de navigation

« NAWAK » : différence entre les versions