Documentation interne avancée

Pour une première approche, consultez d'abord la page de documentation interne sur la contribution au site des tuteurs.

Comme vous le savez, le site des tuteurs subit un lifting. Marie-Lan et Nicolas ont notamment choisi les couleurs et la présentation du nouveau site, et Nicolas a implémenté un certain nombre de scripts (ceux-ci se trouvent dans la branche utilitaires/tml du cvstuteurs).

&icone.attention; Attention &icone.attention;

Ne pas modifier la branche utilitaires/tml du cvstuteurs à moins de savoir vraiment ce que vous faites, puisque tout le site Web en dépend.

Cette page a pour but :

non seulement d'expliquer comment modifier le site;
mais aussi de servir de fichier d'exemple pour l'élaboration des pages.

Un bref résumé des choses à ne pas faire se trouve dans les dix commandements.

Comment tout cela fonctionne ?

Tout est géré depuis l'arborescence web du cvstuteurs. (NDjriou: l'ancien site est toujours dans l'arborescence www dudit cvs)

Dans ce cvs figurent uniquement des fichiers .tml et des fichiers téléchargeables (icônes, screenshots, illustrations du Hublot, PostScripts gzippés d'icelui)

Le site Web en lui-même se trouve à l'adresse http://www.tuteurs.ens.fr/. Pour des raisons de compatibilité avec l'ancien site Web des tuteurs et la phase transitoire, les adresses http://www.eleves.ens.fr/tuteurs/ancien-site/ sont redirigées vers http://www.tuteurs.ens.fr/ et les noms sous lesquels les pages existaient avant sont redirigées vers leur nouvelle position.

Les fichiers `tml`

Théoriquement

Pour faire une nouvelle page Web, il faut écrire un fichier foobar.tml. C'est presque du HTML, mais il y a quelques nuances. En effet, ces fichiers sont passés dans une moulinette qui s'appelle xsltproc quand vous exécutez la commande :

bireme ~/tuteurs/cvs/web/docs/hublot $ ~tuteurs/bin/build hublot12.tml

Il en ressort normalement (s'il n'y a pas trop d'erreurs de syntaxe) un fichier html très joli. Ce dernier utilise une feuille de style tuteurs.css, contient une bande de navigation à gauche présentant notamment un arbre du site et un sommaire de la page en cours de lecture, le tout généré automatiquement grâce à la patience du concepteur de la nouvelle charte graphique.

Les scripts prennent en compte le titre des pages pour générer l'arborescence. Il convient donc de les faire courts.

La moulinette et la feuille de style permettent de faire très simplement beaucoup choses : des encadrés, des jolis prompts, des tableaux...

Par ailleurs, dans les fichiers .tml, tous les liens internes à la page des tuteurs doivent être relatifs, mais il y a une astuce : la racine de l'arborescence du site a pour synonyme &url.tuteurs;. Ainsi, dans logiciels/latex/astuces.tml, on trouve le lien suivant :

<p> Mais cela ne doit pas vous empêcher de prendre de <a href="&url.tuteurs;docs/hublot/typo.html">bonnes habitudes</a> quand vous tapez avec d'autres logiciels ou que vous rédigez un courrier toutes les ponctuations sont suivies d'une espace, seules les ponctuations doubles sont précédées d'une espace.</p>

Concrètement...

Pour faire un fichier page.tml, récupérez l'en-tête d'un autre fichier .tml du site, et modifiez les titres:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
  PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
  "tuteurs://DTD/tml.dtd">
<html>
  <head>
    <title>Les tuteurs</title>
  </head>
  <body>

    <h1>Le site des tuteurs</h1>

    <p> Bienvenue sur la page Web des tuteurs informatique de l'École
Normale Supérieure. Le contenu de ce site est organisé en grands 
thèmes| :</p>

Il est également possible d'utiliser la commande tmltemplate fichier.tml [titre] [titre long].

Le titre de la page (ici « Les tuteurs ») doit être le plus court possible car c'est lui qui est pris en compte pour faire l'arbre de navigation qui se trouvent sur la gauche lors de l'affichage par un navigateur en mode graphique de la page Web une fois générée par les scripts.

Le titre qui s'affiche en gros tout en haut de la page doit être indiqué avec une balise <h1>, les différentes sections avec <h2>, etc... Enfin, un paragraphe doit se trouver à l'intérieur d'une balise <p>.

Lorsque l'on exécute le script build sur un fichier .tml, le fichier .html produit contient un sommaire en dessous du gros titre, celui-ci est généré à partir des balises <h2> et <h3> se trouvant dans le fichier .tml.

Les dates de dernière modification

À partir de l'instant où vous lisez ces lignes, quand vous écrirez une page pour le site des tuteurs ou que vous en modifierez une, vous devrez obligatoirement (de toute façon, vous ne pourrez pas faire autrement, hé, hé...) mettre à la fin des lignes du type:

<div class="metainformation">
Auteur : Comptes tuteurs.
Dernière modification le <date value="$Date$" />.
</div>

Quand vous commiterez vos modifications avec CVS, ce dernier modifiera votre fichier pour insérer la vraie date à côté de $Date$ . N'y touchez-plus, CVS et les scripts de génération des fichiers html s'occupent de tout.

Les fichiers `html`

Les scripts transforment les .tml en .html. Ces derniers doivent être du XHTML 1.0 Strict. Pour le vérifier, passez les pages que vous modifiez au validateur.

Quelles sont les différences entre le HTML usuel et le XHTML 1.0 Strict ?

Toutes les balises doivent être refermées. Ainsi, pour faire un paragraphe on fait

<p>
En utilisant la suite spectrale de coniveau, on peut démontrer le
théorème [...].
</p>

On évite au maximum les retours à la ligne sauvages avec <br>. D'ailleurs, ce genre de balises sont écrites sous la forme <br /> pour se conformer à la première exigence ;
Tous les paramètres doivent être mis entre guillements et les images doivent avoir un paramètre alternatif :
```
<img src="docs/hublot/hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]"/>
```
Toutes les balises doivent être mises en minuscules.

Après que le repository du cvstuteurs est modifié via la commande make install dans la racine de son répertoire de travail (ou celui d'un autre), les fichiers .tml figurant dans ~tuteurs/www/web sont mis à jour, et le script rebuild est lancé dedans : ce script exécute build sur tous les fichiers .tml qui en ont besoin, ce qui permet de mettre à jour les fichiers .html du site.

Comment modifier le site ?

Comme le site est géré via cvs, il convient de connaître le minimum nécessaire pour utiliser ce logiciel, nous allons le voir ci-dessous. Pour en connaître plus sur CVS (en complément de ce qui est indiqué ci-dessous), voyez la documentation sur CVS sur le site des tuteurs.

Se créer un répertoire de travail

Pour utiliser cvs, il faut se créer un répertoire de travail chez soi, c'est-à-dire récupérer les fichiers se trouvant dans le repository, à savoir ~tuteurs/cvs/web.

Pour cela, il faut utiliser la commande cvstuteurs, qui se trouve dans le répertoire /users/staffs/tuteurs/bin/. Pour plus de simplicité, vous êtes invités à rajouter le répertoire /users/staffs/tuteurs/bin/ dans votre PATH (vous pouvez configurer celui-ci dans votre fichier .profile).

Vous pouvez donc maintenant utiliser le CVS des tuteurs en tapant la commande suivante dans votre répertoire ~/tuteurs/cvs par exemple :

bireme ~/tuteurs/cvs $ cvstuteurs checkout web

Il est impératif d'utiliser cvstuteurs à la place de cvs : ce permet de faire travailler cvs directement dans le repository des tuteurs et de le faire travailler en tant que membre du groupe tuteurs, ce qui est très important pour éviter de tout casser (comme c'est arrivé le premier jour). Par conséquent, je vous recommande vivement d'insérer la ligne suivante dans votre .zshrc :

alias cvs='echo "Non, tu ne veux pas utiliser cvs directement, utilise cvstuteurs"'

Vous voyez apparaître quelques fichiers .tml dans votre répertoire de travail. Pour les transformer en .html, faites :

bireme ~/tuteurs/cvs/web $ ~tuteurs/bin/rebuild .

Contribuer au nouveau site

Prenons un exemple. Supposons que vous souhaitiez écrire la page unix/accents.html.

Commencez par synchroniser votre répertoire de travail avec le repository (bien sûr, si un fichier de votre répertoire est plus récent que la version du repository, il n'y a pas de modification). Faites sans danger :
```
bireme ~/tuteurs/cvs/web $ cvstuteurs update
```
Il arrive souvent que cvs vous demande de faire cette manœuvre avant de faire un commit (i.e. de prendre en compte vos modifications).
Pour commencer à travailler sur ce nouveau fichier, faites :
```
bireme ~/tuteurs/cvs/web $ cd unix
bireme ~/tuteurs/cvs/web/unix $ tmltemplate accents.tml "titre court" "titre long" 
bireme ~/tuteurs/cvs/web/unix $ cvstuteurs add accents.tml
bireme ~/tuteurs/cvs/web/unix $ vim accents.tml
```
La troisième commande permet de dire à cvs que vous préparez un fichier unix/accents.tml, il faut que ce fichier existe avant de lancer cette commande, c'est à cela que sert le script tmltemplate. Le titre court est celui qui apparaîtra dans l'arborescence du site à gauche des pages, le titre long sera écrit en gros en haut de la page.
Écrivez le contenu de la page Web, c'est-à-dire dans ce cas en mettant à jour la page figurant sur l'ancien site et en le rendant conforme au standard XHTML 1.0 Strict.
Vérifiez votre page avec :
```
bireme ~/tuteurs/cvs/web/unix $ tmlcheck accents.tml
```
La commande tmlcheck est un peu plus stricte que build. S'il y a des erreurs d'équilibrage entre les balises ouvrantes et fermantes, il peut être difficile de trouver la balise ouvrante coupable. Pour ça, on peut utiliser xmlbalance, qui indique la position des balises incriminées (en caractères, utiliser go avec Vim).
Lancez le script de conversion en .html en faisant :
```
bireme ~/tuteurs/cvs/web/unix $ build accents.tml
```
Notez que si d'autres fichiers tml se trouvent dans le répertoire courant, leur syntaxe sera aussi vérifiée (pour créer l'arborescence dans accents.tml).
Corrigez les fautes de syntaxe.
Si vous avez fait beaucoup de modifications, il peut être utile de faire :
```
bireme ~/tuteurs/cvs/web $ rebuild .
```
Passer la page que vous venez de créer au validateur. Pour cela, il peut être pratique de faire un lien symbolique permettant d'accéder par le Web à votre répertoire de travail :
```
bireme ~/www ln -s ../tuteurs/cvs/web tuteurs
```
Cependant, il faudrait éviter que votre copie de travail se retrouve répertoriée dans un moteur de recherche comme Google par exemple (cela pourrait arriver si vous cliquez sur un lien depuis votre page). Donc, essayez d'utiliser un fichier .htaccess adapté pour limiter l'accès à votre copie du site depuis l'extérieur.
Un démon mensuel fait une liste des liens cassés sur le site, tenez-en compte.
Quand tout est au point, vous pouvez « commiter » en faisant :
```
bireme ~/tuteurs/cvs/web $ make install
```
Pour information, voici le contenu du Makefile
```
install:
        cvstuteurs commit
        su-tuteurs cvstuteurs update -d /users/staffs/tuteurs/www/web
        su-tuteurs /users/staffs/tuteurs/share/tml/bin/rebuild /users/staffs/tuteurs/www/web
```
La première ligne intéressante met à jour le repository compte tenu de vos modifications et créations. La deuxième met à jour met à jour entre autres les fichiers tml de la page Web en fonction du repository nouveau et la troisième ligne met à jour les fichiers html et en crée éventuellement de nouveaux.

Pendant l'exécution de cvstuteurs commit, on vous demande d'indiquer des commentaires sur les manœuvres que vous avez faites dans les différents répertoires. Il est extrêmement important que ceux-ci soient précis et circonstanciés, autant que possible. En clair, éviter de mettre

Correction d'un problème important dans foobar.tml

Quelques astuces

Ne pas publier une page tout de suite

Imaginons que vous avez commencé à travailler une nouvelle section du site, que les pages que vous venez de faire ne soient pas tout-à-fait au point. Vous pouvez alors décider de ne pas faire apparaître dans un premier temps vos nouvelles pages dans l'arbre de navigation qui se trouve sur la gauche des pages.

Pour cela, le script de génération des pages regarde dans chaque répertoire si un fichier nolinks s'y trouve. Ce fichier doit contenir une liste séparée par des espaces ou des retours à la ligne de choses de la forme « fichier » ou encore « répertoire/ ». Cela désactivera les liens éventuels vers la page fichier.html ou vers l'index de répertoire.

Par exemple, pour ne pas faire apparaître cette page de documentation interne aux tuteurs (et quelques autres) dans l'index, la racine du CVS contient :

clipper ~tuteurs/www $ cat nolinks
doc-interne
aide
404
actualite
plan_site

Un autre exemple : pendant le développement de la partie logiciels/mozilla/ du site, le fichier logiciels/nolinks contenait:

mozilla/

On peut conseiller de ne pas rentrer ce fichier nolinks dans CVS, mais seulement de le mettre au bon endroit à partir de ~tuteurs/www/, cela simplifie un peu les choses, et comme cela, sur votre copie de travail, vous avez tous les liens.

&icone.attention; Attention &icone.attention;

Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire disparaître le fichier nolinks :

Éditez-le pour qu'íl devienne vide ;
Regénérez les pages avec rebuild (ou make install) ;
Effacez le fichier nolinks.

En effet, si vous effacez directement le fichier nolinks, a priori, le script de regénération ne refabriquera pas les pages et les liens vers les nouvelles pages ne seront pas insérés.

Quoi faire ?

L'arborescence voulue du site se trouve dans le fichier 00INDEX et le fichier 00TODO contient ce qui est en cours, avec diverses rubriques. Il est important que ces deux fichiers soient mis-à-jour assez régulièrement.

Pour finir, voici quelques recommandations concernant la modification du site Web.

&icone.attention; Les dix commandements de cvstuteurs/web &icone.attention;

Tu n'utiliseras pas cvs mais cvstuteurs.
Tu ne modifieras jamais directement ce qui se trouve dans ~tuteurs/cvs/ et en particulier ~tuteurs/cvs/web/.
Tu ne modifieras pas non plus directement ~tuteurs/www/web/.
Pour commiter, tu ne feras point cvstuteurs commit, mais make install dans la racine de ton répertoire de travail.
Tu ajouteras des fichiers binaires en faisant cvstuteurs add -kb foobar.png
De fichiers .gif tu ne créeras point, parce que c'est mal.
Tu liras et upgraderas 00TODO et 00INDEX.
Des liens relatifs tu utiliseras.
Des commentaires précis tu indiqueras lors d'un commit.
Pour ne point laisser traîner des liens cassés, tu examineras les logs du démon vérifieur qui se manifeste au début de chaque mois.

Je vous prie de bien vouloir excuser les anglicismes scandaleusement présents dans cette page.

Auteur : Joël Riou et Nicolas George.

Documentation interne avancée

&icone.attention; Attention &icone.attention;

Comment tout cela fonctionne ?

Les fichiers tml

Théoriquement

Concrètement...

Les dates de dernière modification

Les fichiers html

Comment modifier le site ?

Se créer un répertoire de travail

Contribuer au nouveau site

Quelques astuces

Ne pas publier une page tout de suite

&icone.attention; Attention &icone.attention;

Quoi faire ?

&icone.attention; Les dix commandements de cvstuteurs/web &icone.attention;

Les fichiers `tml`

Les fichiers `html`