Mettre à jour le site des tuteurs ou y ajouter du contenu

Les pages HTML du site web des tuteurs sont produites à partir de fichiers dans un format XML maison appelé TML. 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.

Cette page décrit les étapes pour effectuer un changement sur le site, et donne au passage, sans explications, le strict minimum de commandes git nécessaires. Il est cependant recommandé d'aller en apprendre un peu plus sur la page consacrée à git ou dans la doc de ce dernier.

Préliminaires

Le dépôt git

Le source TML du site web est géré par git, un système de contrôle de versions. Pour y apporter des changements, on modifie sa propre copie du source TML obtenue en clonant le dépôt git ~tuteurs/www.git, puis on envoie les changements au dépôt central. Le plus simple est de travailler sur son compte clipper, mais il est possible de le faire depuis une machine personnelle, voire avec quelques précautions depuis le compte tuteurs. (On ne modifie jamais directement les fichiers du répertoire ~tuteurs/www.)

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 (de chez soi ou d'une machine de l'école)

$ 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 (mais elle ne marche pas, méthode à éviter pour le moment donc).

On peut aussi (ce n'est guère utile qu'aux gens qui n'ont plus de compte clipper) cloner le dépôt git sur le compte tuteurs lui-même, par exemple dans tmp/moi.

$ export GIT_AUTHOR_NAME="Tartempion"
$ export GIT_AUTHOR_EMAIL="tartempion@phare"

Quand on travaille depuis son propre compte, les valeurs par défaut font généralement l'affaire, sinon, on peut les changer une fois pour toutes via

$ git config --global user.name "Tartempion"
$ git config --global user.email "tartempion@clipper"

Les outils TML

Plusieurs programmes utiles aux tuteurs — notamment, mais pas uniquement, pour travailler sur le site web — se trouvent dans ~tuteurs/bin. C'est donc une bonne idée de l'ajouter à son $PATH

Pour ce faire, é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

(Aucun de ces programmes n'est indispensable pour modifier le site web. Pour travailler depuis chez soi, on a le choix de s'en passer ou de les récupérer avec git clone tuteurs@clipper:share/tml et y faire les adaptations nécessaires : il y a des chemins à adapter dans tml/lib/catalog.xml, ainsi que $BASE dans tmlcheck, build et rebuild.)

Créer ou modifier une page

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 apparaîtra 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, entre autres choses, ajoute automatiquement à la page un plan du site sur gauche et un sommaire en début de page. La moulinette TML et la feuille de style tuteurs.css permettent de faire facilement des encadrés, de jolis prompts, etc. : voyez les pages existantes pour des exemples, et la feuille de style elle-même (voire la moulinette) pour tous les détails. Les liens internes au site des tuteurs ne doivent pas mentionner l'adresse de la racine du site. Il faut soit faire des liens relatifs, soit faire référence à la racine en utilisant l'entité &url.tututeurs;, ce qui donne des liens de 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.
  <date value="from git" />.
  </div>

  Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du tutoriel XHTML des tuteurs. Rappelons juste que toutes les balises doivent être refermées, que leurs noms s'écrivent en minuscules, et qu'il est de mauvais goût d'aller à la ligne sauvagement avec <br>.
• Sur clipper, ou si vous avez installé les outils nécessaires, vous pouvez vérifier la syntaxe de votre fichier tml avec

  $ tmlcheck accents.tml

  et la convertir en html en faisant

  $ build accents.tml

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

  $ rebuild .

  à la racine de votre copie de travail.
• Quand vous avez terminé une modification, « commitez » 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). À l'autre bout, les fichiers tml modifiés seront validés par tmlcheck. Si tout va bien, le site web sera mis à jour automatiquement. Sinon, votre commit sera rejetté : faites les corrections nécessaires puis réessayez.

Trucs plus avancés

Masquer une page dans l'arbre de navigation

Vous pouvez décider de ne pas faire apparaître une page 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

Pour supprimer un fichier nolinks, procédez en plusieurs étapes :

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

Ignorer un commit dans le calcul de la dernière modification

La date et l'auteur de la dernière modification de chaque page sont lus dans l'historique du dépôt git. Il est possible d'empêcher qu'un commit donné soit pris en compte pour ce calcul. (C'est utile, par exemple, si l'on a fait des modifications automatisées qui affectent plein de pages sans assurer que leur contenu soit à jour.) Il suffit pour cela de placer dans le message de commit la ligne magique Last-change: ignore this commit. On peut aussi ignorer un commit après coup en ajoutant son identifiant (SHA) au fichier .hidden_commits.

Ajuster le nom sous lequel on apparaît dans les dernières modifications

Voir le fichier .mailmap.

Quelqu'un a modifié les fichiers de www !

Lors de la mise à jour du site, il y a un mécanisme qui essaie de faire une copie de sauvegarde des modifications parasites avant de les écraser. Lancer git --git-dir=../www.git stash list depuis ~tuteurs/www et lire la doc de git stash

Doc technique

Quelques informations sur les scripts qui gèrent tout ça sont ou devraient apparaître peu à peu dans les divers fichiers README du compte tuteurs.