DGNum/tuteurs.ens.fr
16
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Mise à jour doc interne.

Browse source 
Première version plus ou moins complète post-passage à git. Reste à
adapter/virer la doc interne avancée.
This commit is contained in:
Marc Mezzarobba 2009-10-02 22:13:50 +02:00
parent ebbb37a220
commit 42a5a2c851
1 changed files with 153 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

224
doc-interne.tml
View file

@ -8,28 +8,90 @@
</head> </head>
<body> <body>
<h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu?</h1> <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>
<h2> Rajouter <code>~tuteurs/bin</code> dans votre <code>PATH</code></h2>
<p> <p>
La plupart des programmes utilisés dans la suite sont dans Les pages HTML du site web des tuteurs sont produites à partir de
<code>~tuteurs/bin</code>. Éditez le fichier <code> .profile </code> à fichiers dans un format XML maison appelé TML. Tout le contenu du site
la racine de votre compte, trouvez le passage qui parle du PATH et est sous <a href="logiciels/git/">git</a>, et l'arborescence HTML est
modifiez la fin. Attention, ne pas oublier de mettre :\ (non suivi mise à jour automatiquement à chaque <code>push</code> (de la branche
d'espace !) à la fin de l'avant-dernière ligne, et de tester (en qui va bien) dans <code>~tuteurs/www.git</code>.
vous logguant une deuxième fois) <em>avant</em> de se délogguer. </p>
<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>
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> </p>
<pre> <pre>
@ -43,36 +105,22 @@ $MISCPATH:\
/users/staffs/tuteurs/bin /users/staffs/tuteurs/bin
</pre> </pre>
<h2> Récupérer une copie de travail </h2>
<p> <p>
Le site web des (Aucun de ces programmes n'est indispensable pour modifier le site
<a href="logiciels/git/">git</a>. Je ne réexplique pas comment se web. Pour travailler depuis chez soi, on a le choix de s'en passer ou
servir de git ici, allez voir la page qu'on a déjà à ce sujet... 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>
<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> <p>
Supposons que vous souhaitiez créer ou modifier la page Supposons que vous souhaitiez créer ou modifier la page
<code>unix/accents.html</code>. Pour cela, il va falloir écrire un <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> <ul>
<li> <li>
@ -94,41 +142,36 @@ $MISCPATH:\
Écrivez le contenu du fichier. Ce dernier sera passé dans une Écrivez le contenu du fichier. Ce dernier sera passé dans une
moulinette qui s'appelle <code>xsltproc</code> qui rajoute moulinette qui s'appelle <code>xsltproc</code> qui rajoute
automatiquement un plan du site à gauche et un sommaire de la page automatiquement un plan du site à gauche et un sommaire de la page
en cours de lecture. Les liens internes à la page des tuteurs en cours de lecture. Les liens internes au site des tuteurs
doivent être sous la forme: 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> <pre>&lt;a href="&amp;url.tuteurs;docs/hublot/typo.html"&gt;</pre>
Il faut mettre à la fin du fichier des lignes du type: Il faut mettre à la fin du fichier des lignes du type:
<pre>&lt;div class="metainformation"&gt; <pre>&lt;div class="metainformation"&gt;
Auteur : Comptes tuteurs. 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> &lt;/div&gt;</pre>
Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du 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 <a href="&url.tuteurs;internet/web/html/">tutoriel XHTML</a> des
tuteurs. tuteurs.
</li> </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> <pre><span class="prompt">$</span> tmlcheck accents.tml</pre>
</li> et la convertir en html en faisant
<li>
Lancez le script de conversion en <code>.html</code> en faisant :
<pre><span class="prompt">$</span> build accents.tml</pre> <pre><span class="prompt">$</span> build accents.tml</pre>
Si vous avez fait beaucoup de modifications, il peut être utile de Si vous avez fait beaucoup de modifications, il peut être utile de
lancer lancer
<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .</pre> <pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .</pre>
à la racine de votre copie de travail.</li> à la racine de votre copie de travail.
<li>
Passez la page que vous venez de créer au <a
href="http://validator.w3.org/">validateur</a>.
</li> </li>
<li id="makeinstall"> <li>
Quand vous avez terminé une modification, vous pouvez « commiter » Quand vous avez terminé une modification, « commitez » en faisant :
en faisant : <pre><span class="prompt">$</span> git add accents.tml
<pre>
<span class="prompt">$</span> git add accents.tml
<span class="prompt">$</span> git commit <span class="prompt">$</span> git commit
</pre> </pre>
Tâchez de mettre un commentaire explicite. 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 installez vos modifications sur le site web avec
<pre><span class="prompt">$</span> make install</pre> <pre><span class="prompt">$</span> make install</pre>
(essentiellement équivalent à <code>git push</code>). (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> </li>
</ul> </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 <p>
premier temps vos nouvelles pages dans l'arbre de navigation qui se Vous pouvez décider de ne pas faire apparaître une page dans l'arbre
trouve sur la gauche des pages.</p> 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 <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 répertoire si un fichier <code>nolinks</code> s'y trouve. Ce fichier doit
@ -172,18 +220,52 @@ actualite
plan_site plan_site
</pre> </pre>
<p>Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire <p> Pour supprimer un fichier <code>nolinks</code>, procédez en
disparaître le fichier <code>nolinks</code> :</p> plusieurs étapes :</p>
<ul> <ul>
<li>Éditez-le pour qu'íl devienne vide ;</li> <li>éditez-le pour qu'íl devienne vide ;</li>
<li>Regénérez les pages avec <code>rebuild</code> (ou <code>make <li>regénérez les pages avec <code>rebuild</code> (ou <code>make
install</code>) ;</li> install</code>) ;</li>
<li>Effacez le fichier <code>nolinks</code>.</li> <li>effacez le fichier <code>nolinks</code>.</li>
</ul> </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"> <div class="metainformation">
Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba. Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba.