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.
-
~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.
+ 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. +
+ +
+ 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. +
+ +
+ 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. Dans ce cas, il
+ est important de veiller avant tout commit à régler les nom et
+ adresse utilisés pour identifier l'auteur du commit :
+
$ 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"+ +
+ 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.
@@ -43,36 +105,22 @@ $MISCPATH:\ /users/staffs/tuteurs/bin-
- 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...
+ (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
+ les récupérer avec git clone tuteurs@clipper:share/tml et
+ y faire les adaptations nécessaires [il y a apparemment des chemins en
+ dur].)
- 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. -
-
Supposons que vous souhaitiez créer ou modifier la page
unix/accents.html. Pour cela, il va falloir écrire un
- fichier unix/accents.tml.
unix/accents.tml.
+
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:
+ en cours de lecture. 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. -Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />. +<date value="from git" />. </div>Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du tutoriel XHTML des tuteurs.
$ tmlcheck accents.tml
- .html en faisant :
+ et la convertir 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.-$ git add accents.tml + Quand vous avez terminé une modification, « commitez » en faisant : +$ git add accents.tml $ git commitTâchez de mettre un commentaire explicite. @@ -139,17 +182,22 @@ Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />. 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.
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.
++ 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
@@ -172,18 +220,52 @@ actualite
plan_site
-
Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
-disparaître le fichier nolinks :
Pour supprimer un fichier nolinks, procédez en
+ plusieurs étapes :
rebuild (ou make
+ - éditez-le pour qu'íl devienne vide ;
+ - regénérez les pages avec
rebuild (ou make
install) ;
- - Effacez le fichier
nolinks.
+ - effacez le fichier
nolinks.
+ 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.
+
Voir le fichier .mailmap.
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
+
+ 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. +