Début de doc pour modifier le site sous git.

doc-interne.tml

@@ -10,7 +10,18 @@
 
     <h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu?</h1>
 
-<h3> Rajouter <code>~tuteurs/bin</code> dans votre <code>PATH</code></h3>
+    <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>
+    
+<h2> Rajouter <code>~tuteurs/bin</code> dans votre <code>PATH</code></h2>
 
 <p>
 La plupart des programmes utilisés dans la suite sont dans
@@ -32,121 +43,109 @@ $MISCPATH:\
 /users/staffs/tuteurs/bin
 </pre>
 
-
+<h2> Récupérer une copie de travail </h2>
-       <h3>Se créer un répertoire de travail</h3>
 
 <p>
-Tout d'abord, créez-vous un répertoire de travail sur votre compte avec
+  Le site web des 
-<code>mkdir</code>. Par la suite, nous supposerons que ce répertoire
+  <a href="logiciels/git/">git</a>. Je ne réexplique pas comment se
-s'appelle <code> tuteurs/cvs</code>.
+  servir de git ici, allez voir la page qu'on a déjà à ce sujet...
 </p>
 
-<p>Tapez les commandes suivantes: 
+<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>
+<pre><span class="prompt">$</span> git clone tuteurs@clipper:www.git </pre>
-<span class="prompt"> teck ~/tuteurs/cvs $</span> cvstuteurs checkout web
+<p class="continue">
-<span class="prompt"> teck ~/tuteurs/cvs $</span> cd web
+  Cependant, depuis les machines de l'école, on peut aussi faire
-<span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .
+  directement
-</pre>
-  
-  <h3>Écrire une nouvelle page (ou la modifier)</h3>
-
-     <p>Prenons un exemple. Supposons que vous souhaitiez écrire la page
-<code>unix/accents.html</code>. Pour cela, il va falloir écrire
-un fichier <code>unix/accents.tml</code>.
 </p>
-      <ol>
+<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>
+
+<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>
+
+<ul>
   <li>
-Commencez par synchroniser votre répertoire de travail avec le repository:
+    Commencez par synchroniser votre répertoire de travail avec le dépôt :
-<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> cvstuteurs update
+    <pre><span class="prompt">$</span> git pull</pre>
-</pre>
   </li>
-        <li>Pour commencer à travailler sur ce nouveau fichier, faites :
+  <li>
-
+    Si <code>unix/accents.html</code> n'existe pas déjà, créez-le :
-<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> cd unix
+    <pre><span class="prompt">$</span> cd unix
-<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> tmltemplate accents.tml <em>"titre court"</em> <em>"titre long"</em> 
+      <span class="prompt">$</span> tmltemplate accents.tml <em>"titre court"</em> <em>"titre long"</em> 
-<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> cvstuteurs add accents.tml
+      <span class="prompt">$</span> emacs accents.tml</pre>
-<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> emacs accents.tml
-</pre>
-
-Si vous voulez modifier un fichier existant, il ne faut pas taper les
-commandes du milieu.
-
     Le <em>titre court</em> est celui qui apparaîtra dans l'arborescence du
-site à gauche des pages (choississez-le concis, car l'arbre de navigation
+    site à gauche des pages (choississez-le concis, car l'arbre de
-est étroit), le <em>titre long</em> sera écrit en gros en 
+    navigation est étroit), le <em>titre long</em> sera écrit en gros en
-haut de la page.
+    haut de la page. Pour modifier un fichier existant, idem sauf le
-
+    <code>tmltemplate</code>. 
-<p>Pour ajouter des fichiers binaires (par exemple des images), il faut
-taper :</p>
-<pre>
-<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> <code>cvstuteurs add -kb foobar.png </code>
-</pre>
   </li>
-
+  <li>
-<li>Écrivez le contenu du fichier.  Ce dernier sera passé dans une moulinette
+    Écrivez  le contenu du fichier.  Ce dernier sera passé dans une
-qui s'appelle <code>xsltproc</code> qui rajoute automatiquement
+    moulinette qui s'appelle <code>xsltproc</code> qui rajoute
-un plan du site à gauche et un sommaire de la page en cours de lecture.
+    automatiquement un plan du site à gauche et un sommaire de la page
-
+    en cours de lecture. Les liens internes à la page des tuteurs
-Les liens internes à la page des tuteurs doivent être sous la forme:
+    doivent être sous la forme:
-     <!-- <blockquote><p> -->
+    <pre>&lt;a href="&amp;url.tuteurs;docs/hublot/typo.html"&gt;</pre>
-<pre>
-&lt;a href="&amp;url.tuteurs;docs/hublot/typo.html"&gt;
-</pre>
-      <!-- </p></blockquote> -->
-
     Il faut mettre à la fin du fichier des lignes du type:
-      <pre>
+    <pre>&lt;div class="metainformation"&gt;
-&lt;div class="metainformation"&gt;
 Auteur : Comptes tuteurs.
 Dernière modification le &lt;date value="$Date: 2008-10-05 11:20:36 $" /&gt;.
-&lt;/div&gt;
+&lt;/div&gt;</pre>
-</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 :
-<pre><span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> tmlcheck accents.tml
+    <pre><span class="prompt">$</span> tmlcheck accents.tml</pre>
-</pre></li>
+  </li>
 
-<li> Lancez le script de conversion en <code>.html</code> en faisant :
+  <li>
-<pre><span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> build accents.tml
+    Lancez le script de conversion en <code>.html</code> en faisant :
-</pre> </li>
+    <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> Si vous avez fait beaucoup de modifications, il peut être utile de
+  <li>
-  retourner dans le répertoire <code>web/</code> et de taper :
+    Passez la page que vous venez de créer au <a
-<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .
-</pre></li>
-
-<li> Passer la page que vous venez de créer au <a
       href="http://validator.w3.org/">validateur</a>. 
   </li>
         
-<li><a name="makeinstall" id="makeinstall"></a>
+  <li id="makeinstall">
-Quand tout est au point, vous pouvez « commiter » en faisant (depuis le
+    Quand vous avez terminé une modification, vous pouvez « commiter »
-  répertoire <code>web/</code>) :
+    en faisant :
-<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> make install
+    <pre>
-</pre></li>
+<span class="prompt">$</span> git add accents.tml
+<span class="prompt">$</span> git commit
+  </pre>
+    Tâchez de mettre un commentaire explicite.
+  </li>
         
   <li>
-On vous demandera
+    Répétez ce qui précède autant de fois que nécessaire. À la fin,
-d'indiquer des commentaires sur les man&#339;uvres que vous avez faites
+    installez vos modifications sur le site web avec 
-dans les différents répertoires. Il est extrêmement important que ceux-ci
+    <pre><span class="prompt">$</span> make install</pre>
-soient précis et circonstanciés, autant que possible. En clair, éviter de
+    (essentiellement équivalent à <code>git push</code>).
-mettre
+  </li>
-<pre>Correction d'un problème important dans foobar.tml</pre></li>
 
-<li>L'arborescence du site se trouve dans le fichier
+</ul>
-<code>00INDEX</code> et le fichier <code>00TODO</code> contient ce qui
-est en cours, avec diverses rubriques. Il est important que ces deux
-fichiers soient mis-à-jour.</li>
 
-</ol>
+<h2> Astuces plus avancées </h2>
 
-<h4>Ne pas publier une page tout de suite</h4>
+<h3>Ne pas publier une page tout de suite</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
@@ -173,14 +172,9 @@ actualite
 plan_site
 </pre>
         
-<p>
-Les fichiers <code>nolinks</code> peuvent être écrits directement, sans
-passer par <code>CVS</code>.  Comme cela, sur votre copie
-de travail, vous avez tous les liens.
-</p>
-        
 <p>Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
 disparaître le fichier <code>nolinks</code> :</p>
+
 <ul>
   <li>Éditez-le pour qu'íl devienne vide ;</li>
   <li>Regénérez les pages avec <code>rebuild</code> (ou <code>make
@@ -188,12 +182,11 @@ install</code>) ;</li>
   <li>Effacez le fichier <code>nolinks</code>.</li>
 </ul>
 
-<p> Vous trouverez des informations plus complètes sur la page de
+<h3> Branches </h3>
-  <a href="doc-interne-avancee.html">documentation interne avancée</a>.
+
-</p>
 
 <div class="metainformation">
-Auteurs : Joël Riou, Nicolas George et Éric Levieil.
+Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba.
 Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />.
 </div>