Différences entre les versions de « Web Howto »

De April MediaWiki
Aller à la navigationAller à la recherche
m (a déplacé WebHowto vers Web Howto : Le CamelCase saÿmal)
m
Ligne 3 : Ligne 3 :
 
=HOWTO WEB=
 
=HOWTO WEB=
  
_'''Contribuer au site web d'APRIL'''_
+
_'''Contribuer au site web d'April'''_
  
 
Benjamin Drieu <bdrieu@april.org>
 
Benjamin Drieu <bdrieu@april.org>
 
Mis à jour par Benoît Sibaud <bsibaud @ april.org>
 
Mis à jour par Benoît Sibaud <bsibaud @ april.org>
  
Ce document a pour but d'expliquer en détails comment effectuer des mises à jour sur le site web d'APRIL. Il ne peut bien sûr pas espérer tout documenter. Des liens à la fin de la page vous permettront j'espère de résoudre tout manque potentiel.
+
Ce document a pour but d'expliquer en détails comment effectuer des mises à jour sur le site web de l'April. Il ne peut bien sûr pas espérer tout documenter. Des liens à la fin de la page vous permettront j'espère de résoudre tout manque potentiel.
  
 
==Où trouver ce document==
 
==Où trouver ce document==
  
Cet article est un document de travail de l'association APRIL. Si vous travaillez à la maintenance du site web de l'association, vous êtes de plus encouragés à maintenir ce document.
+
Cet article est un document de travail de l'association April. Si vous travaillez à la maintenance du site web de l'association, vous êtes de plus encouragés à maintenir ce document.
  
 
==Pour les pressés==
 
==Pour les pressés==
Ligne 64 : Ligne 64 :
 
==Principes fondamentaux==
 
==Principes fondamentaux==
  
Le site web de l'association APRIL possède deux spécificités bien particulières dont les mainteneurs doivent prendre conscience pour éviter de perdre du temps inutilement :
+
Le site web de l'association April possède deux spécificités bien particulières dont les mainteneurs doivent prendre conscience pour éviter de perdre du temps inutilement :
  
 
**** l'utilisation de SVN pour permettre des accès concurrents et coopératifs à l'arborescence du site web ;
 
**** l'utilisation de SVN pour permettre des accès concurrents et coopératifs à l'arborescence du site web ;
Ligne 97 : Ligne 97 :
 
==Gestion des tâches de webmestre==
 
==Gestion des tâches de webmestre==
  
Afin de coordonner tout le monde, l'APRIL s'est dotée d'un outil spécifique: [http://dotproject.april.org dotProject]. En effet, tout le monde ne peut se réunir chaque semaine, il est donc important de bien distribuer les travaux, de garder traces des tâches faites/à faire/qui s'en est occupé, etc. Demandez à un admin de vous créer un compte.
+
Afin de coordonner tout le monde, l'April s'est dotée d'un outil spécifique: [http://dotproject.april.org dotProject]. En effet, tout le monde ne peut se réunir chaque semaine, il est donc important de bien distribuer les travaux, de garder traces des tâches faites/à faire/qui s'en est occupé, etc. Demandez à un admin de vous créer un compte.
  
 
Ensuite, pour chaque tâche de webmestre que vous ne puissiez faire en 2 secondes (pas les modifications de typo, quoi), il faut créer une tâche dans l'outil. Au fur et à mesure que la tâche avance, il faut mettre à jour l'entrée. Une fois finie, la tâche doit être fermée avec les modifications faîtes en commentaire (Comme ça, si le cas se représente, on sait comment faire).
 
Ensuite, pour chaque tâche de webmestre que vous ne puissiez faire en 2 secondes (pas les modifications de typo, quoi), il faut créer une tâche dans l'outil. Au fur et à mesure que la tâche avance, il faut mettre à jour l'entrée. Une fois finie, la tâche doit être fermée avec les modifications faîtes en commentaire (Comme ça, si le cas se représente, on sait comment faire).
Ligne 125 : Ligne 125 :
 
Voici en vrac quelques recommandations que les webmestres aimeraient vous voir suivre. Leurs soucis principaux sont la cohérence du site (tant sur le plan architectural que sur le plan graphique) et sa maintenance :
 
Voici en vrac quelques recommandations que les webmestres aimeraient vous voir suivre. Leurs soucis principaux sont la cohérence du site (tant sur le plan architectural que sur le plan graphique) et sa maintenance :
  
**** lorsque plusieurs documents doivent être référencés dans une page d'index, utilisez une liste (balise <ul><li>...</ul>) et faites un lien à partir de chacun des items de la liste. Au besoin, vous pouvez écrire un texte au dessus de la liste et séparer les deux parties par un filet horizontal (<hr>) Voyez par exemple la page d'accueil du laboratoire APRIL http://www.april.org/groupes/labo.
+
**** lorsque plusieurs documents doivent être référencés dans une page d'index, utilisez une liste (balise <ul><li>...</ul>) et faites un lien à partir de chacun des items de la liste. Au besoin, vous pouvez écrire un texte au dessus de la liste et séparer les deux parties par un filet horizontal (<hr>) Voyez par exemple la page d'accueil du laboratoire April http://www.april.org/groupes/labo.
 
**** Passez les pages à ASPELL/ISPELL, ou tout autre correcteur orthographique. Une page qui contient des fautes d'orthographe ou de grammaire n'est pas crédible. De plus, essayer de vous faire relire si c'est possible (au besoin, une relecture de la page à tête reposée élimine 90% des fautes). N'hésitez pas à envoyer un courriel aux webmestres si vous avez besoin d'un relecteur.
 
**** Passez les pages à ASPELL/ISPELL, ou tout autre correcteur orthographique. Une page qui contient des fautes d'orthographe ou de grammaire n'est pas crédible. De plus, essayer de vous faire relire si c'est possible (au besoin, une relecture de la page à tête reposée élimine 90% des fautes). N'hésitez pas à envoyer un courriel aux webmestres si vous avez besoin d'un relecteur.
 
**** Si possible, veuillez respecter la convention typographique américaine de séparation entre deux phrases : passez deux espaces après un point. Cela permet d'utiliser les fonctions de manipulation de phrases sous Emacs (à savoir M-a, M-e, M-k, etc.).
 
**** Si possible, veuillez respecter la convention typographique américaine de séparation entre deux phrases : passez deux espaces après un point. Cela permet d'utiliser les fonctions de manipulation de phrases sous Emacs (à savoir M-a, M-e, M-k, etc.).
Ligne 138 : Ligne 138 :
 
==Tâches administratives==
 
==Tâches administratives==
  
Tout mainteneur du site web d'APRIL sera amené à effectuer différentes tâches telles que la création de répertoire, la création de rubriques, la mise à jour de pages, ...
+
Tout mainteneur du site web de l'April sera amené à effectuer différentes tâches telles que la création de répertoire, la création de rubriques, la mise à jour de pages, ...
  
 
===Environnement de travail===
 
===Environnement de travail===
  
La première chose à faire est de se créer un miroir local de l'arborescence du site web d'APRIL. Étant donné que la totalité du web fait plus d'un giga-octets, ne copiez que la partie sur laquelle vous voulez travailler.
+
La première chose à faire est de se créer un miroir local de l'arborescence du site web de l'April. Étant donné que la totalité du web fait plus d'un giga-octets, ne copiez que la partie sur laquelle vous voulez travailler.
  
 
Comme expliqué dans la section SVN, nous utilisons SVN pour effectuer le contrôle des versions des documents et assurer l'accès concurrent au web. Vous devez donc avoir installé SVN sur votre machine. Voir le svn-howto pour savoir comment l'installer et l'utiliser. Si vous ne possédez pas SVN, vous pouvez toujours utiliser svnweb (TODO non remis en place...) pour accéder à notre arborescence SVN via le web, ou en dernière limite envoyer vos contributions par courriel aux webmestres (webmaster@april.org).
 
Comme expliqué dans la section SVN, nous utilisons SVN pour effectuer le contrôle des versions des documents et assurer l'accès concurrent au web. Vous devez donc avoir installé SVN sur votre machine. Voir le svn-howto pour savoir comment l'installer et l'utiliser. Si vous ne possédez pas SVN, vous pouvez toujours utiliser svnweb (TODO non remis en place...) pour accéder à notre arborescence SVN via le web, ou en dernière limite envoyer vos contributions par courriel aux webmestres (webmaster@april.org).
  
Prenons un exemple pour simplifier. Si vous désirez ajouter un article au laboratoire APRIL, vous effectuerez :
+
Prenons un exemple pour simplifier. Si vous désirez ajouter un article au laboratoire April, vous effectuerez :
  
 
<pre>
 
<pre>
Ligne 274 : Ligne 274 :
 
Placez de préférence le fichier index.html à la fin de cette liste afin qu'il soit compilé à la fin (faute de quoi, pendant une courte période, nous risquons d'avoir des liens invalides sur le serveur web). Le fichier index.html est le fichier d'index généré à partir du fichier index.wml que vous devrez placer dans le répertoire et mettre à jour s'il ne l'est pas.
 
Placez de préférence le fichier index.html à la fin de cette liste afin qu'il soit compilé à la fin (faute de quoi, pendant une courte période, nous risquons d'avoir des liens invalides sur le serveur web). Le fichier index.html est le fichier d'index généré à partir du fichier index.wml que vous devrez placer dans le répertoire et mettre à jour s'il ne l'est pas.
  
Vous ne maîtrisez pas les options de compilation qui sont fixées dans le fichier /var/www/www.april.org/include/april/Makefile.rules. Si, sur votre propre machine, vous n'avez pas placé le fichier Makefile.rules à cet endroit là, modifiez ce chemin pour refléter celui où vous l'avez placé afin de vérifier le bon fonctionnement de la compilation AVANT de penser à effectuer un commit. MAIS N'OUBLIEZ PAS DE REMETTRE LA VALEUR ORIGINALE DANS LE MAKEFILE AVANT D'EFFECTUER UN COMMIT !!! Il faut en effet que les fichiers utilisent /var/www/www.april.org/include/april/Makefile.rules sur le web d'APRIL.
+
Vous ne maîtrisez pas les options de compilation qui sont fixées dans le fichier /var/www/www.april.org/include/april/Makefile.rules. Si, sur votre propre machine, vous n'avez pas placé le fichier Makefile.rules à cet endroit là, modifiez ce chemin pour refléter celui où vous l'avez placé afin de vérifier le bon fonctionnement de la compilation AVANT de penser à effectuer un commit. MAIS N'OUBLIEZ PAS DE REMETTRE LA VALEUR ORIGINALE DANS LE MAKEFILE AVANT D'EFFECTUER UN COMMIT !!! Il faut en effet que les fichiers utilisent /var/www/www.april.org/include/april/Makefile.rules sur le web de l'April.
  
 
===Compilation avec ajout de commandes===
 
===Compilation avec ajout de commandes===
 
Cas du format SGML
 
Cas du format SGML
  
Note : le SGML est voué à disparaître du SVN APRIL (remplacé par du XML Docbook ou du WML)
+
Note : le SGML est voué à disparaître du SVN April (remplacé par du XML Docbook ou du WML)
  
 
Autres commandes
 
Autres commandes
Ligne 359 : Ligne 359 :
 
Le user est edit, les webmestres ont le mot de passe.
 
Le user est edit, les webmestres ont le mot de passe.
  
Une fois dessus, on peut soit ajouter une personne, soit lister les personnes pour édition ou effacement. Les champs par personne sont: prénom, nom, dit (pour un surnom), la fonction de la personne au sein de l'APRIL, éventuellement une URL personnelle et l'image. Sachez encore que l'image doit être au format PNG et aucune de ses dimensions ne peut être plus grande que 150 pixels.
+
Une fois dessus, on peut soit ajouter une personne, soit lister les personnes pour édition ou effacement. Les champs par personne sont: prénom, nom, dit (pour un surnom), la fonction de la personne au sein de l'April, éventuellement une URL personnelle et l'image. Sachez encore que l'image doit être au format PNG et aucune de ses dimensions ne peut être plus grande que 150 pixels.
  
 
La page publique du trombino est http://www.april.org/association/trombinoscope/.
 
La page publique du trombino est http://www.april.org/association/trombinoscope/.
Ligne 375 : Ligne 375 :
 
==La liste webmasters==
 
==La liste webmasters==
  
La liste webmasters@april.org est la liste de diffusion autour de laquelle communiquent les webmestres d'APRIL. C'est aussi celle-ci qui reçoit les commentaires des utilisateurs du site web. Il est d'usage d'informer les autres webmestres de ses travaux par le biais de cette liste. En cas de problème ou si vous avez besoin de conseils, cette liste est faite pour vous.
+
La liste webmasters@april.org est la liste de diffusion autour de laquelle communiquent les webmestres de l'April. C'est aussi celle-ci qui reçoit les commentaires des utilisateurs du site web. Il est d'usage d'informer les autres webmestres de ses travaux par le biais de cette liste. En cas de problème ou si vous avez besoin de conseils, cette liste est faite pour vous.
  
Si vous voulez contribuer au site web d'APRIL, la première chose est d'envoyer un courriel aux webmestres afin de vous inscrire à cette liste et d'obtenir un accès SVN au web.
+
Si vous voulez contribuer au site web de l'April, la première chose est d'envoyer un courriel aux webmestres afin de vous inscrire à cette liste et d'obtenir un accès SVN au web.
  
  

Version du 19 juillet 2012 à 13:35

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

HOWTO WEB

_Contribuer au site web d'April_

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

Ce document a pour but d'expliquer en détails comment effectuer des mises à jour sur le site web de l'April. Il ne peut bien sûr pas espérer tout documenter. Des liens à la fin de la page vous permettront j'espère de résoudre tout manque potentiel.

Où trouver ce document

Cet article est un document de travail de l'association April. Si vous travaillez à la maintenance du site web de l'association, vous êtes de plus encouragés à maintenir ce document.

Pour les pressés

Vous connaissez déjà Subversion/SVN (qui permet des accès concurrents et coopératifs à l'arborescence du site web) et WML (qui est utilisé pour composer les pages web) et souhaitez donc aller à l'essentiel. Les admins vous ont créé un compte pour accéder au SVN.

Première étape, récupérer les fichiers du site web. Pour cela il faut positionner correctement le dépôt SVN et lancer un checkout. Si votre compte est 'moi' voici les commandes :

$ svn checkout svn+ssh://moi@april.org/var/lib/svn/web/trunk/htdocs

Il existe un dépôt /var/lib/svn/admins/trunk/htdocs et /var/lib/svn/ca/trunk/htdocs pour respectivement les parties admins et ca du site.

Vous récupérez ainsi le contenu du répertoire htdocs qui contient l'arboresence des fichiers wml du site web (ainsi l'url http://www.april.org/groupes/index.html correspondra au fichier htdocs/groupes/index.wml).

Ensuite vous pouvez modifier les fichiers en local et envoyer les modifications sur le serveur, par ex :

$ cd htdocs/groupes/
$ vi index.wml
$ svn commit

Le fichier index.wml modifié est envoyé sur le serveur. Vous être fortement encourage à utiliser la commande tidy pour vérifier que la syntaxe du fichier wml est correcte, par exemple :

tidy -e -xml index.wml

Il existe par ailleurs un script automatique htdocs/webcheck.sh qui effectue diverses analyses sur la validité du dépôt SVN côté serveur.

Attention le SVN utilise le jeu de caractères ISO-8859-15. Si vous rencontrez des soucis sur les « locales », utilisez les commandes suivantes au préalable à vos opérations SVN :

$ LC_ALL=fr_FR@euro LANG=fr_FR@euro
$ export LC_ALL LANG

Toutes les heures le site web est synchronisé avec le contenu de l'arborescence SVN. Pour forcer une synchronisation immédiate il suffit de lancer la commande suivante (si vous y êtes autorisé...) :

$ ssh www-data@april.org

Vous ne devez pas faire un checkout à chaque fois : il suffit d'utiliser update, par ex :

$ cd htdocs
$ svn update

Principes fondamentaux

Le site web de l'association April possède deux spécificités bien particulières dont les mainteneurs doivent prendre conscience pour éviter de perdre du temps inutilement :

        • l'utilisation de SVN pour permettre des accès concurrents et coopératifs à l'arborescence du site web ;
        • l'utilisation de WML pour assurer le travail de composition de documents HTML (la personne chargée d'entretenir un ensemble de pages n'a pas à se soucier de la charte web de l'association ni même de la connaître).

SVN

SVN permet d'assurer l'accès concurrent aux pages du serveur web. Le SVN permet de plus de gérer les versions successives des documents. Le principe est que chaque fois qu'un contributeur veut mettre à jour une partie du site web, il télécharge par le biais de SVN une copie des documents sur lesquels il désire travailler sur son disque local. Il modifie et teste ces documents, puis, à nouveau par SVN, les met à jour sur le serveur. Voir le document howto-svn pour plus d'informations à ce sujet.

Typiquement, une session se déroule ainsi :


$ svn update htdocs/index.wml
$ vi htdocs/index.wml
$ svn commit htdocs/index.wml
<svn demande de saisir un texte pour logguer les modifications>
Envoi          htdocs/index.wml
Transmission des données .
Révision 11073 propagée.


WML

Voir le howto-wml pour plus de précisions à ce sujet.

En deux mots, WML est un langage de macros qui, une fois compilé, produit de l'HTML. Une suite d'outils écrits en Perl permettent de passer (par le biais d'étapes successives) d'un code WML à un code HTML.

Le langage est compilé une bonne fois pour toute, ce qui permet d'inclure des directives de haut niveau sans surcharger le serveur web (en revanche, la compilation est lente). Parmi les fonctionnalités, il est possible d'inclure du code Perl dans un document WML, qui sera interprété à la compilation. Le serveur sert quant à lui des pages HTML et conserve donc ses possibilités (par exemple l'insertion de server-side includes).

Gestion des tâches de webmestre

Afin de coordonner tout le monde, l'April s'est dotée d'un outil spécifique: dotProject. En effet, tout le monde ne peut se réunir chaque semaine, il est donc important de bien distribuer les travaux, de garder traces des tâches faites/à faire/qui s'en est occupé, etc. Demandez à un admin de vous créer un compte.

Ensuite, pour chaque tâche de webmestre que vous ne puissiez faire en 2 secondes (pas les modifications de typo, quoi), il faut créer une tâche dans l'outil. Au fur et à mesure que la tâche avance, il faut mettre à jour l'entrée. Une fois finie, la tâche doit être fermée avec les modifications faîtes en commentaire (Comme ça, si le cas se représente, on sait comment faire).

Linkchecker

Pour les liens morts, nous avons un outil qui fait un rapport chaque samedi. Le rapport est ici: http://www.april.org/stats/linkcheck.report.www.april.org. Bien qu'il ne faille pas penser que chaque lien est à corriger (par ex. ce qui est dans /groupes/gnufr/work/ n'est, sauf erreur, pas public, la responsabilité en incombe donc au groupe gnufr)


Charte graphique et conventions

Pour simplifier l'administration du site web tout comme pour assurer sa cohérence, il est nécessaire de fixer une charte rédactionnelle et graphique et de s'y tenir. L'utilisation de WML nous a déjà permis de nous abstraire un maximum des obligations de mise en page HTML, mais un certain nombre de points doivent être respectés lors de la rédaction de documents.

Ce qu'il ne faut pas faire

Mise en page

        • Pas d'images GIF. En raison de problèmes de licences (voir http://gnu.april.org/philosophy/gif.fr.html ), l'utilisation du format GIF est prohibé sur le serveur web de l'association. Quelques images au format GIF sont toutefois sur le serveur web, mais il s'agit de contributions de personnes tierces (supports de conférences par exemple). Nous avons préféré ne pas altérer de tels documents.
        • L'utilisation d'images doit rester exceptionnelle. Par exemple, l'insertion de sphères en lieu et place des puces générées par la balise
        • est du plus mauvais goût.

Balises HTML

Il est possible d'utiliser des balises HTML dans du code WML, mais nous nous limitons à un jeu restreint de balises HTML car cela revient à déroger à la charte graphique mise en place au moyen de WML.

Ce qu'il faut faire

Voici en vrac quelques recommandations que les webmestres aimeraient vous voir suivre. Leurs soucis principaux sont la cohérence du site (tant sur le plan architectural que sur le plan graphique) et sa maintenance :

        • lorsque plusieurs documents doivent être référencés dans une page d'index, utilisez une liste (balise
          • ...
          ) et faites un lien à partir de chacun des items de la liste. Au besoin, vous pouvez écrire un texte au dessus de la liste et séparer les deux parties par un filet horizontal (
          ) Voyez par exemple la page d'accueil du laboratoire April http://www.april.org/groupes/labo.
        • Passez les pages à ASPELL/ISPELL, ou tout autre correcteur orthographique. Une page qui contient des fautes d'orthographe ou de grammaire n'est pas crédible. De plus, essayer de vous faire relire si c'est possible (au besoin, une relecture de la page à tête reposée élimine 90% des fautes). N'hésitez pas à envoyer un courriel aux webmestres si vous avez besoin d'un relecteur.
        • Si possible, veuillez respecter la convention typographique américaine de séparation entre deux phrases : passez deux espaces après un point. Cela permet d'utiliser les fonctions de manipulation de phrases sous Emacs (à savoir M-a, M-e, M-k, etc.).
        • Mettez un espace insécable (appelé aussi espace non bloquant) avant les ponctuations doubles, à savoir les caractères suivants : ; : ? !. Un espace insécable est obtenu avec la séquence  . Le but est d'éviter qu'un de ces caractères se retrouve orphelin au début d'une ligne. Espace insécable après « et avant ».
        • Il n'y a pas d'expace devant les ponctuations simples, à savoir les caractères suivants : . ,.
        • Il n'y a pas d'espace à l'intérieur des parenthèses mais un espace à l'extérieur : il y a ainsi un espace avant la parenthèse ouvrante ( mais pas après. Pour la parenthèse fermante ), c'est le contraire.
        • Une phrase commence avec une majuscule et s'arrête au point. Entre ces deux éléments, l'usage des majuscules ne doit pas être excessif (noms propres, acronymes, etc.). Il n'y a donc pas de majuscule après un point virgule. De plus, les majuscules sont elles aussi accentuées.
        • Une liste d'éléments est sensée commencer au symbôle ":" et s'arrêter au point. Chaque élément est suivi d'un point virgule final, excepté le dernier qui est suivi d'un point.
        • Il n'y a pas de virgule devant l'élément de coordination « et » en français ! Elle n'est présente que rarement pour mettre un élément en valeur. Par défaut, abstenez-vous d'en mettre. Elle est par contre nécessaire en anglais devant « and » (d'où la confusion de certaines personnes).
        • Nous considérons néanmoins que le contenu est plus important que la forme, donc le texte est primordial. N'hésitez donc pas à espacer tous les paragraphes de balises

          pour une meilleure lisibilité et n'abusez pas des polices. La lisibilité passe avant tout.

Tâches administratives

Tout mainteneur du site web de l'April sera amené à effectuer différentes tâches telles que la création de répertoire, la création de rubriques, la mise à jour de pages, ...

Environnement de travail

La première chose à faire est de se créer un miroir local de l'arborescence du site web de l'April. Étant donné que la totalité du web fait plus d'un giga-octets, ne copiez que la partie sur laquelle vous voulez travailler.

Comme expliqué dans la section SVN, nous utilisons SVN pour effectuer le contrôle des versions des documents et assurer l'accès concurrent au web. Vous devez donc avoir installé SVN sur votre machine. Voir le svn-howto pour savoir comment l'installer et l'utiliser. Si vous ne possédez pas SVN, vous pouvez toujours utiliser svnweb (TODO non remis en place...) pour accéder à notre arborescence SVN via le web, ou en dernière limite envoyer vos contributions par courriel aux webmestres (webmaster@april.org).

Prenons un exemple pour simplifier. Si vous désirez ajouter un article au laboratoire April, vous effectuerez :

$ svn checkout svn+ssh://moi@april.org/var/lib/svn/web/trunk/htdocs/groupes/labo

Voilà, SVN a créé un répertoire htdocs/groupes/labo dans le répertoire courant et l'a peuplé des différents fichiers et sous-répertoires qu'il contient. Vous êtes maintenant prêt à les éditer.

Modification d'un fichier

Vous avez decelé une faute d'orthographe ? Vous aimeriez contribuer la rédaction d'un document ? Un lien est défectueux ? Vous allez devoir modifier un fichier HTML/XML/WML.

La première chose à faire est de télécharger la page source WML à partir du site SVN. Par exemple supposons que vous souhaitez travailler sur le document htdocs/secure/members/index.html, la commande svn pour télécharger une version du document sera :


$ svn checkout svn+ssh://moi@april.org/var/lib/svn/web/trunk/htdocs/secure/members/index.wml

Vous devez ensuite apporter vos modifications à l'aide de votre éditeur de texte préféré. Attention au format du fichier ! Dans notre exemple nous travaillons sur un document écrit en WML. Vous pouvez être également amené à éditer des documents HTML et XML.

Testez vos modifications si vous avez installé WML en local (voir le wml-howto) et ensuite mettez le fichier en ligne (à l'aide de svn commit). Voici la commande svn correspondant au document de notre exemple précédent :


$ svn commit -m "Correction de fautes d'orthographe" htdocs/secure/members/index.wml

SVN a besoin d'une description de votre modification. Essayez d'être le plus clair et concis. Une description du genre « Ajout de modifications » n'aidera pas le mainteneur à comprendre ce que vous avez modifié. Mais ne soyez pas trop verbeux (une ou deux lignes suffisent). Dans notre exemple la description est « Correction de fautes d'orthographe ».

Si vous avez effectué des modifications relativement importantes à un fichier (ajout d'un paragraphe, correction massive de fautes d'orthographe, remise en page, ...), il est de bon ton d'en avertir l'auteur original.

Création d'un fichier

Typiquement, vous avez écrit un article, traduit un texte (par exemple de GNU) ou vous ajoutez un complément d'informations dans un document. Votre fichier est au format WML (voir le howto-wml).

La première chose à faire est de l'intégrer dans votre copie locale du web (voir section Environnement de travail). Puis vous copiez le fichier dans le répertoire où vous désirez le faire apparaître. Cela pourrait se traduire par les commandes suivantes :

$ cd ma_copie_locale_du_web
$ emacs fichier.wml
$ cp fichier.wml copie_du_web_recuperée_par_svn/fichier.wml
$ cd copie_du_web_recuperée_par_svn
$ svn add fichier.wml
$ svn commit

Bien sûr, vous avez déjà vérifié que ce fichier est correct (i.e. aucune faute d'orthographe ; création du Makefile adéquat ; la génération de la version HTML du fichier ne pose pas de problème ; le fichier HTML généré ne contient pas d'erreur ; etc.) car le commit le met sur la copie finale du serveur web, où il sera compilé et mis en ligne quelques minutes plus tard.

Il vous reste maintenant à l'annoncer. Si j'ai le temps, j'écrirai un script qui effectue cette tâche tout seul. En attendant, la procédure est manuelle. Voir la section Annoncer une modification.

Création de répertoires

Tous les répertoires du site web comportent des caractéristiques communes :

        • un nom en lettres minuscules ;
        • un fichier Makefile qui permet la création des documents finaux du répertoire. Dans la plupart des cas il s'agit de compiler du WML ;
        • un fichier index.wml sauf dans le cas de répertoires contenant des fichiers à télécharger.

Dans la mesure du possible, évitez de créer une arborescence trop profonde (trop de répertoires imbriqués). Le maximum souhaitable pour accéder à une page web est trois niveaux de profondeur (par exemple /actions/bouffe/11091999/). S'il devient nécessaire de créer une arborescence plus profonde, c'est que le web est mal organisé.

NE PAS CRÉER DE LIENS SYMBOLIQUES D'UN RÉPERTOIRE À UN AUTRE !!! SVN ne suit en effet pas les liens symboliques. Au besoin, effectuez des liens hypertextes, c'est à dire, mettez dans votre document un lien HTML vers le document en question.

Les fichiers Makefile profitent de l'héritage d'un fichier Makefile de référence. Voir la section Le Makefile pour une référence complète à ce sujet.

Le fichier index.wml est nécessaire pour effectuer des liens vers les sous-répertoires (chacun d'entre eux fait un lien vers le fichier index.html du niveau supérieur). De plus, ça facilite la navigation. Voir le wml-howto pour une référence complête de WML. Voir aussi la section Charte graphique.

Il serait souhaitable de discuter d'abord avec l'équipe des webmasters de la pertinence de la position du nouveau répertoire, puis vous pourrez ajouter ce répertoire à l'arborescence SVN :


$ cd htdocs
$ mkdir mon_répertoire
$ svn add -N htdocs/mon_répertoire
$ cd htdocs/mon_répertoire
$ svn add -N Makefile index.wml mon_fichier.wml
$ svn commit

(TODO : obsolète ?) Si ce répertoire est appelé à être utilisé souvent, vous devriez ajouter une entrée dans le script include/april/urls.pl (c'est sa position dans l'arborescence SVN) et utiliser la nouvelle balise pour y faire référence. N'oubliez pas d'informer AVANT l'équipe des webmestres de votre souhait (l'ajout dans le script), de l'ajouter effectivement s'ils sont d'accord et de mettre à jour le wml-howto.

Un script disponible sur le serveur web de GNU permet de lister les URL qui ne sont pas accessibles facilement depuis la page d'accueil. Peut-être serait il souhaitable de l'utiliser pour effectuer ce travail ?

Écriture d'un article

Chaque contributeur est le bienvenu. Chacun est libre d'avoir ses opinions et de les exprimer. Si vous désirez écrire un article et le publier sur le serveur web c'est possible.

Cependant, il serait regrettable que des documents engageant l'association soient publiés n'importe comment. Tout document publié dans la partie articles doit être soumis au CA pour approbation.

Une fois approuvé, il doit être mis en forme au format WML et placé dans l'arborescence /articles/divers/. Vous devez ajouter un lien de la page d'index de la partie «Articles» vers votre fichier en utilisant les autres liens comme modèle.

Les statistiques

(TODO: oboslète) Des statistiques sont effectuées par le programme webalizer. Il se charge de générer des pages HTML ainsi que des tableaux et des graphiques représentant l'évolution de la fréquentation du site. Le répertoire où sont stockés les fichiers HTML correspondants est /usr/local/apache/htdocs/stats/. Ce répertoire n'est pas dans l'arbre SVN, attention à ne pas l'effacer maladroitement. Le fichier de configuration de webalizer est /usr/local/http/conf/webalizer.conf. L'URL des statistiques de webalizer: http://www.april.org/stats/.

(TODO: oboslète) D'autres statistiques en texte seul et plus complètes sont effectuées par analog. Il se charge de générer une page HTML avec des images (barres rouges). Le répertoire où sont stockées ces images est /usr/local/apache/icons/analog. La page est dans /usr/local/analog/analog.html. Ce répertoire & la page ne sont pas dans l'arbre SVN, attention à ne pas les effacer maladroitement. Le fichier de configuration d'analog est /usr/local/analog/analog.cfg. Deux alias dans la config d'apache font pointer ces stats à l'URL: http://www.april.org/analog.html.

Annoncer une modification

Annoncez votre modification sur la liste des webmestres.

Ajoutez l'annonce dans la page d'accueil si votre modification le mérite. Au besoin, supprimez les annonces obsolètes (plus de deux/trois annonces, ça commence à surcharger la page). Essayez de faire court, avec un lien hypertexte ; le fichier à modifier est serveur/april.xml, au format RSS.

Le Makefile

Pour plus de facilité, tout répertoire contenant des documents doit aussi comporter un fichier Makefile afin de permettre la compilation des documents WML et XML. Il est de plus utilisé lorsque le web est exporté à partir de l'archive SVN vers la copie effectivement utilisée par le serveur web Apache.

Compilation simple (HTML, WML)

Si vous ajoutez un fichier à l'arborescence du serveur web, vous devez ajouter votre fichier dans le Makefile afin qu'il puisse être compilé sur le serveur web.

Dans le Makefile, deux variables sont utilisées pour spécifier les fichiers WML ou HTML à compiler et les sous-répertoires à visiter ensuite. Il s'agit des variables FILES et SUBDIRS.

Par exemple, dans le fichier Makefile suivant, on compile les fichiers index.wml et err404.wml, et on visite ensuite les répertoires actions et groupes :


FILES=err404.html index.html
SUBDIRS=actions groupes

include /var/www/www.april.org/include/april/Makefile.rules

Votre Makefile doit donc ressembler à celui-ci, aux fichiers près.

Notez qu'on spécifie par le biais de la variable FILES soit les cibles à compiler (fichiers WML avec extension en .html par exemple), soit les fichiers HTML finaux. make utilise les fichiers wml correspondants en tant que dépendance.

Placez de préférence le fichier index.html à la fin de cette liste afin qu'il soit compilé à la fin (faute de quoi, pendant une courte période, nous risquons d'avoir des liens invalides sur le serveur web). Le fichier index.html est le fichier d'index généré à partir du fichier index.wml que vous devrez placer dans le répertoire et mettre à jour s'il ne l'est pas.

Vous ne maîtrisez pas les options de compilation qui sont fixées dans le fichier /var/www/www.april.org/include/april/Makefile.rules. Si, sur votre propre machine, vous n'avez pas placé le fichier Makefile.rules à cet endroit là, modifiez ce chemin pour refléter celui où vous l'avez placé afin de vérifier le bon fonctionnement de la compilation AVANT de penser à effectuer un commit. MAIS N'OUBLIEZ PAS DE REMETTRE LA VALEUR ORIGINALE DANS LE MAKEFILE AVANT D'EFFECTUER UN COMMIT !!! Il faut en effet que les fichiers utilisent /var/www/www.april.org/include/april/Makefile.rules sur le web de l'April.

Compilation avec ajout de commandes

Cas du format SGML

Note : le SGML est voué à disparaître du SVN April (remplacé par du XML Docbook ou du WML)

Autres commandes

Il est possible de faire exécuter des commandes après la compilation des fichiers WML en surchargeant la règle all. C'est très simple et même incantatoire :


FILES=index.html
SUBDIRS=

include /var/www/www.april.org/include/april/Makefile.rules

all:    all-inherited
chmod +x *.html

Cet exemple effectue la compilation de index.wml pour générer index.html et exécute la commande chmod +x *.html ensuite (dans cet exemple cela permet de rendre exécutable les fichiers HTML, afin d'y inclure des directives propres à Apache).

Les règles définies

Différentes règles sont définies dans le fichier Makefile.rules et sont donc héritées par tous les fichiers Makefile) du site web. Certaines peuvent être utiles :

all

cette règle effectue toutes les compilations nécessaires. Elle est utilisée lorsque make est exécuté sans argument.

all-inherited

il est parfois nécessaire de redéfinir la cible all. Dans ce cas là, il est préférable de placer all-inherited dans les dépendances de la règle all,

%.html

cette règle permet de compiler des documents HTML à partir de sources WML. Si vous devez compiler un document HTML à partir d'une autre source, vous devrez définir une autre règle afin d'écraser celle-ci ou de la compléter (cf. section Makefile : cas du format SGML).

clean

cette règle est responsable de la suppression de tous les fichiers spécifiés par la variable $(FILES).

clean-recursive

cette règle est responsable de la suppression de tous les fichiers spécifiés par la variable $(FILES). De plus, elle explore tous les répertoires spécifiés par la variable $(SUBDIRS) pour les nettoyer récursivement.

Si vous redéfinissez des :

        • règles de conversion (type %html: %xml) : placez-les AVANT la ligne include /var/www/www.april.org/include/april/Makefile.rules ;
        • règles d'exécution (type clean) : placez-les AVANT la ligne include /var/www/www.april.org/include/april/Makefile.rules ;

sinon vos re-définitions ne seront pas prises en compte. Lorsque vous exécutez la commande make, celle-ci vous notifiera les règles d'exécution que vous avez réecrites (warning).

Par exemple, dans le fichier Makefile du répertoire howto, une règle a été ajoutée pour générer un fichier postscript et HTML à partir de fichier XML et la règle clean a été redéfinie pour effacer aussi les fichiers postscript générés :


FILES=index.html maj_web.html envoyer_cp.html howto-svn.html 
howto-md5.html howto-web.html howto-wml.html stand-howto.html

SUBDIRS=

%html: %xml
docbook2ps $<
docbook2html $<

include /var/www/www.april.org/include/april/Makefile.rules

clean:
rm -f $(FILES) *.ps

Néanmoins, essayez le moins possible de réécrire les règles du fichier Makefile. Faîtes plutôt part de vos besoins aux webmestres. Si vos besoins sont naturels, il serait en effet plus intelligent de modifier le fichier /var/www/www.april.org/include/april/Makefile.rules que de refaire, pour chaque fichier Makefile, la réécriture des règles.

Le trombinoscope

La gestion du trombinoscope est un peu différente du reste, car ses données sont contenues dans une base de données.

La gestion se passe là: http://www.april.org/edit/trombinoscope/.

Le user est edit, les webmestres ont le mot de passe.

Une fois dessus, on peut soit ajouter une personne, soit lister les personnes pour édition ou effacement. Les champs par personne sont: prénom, nom, dit (pour un surnom), la fonction de la personne au sein de l'April, éventuellement une URL personnelle et l'image. Sachez encore que l'image doit être au format PNG et aucune de ses dimensions ne peut être plus grande que 150 pixels.

La page publique du trombino est http://www.april.org/association/trombinoscope/.

Les trucs du pro

Si vous travaillez sur une machine personnelle, je vous conseille de faire tourner un serveur web sur votre machine (vous n'avez pas besoin d'être root pour ça). En effet, nous vous conseillons d'utiliser des balises spéciales pour faire des liens vers d'autres fichiers à la place de liens relatifs (cela permet de modifier l'arborescence du site web sans éditer tous les fichiers faisant référence à la partie modifiée du web). Ces liens sont des liens absolus, qui ne sont pas utilisables avec une méthode file: (ce qui correspond à un test local sans serveur).

Et tant que vous y êtes, installez aussi wml, ça vous permettra de tester les pages localement avant de les envoyer. Dans ce cas, n'oubliez pas de faire un svn checkout includes afin d'avoir les includes pour wml ; sinon vous aurez une erreur à la compilation.

Si vous modifiez une page web (même une modification mineure), la correction veut que vous en mettiez au courant l'auteur de la page par courriel. Son adresse de courriel est en bas de la page et sera remplacée par la votre automatiquement par SVN. Magique, non ?

Lisez les web site style guidelines de GNU, elles sont un bon exemple de ce qu'il faut faire. Voir http://www.gnu.org/server/fsf-html-style-sheet.html.

La liste webmasters

La liste webmasters@april.org est la liste de diffusion autour de laquelle communiquent les webmestres de l'April. C'est aussi celle-ci qui reçoit les commentaires des utilisateurs du site web. Il est d'usage d'informer les autres webmestres de ses travaux par le biais de cette liste. En cas de problème ou si vous avez besoin de conseils, cette liste est faite pour vous.

Si vous voulez contribuer au site web de l'April, la première chose est d'envoyer un courriel aux webmestres afin de vous inscrire à cette liste et d'obtenir un accès SVN au web.


Également dans nos rayons

Si vous m'avez lu jusqu'ici, c'est que vous aimez bien la lecture; aussi vais-je vous en donner encore et encore:

Pour de plus amples information, adressez-vous aux webmestres (webmasters@april.org).