Mise à jour doc interne.
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
parent
ebbb37a220
commit
42a5a2c851
1 changed files with 153 additions and 71 deletions
224
doc-interne.tml
224
doc-interne.tml
|
|
@ -8,28 +8,90 @@
|
|||
</head>
|
||||
<body>
|
||||
|
||||
<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>
|
||||
<h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu?</h1>
|
||||
|
||||
<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.
|
||||
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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>&url.tututeurs;</code>, ce qui donne
|
||||
des liens de la forme :
|
||||
<pre><a href="&url.tuteurs;docs/hublot/typo.html"></pre>
|
||||
Il faut mettre à la fin du fichier des lignes du type:
|
||||
<pre><div class="metainformation">
|
||||
Auteur : Comptes tuteurs.
|
||||
Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />.
|
||||
<date value="from git" />.
|
||||
</div></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>
|
||||
à 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>.
|
||||
</li>
|
||||
|
||||
<li id="makeinstall">
|
||||
Quand vous avez terminé une modification, vous pouvez « commiter »
|
||||
en faisant :
|
||||
<pre>
|
||||
<span class="prompt">$</span> git add accents.tml
|
||||
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 <date value="$Date: 2008-10-05 11:20:36 $" />.
|
|||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue