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

En bref : les pages HTML du site web des tuteurs sont produites à partir de fichiers dans un format XML maison appelé TML. Le répertoire ~tuteurs/bin contient plusieurs commandes utiles pour travailler avec les fichiers TML. On ne travaille pas directement dans ~tuteurs/www : tout le contenu du site est sous git, et l'arborescence HTML est mise à jour automatiquement à chaque push (de la branche qui va bien) dans ~tuteurs/www.git.

Rajouter ~tuteurs/bin dans votre PATH

La plupart des programmes utilisés dans la suite sont dans ~tuteurs/bin. Éditez le fichier .profile à la racine de votre compte, trouvez le passage qui parle du PATH et modifiez la fin. Attention, ne pas oublier de mettre :\ (non suivi d'espace !) à la fin de l'avant-dernière ligne, et de tester (en vous logguant une deuxième fois) avant de se délogguer.

PATH=\
$HOME/bin/$SYSTEMNAME:\
$HOME/bin:\
$UTILPATH:\
$MAINPATH:\
$GAMESPATH:\
$MISCPATH:\
/users/staffs/tuteurs/bin

Récupérer une copie de travail

Le site web des git. Je ne réexplique pas comment se servir de git ici, allez voir la page qu'on a déjà à ce sujet...

La première chose à faire pour modifier le site est donc de cloner le dépôt git. La meilleure façon est de commencer par mettre une clé ssh chez tuteurs (si on n'en a pas déjà) puis de faire

$ git clone tuteurs@clipper:www.git 

Cependant, depuis les machines de l'école, on peut aussi faire directement

$ git clone ~tuteurs/www.git 

sans clé ssh — du moins, il y a une magouille dans le Makefile qui essaie de faire en sorte que ça marche.

Écrire une nouvelle page (ou la modifier)

Supposons que vous souhaitiez créer ou modifier la page unix/accents.html. Pour cela, il va falloir écrire un fichier unix/accents.tml.

• Commencez par synchroniser votre répertoire de travail avec le dépôt :

  $ git pull

• Si unix/accents.html n'existe pas déjà, créez-le :

  $ cd unix
        $ tmltemplate accents.tml "titre court" "titre long" 
        $ emacs accents.tml

  Le titre court est celui qui apparaîtra dans l'arborescence du site à gauche des pages (choississez-le concis, car l'arbre de navigation est étroit), le titre long sera écrit en gros en haut de la page. Pour modifier un fichier existant, idem sauf le tmltemplate.
• Écrivez le contenu du fichier. Ce dernier sera passé dans une moulinette qui s'appelle xsltproc qui rajoute automatiquement un plan du site à gauche et un sommaire de la page en cours de lecture. Les liens internes à la page des tuteurs doivent être sous la forme:

  <a href="&url.tuteurs;docs/hublot/typo.html">

  Il faut mettre à la fin du fichier des lignes du type:

  <div class="metainformation">
  Auteur : Comptes tuteurs.
  Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />.
  </div>

  Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du tutoriel XHTML des tuteurs.
• Vérifiez votre page avec :

  $ tmlcheck accents.tml

• Lancez le script de conversion en .html en faisant :

  $ build accents.tml

  Si vous avez fait beaucoup de modifications, il peut être utile de lancer

   teck ~/tuteurs/cvs/web $ rebuild .

  à la racine de votre copie de travail.
• Passez la page que vous venez de créer au validateur.
• Quand vous avez terminé une modification, vous pouvez « commiter » en faisant :

  $ git add accents.tml
  $ git commit
    

  Tâchez de mettre un commentaire explicite.
• Répétez ce qui précède autant de fois que nécessaire. À la fin, installez vos modifications sur le site web avec

  $ make install

  (essentiellement équivalent à git push).

Astuces plus avancées

Ne pas publier une page tout de suite

Vous pouvez 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

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.

Branches