Comment mettre à jour le site des tuteurs ou y ajouter du contenu

Comme vous le savez, le site des tuteurs doit subir 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).

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 (icones, screenshots, illustrations du hublot, PostScripts gzippés d'icelui)

Le site Web en lui-même se trouve à l'adresse http://www.eleves.ens.fr/tuteurs/web/ temporairement. Quand il sera terminé, il reviendra à sa place, à savoir http://www.eleves.ens.fr/tuteurs/.

Les fichiers tml

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 éxé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.

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'un espace, seules les ponctuations doubles sont précédées d'un espace.</p>

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 modifier 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 écrire 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="hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]">
  

Quand le repository du cvstuteurs est modifié (ou plutôt quand on fait make install dans la racine de son répertoire de travail), les fichiers .tml figurant dans ~tuteurs/www/web sont mis-à-jour, et le script rebuild est lancé dedans, ce script éxécute build sur tous les fichiers .tml qui en ont besoin.

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.

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 suffit de taper 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 "Attention, tu utilises cvstuteurs";sleep 2;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.

1. 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 moficiation). 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 un compte vos modifications).
2. Pour commencer à travailler sur ce nouveau fichier, faites :
   

   bireme ~/tuteurs/cvs/web $ cd unix
   bireme ~/tuteurs/cvs/web $ cvstuteurs add accents.tml
   bireme ~/tuteurs/cvs/web/unix $ vim accents.tml
   

   La deuxième commande permet de dire à cvs que vous préparez un fichier unix/accents.tml.
   Vous pouvez alors insérer la décoration du fichier accents.tml (à savoir l'entête) en faisant :r ../index.tml par exemple. Activez le syntax-highlight HTML, par exemple en relançant vim.
3. É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.
4. Lancez le script de conversion en .html en faisant :! 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).
5. Corrigez les fautes de syntaxe.
6. Si vous avez fait beaucoup de modifications, il peut être utile de faire :

   bireme ~/tuteurs/cvs/web $ rebuild .
   

7. 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
   

8. 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.
9. Pendant l'éxécution de cvstuteurs commit, on vous demande d'indiquer des commentaires sur les man\oelig;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

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