Mise à jour doc interne.

Première version plus ou moins complète post-passage à git. Reste à
adapter/virer la doc interne avancée.

doc-interne.tml

@@ -10,26 +10,88 @@
 
 <h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu?</h1>
 
-    <p> 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 <code>~tuteurs/bin</code> contient plusieurs commandes
-      utiles pour travailler avec les fichiers TML. 
-      On ne travaille pas directement dans <code>~tuteurs/www</code> :
-      tout le contenu du site est sous <a href="logiciels/git/">git</a>,
-      et l'arborescence HTML est mise à jour automatiquement à chaque
-      <code>push</code> (de la branche qui va bien) dans
-      <code>~tuteurs/www.git</code>.
+<p>
+  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 <a href="logiciels/git/">git</a>, et l'arborescence HTML est
+  mise à jour automatiquement à chaque <code>push</code> (de la branche
+  qui va bien) dans <code>~tuteurs/www.git</code>.
 </p>
 
-<h2> Rajouter <code>~tuteurs/bin</code> dans votre <code>PATH</code></h2>
+<p>
+  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 <a href="logiciels/git/">la page consacrée à git</a> ou
+  dans la doc de ce dernier.
+</p>
+
+<h2> Préliminaires </h2>
+
+<h3> Le dépôt git </h3>
 
 <p>
-La plupart des programmes utilisés dans la suite sont dans
-<code>~tuteurs/bin</code>.  Éditez le fichier <code> .profile </code> à
-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) <em>avant</em> de se délogguer.
+  Le source TML du site web est géré par <a
+    href="logiciels/git/">git</a>, 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
+  <code>~tuteurs/www.git</code>, puis on envoie les changements au dépôt
+  central. Le plus simple est de travailler sur
+  son compte <code>clipper</code>, mais il est possible de le faire
+  depuis une machine personnelle, voire avec quelques précautions depuis
+  le compte <code>tuteurs</code>. (On ne modifie jamais directement les
+  fichiers du répertoire <code>~tuteurs/www</code>.)
+</p>
+
+<p>
+  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)
+</p>
+<pre><span class="prompt">$</span> git clone tuteurs@clipper:www.git </pre>
+<p class="continue">
+  Cependant, depuis les machines de l'école, on peut aussi faire
+  directement
+</p>
+<pre><span class="prompt">$</span> git clone ~tuteurs/www.git </pre>
+<p class="continue">
+  sans clé ssh — du moins, il y a une magouille dans le Makefile qui
+  essaie de faire en sorte que ça marche.
+</p>
+   
+<p>
+  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 <code>tuteurs</code>
+  lui-même, par exemple dans <code>tmp/moi</code>. <em>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 :</em>
+</p>
+<pre><span class="prompt">$</span> export GIT_AUTHOR_NAME="Tartempion"
+<span class="prompt">$</span> export GIT_AUTHOR_EMAIL="tartempion@phare"</pre>
+
+<p>
+  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 <em>via</em>
+</p>
+<pre><span class="prompt">$</span> git config --global user.name "Tartempion"
+<span class="prompt">$</span> git config --global user.email "tartempion@clipper"</pre>
+
+<h3> Les outils TML </h3>
+
+<p>
+  Plusieurs programmes utiles aux tuteurs — notamment, mais pas
+  uniquement, pour travailler sur le site web — se trouvent dans
+  <code>~tuteurs/bin</code>. C'est donc une bonne idée de l'ajouter à
+  son <code>$PATH</code>
+</p>
+
+<p>
+  Pour ce faire, éditez le fichier <code>.profile </code> à 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) <em>avant</em> de se délogguer.
 </p>
 
 <pre>
@@ -43,36 +105,22 @@ $MISCPATH:\
 /users/staffs/tuteurs/bin
 </pre>
 
-<h2> Récupérer une copie de travail </h2>
-
 <p>
-  Le site web des 
-  <a href="logiciels/git/">git</a>. 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 <code>git clone tuteurs@clipper:share/tml</code> et
+  y faire les adaptations nécessaires [il y a apparemment des chemins en
+  dur].)
 </p>
 
-<p>
-  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
-</p>
-<pre><span class="prompt">$</span> git clone tuteurs@clipper:www.git </pre>
-<p class="continue">
-  Cependant, depuis les machines de l'école, on peut aussi faire
-  directement
-</p>
-<pre><span class="prompt">$</span> git clone ~tuteurs/www.git </pre>
-<p class="continue">
-  sans clé ssh — du moins, il y a une magouille dans le Makefile qui
-  essaie de faire en sorte que ça marche.
-</p>
  
-<h2>Écrire une nouvelle page (ou la modifier)</h2>
+<h2> Créer ou modifier une page </h2>
 
 <p>
   Supposons que vous souhaitiez créer ou modifier la page
   <code>unix/accents.html</code>. Pour cela, il va falloir écrire un
-  fichier <code>unix/accents.tml</code>. </p>
+  fichier <code>unix/accents.tml</code>.
+</p>
 
 <ul>
   <li>
@@ -94,41 +142,36 @@ $MISCPATH:\
     Écrivez  le contenu du fichier.  Ce dernier sera passé dans une
     moulinette qui s'appelle <code>xsltproc</code> 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é <code>&amp;url.tututeurs;</code>, ce qui donne
+    des liens de la forme :
     <pre>&lt;a href="&amp;url.tuteurs;docs/hublot/typo.html"&gt;</pre>
     Il faut mettre à la fin du fichier des lignes du type:
     <pre>&lt;div class="metainformation"&gt;
 Auteur : Comptes tuteurs.
-Dernière modification le &lt;date value="$Date: 2008-10-05 11:20:36 $" /&gt;.
+&lt;date value="from git" /&gt;.
 &lt;/div&gt;</pre>
     Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du
     <a href="&url.tuteurs;internet/web/html/">tutoriel XHTML</a> des
     tuteurs.
   </li>
 
-  <li> Vérifiez votre page avec :
+  <li> Sur clipper, ou si vous avez installé les outils nécessaires,
+    vous pouvez vérifier la syntaxe de votre fichier tml avec
     <pre><span class="prompt">$</span> tmlcheck accents.tml</pre>
-  </li>
-
-  <li>
-    Lancez le script de conversion en <code>.html</code> en faisant :
+    et la convertir en html en faisant
     <pre><span class="prompt">$</span> build accents.tml</pre>
     Si vous avez fait beaucoup de modifications, il peut être utile de
     lancer
     <pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .</pre>
-    à la racine de votre copie de travail.</li>
-
-  <li>
-    Passez la page que vous venez de créer au <a
-      href="http://validator.w3.org/">validateur</a>. 
+    à la racine de votre copie de travail.
   </li>
 
-  <li id="makeinstall">
-    Quand vous avez terminé une modification, vous pouvez « commiter »
-    en faisant :
-    <pre>
-<span class="prompt">$</span> git add accents.tml
+  <li>
+    Quand vous avez terminé une modification, « commitez » en faisant :
+    <pre><span class="prompt">$</span> git add accents.tml
 <span class="prompt">$</span> git commit
   </pre>
     Tâchez de mettre un commentaire explicite.
@@ -139,17 +182,22 @@ Dernière modification le &lt;date value="$Date: 2008-10-05 11:20:36 $" /&gt;.
     installez vos modifications sur le site web avec 
     <pre><span class="prompt">$</span> make install</pre>
     (essentiellement équivalent à <code>git push</code>).
+    À l'autre bout, les fichiers tml modifiés seront validés par
+    <code>tmlcheck</code>. Si tout va bien, le site web sera mis à jour
+    automatiquement. Sinon, votre commit sera rejetté : faites les
+    corrections nécessaires puis réessayez.
   </li>
 
 </ul>
 
-<h2> Astuces plus avancées </h2>
+<h2> Trucs plus avancés </h2>
 
-<h3>Ne pas publier une page tout de suite</h3>
+<h3> Masquer une page dans l'arbre de navigation </h3>
       
-<p>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.</p>
+<p>
+  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.
+</p>
       
 <p>Pour cela, le script de génération des pages regarde dans chaque
 répertoire si un fichier <code>nolinks</code> s'y trouve. Ce fichier doit
@@ -172,18 +220,52 @@ actualite
 plan_site
 </pre>
         
-<p>Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
-disparaître le fichier <code>nolinks</code> :</p>
+<p> Pour supprimer un fichier <code>nolinks</code>, procédez en
+  plusieurs étapes :</p>
 
 <ul>
-  <li>Éditez-le pour qu'íl devienne vide ;</li>
-  <li>Regénérez les pages avec <code>rebuild</code> (ou <code>make
+  <li>éditez-le pour qu'íl devienne vide ;</li>
+  <li>regénérez les pages avec <code>rebuild</code> (ou <code>make
 install</code>) ;</li>
-  <li>Effacez le fichier <code>nolinks</code>.</li>
+  <li>effacez le fichier <code>nolinks</code>.</li>
 </ul>
 
-<h3> Branches </h3>
+<h3> Ignorer un commit dans le calcul de la dernière modification </h3>
 
+<p>
+  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
+  <code>Last-change: ignore this commit</code>. On peut aussi ignorer un
+  commit après coup en ajoutant son identifiant (SHA) au fichier
+  <code>.hidden_commits</code>.
+</p>
+
+<h3> Ajuster le nom sous lequel on apparaît dans les dernières
+  modifications </h3>
+
+<p> Voir le fichier <code>.mailmap</code>. </p>
+
+<h3> Quelqu'un a modifié les fichiers de <code>www</code> ! </h3>
+
+<p>
+  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 <code>git --git-dir=../www.git  stash list</code>
+  depuis <code>~tuteurs/www</code> et lire la doc de <code>git
+    stash</code>
+</p>
+
+<h3> Doc technique </h3>
+
+<p>
+  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.
+</p>
 
 <div class="metainformation">
 Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba.