006f22ffeb
Depuis le compte tuteurs, le push local marche. Le souci dans les autres cas doit donc être une problème de droits...
299 lines
11 KiB
XML
299 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE html
|
||
PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
|
||
"tuteurs://DTD/tml.dtd">
|
||
<html>
|
||
<head>
|
||
<title>Doc. interne</title>
|
||
</head>
|
||
<body>
|
||
|
||
<h1>Mettre à jour le site des tuteurs ou y ajouter du contenu</h1>
|
||
|
||
<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>
|
||
|
||
<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>.
|
||
</p>
|
||
|
||
<div class="attention">
|
||
<p>
|
||
On ne modifie jamais directement les fichiers du répertoire
|
||
<code>~tuteurs/www</code>.
|
||
</p>
|
||
</div>
|
||
|
||
<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 (mais elle ne marche pas,
|
||
méthode à éviter pour le moment donc).
|
||
</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>.
|
||
</p>
|
||
|
||
<div class="attention">
|
||
<p>
|
||
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 :
|
||
</p>
|
||
<pre><span class="prompt">$</span> export GIT_AUTHOR_NAME="Tartempion"
|
||
<span class="prompt">$</span> export GIT_AUTHOR_EMAIL="tartempion@phare"</pre>
|
||
</div>
|
||
|
||
<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>
|
||
PATH=\
|
||
$HOME/bin/$SYSTEMNAME:\
|
||
$HOME/bin:\
|
||
$UTILPATH:\
|
||
$MAINPATH:\
|
||
$GAMESPATH:\
|
||
$MISCPATH:\
|
||
/users/staffs/tuteurs/bin
|
||
</pre>
|
||
|
||
<p>
|
||
(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
|
||
de les récupérer avec <code>git clone tuteurs@clipper:share/tml</code>
|
||
et y faire les adaptations nécessaires : il y a des chemins à adapter
|
||
dans <code>tml/lib/catalog.xml</code>, ainsi que <code>$BASE</code>
|
||
dans <code>tmlcheck</code>, <code>build</code> et
|
||
<code>rebuild</code>.)
|
||
</p>
|
||
|
||
|
||
<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>
|
||
|
||
<ul>
|
||
<li>
|
||
Commencez par synchroniser votre répertoire de travail avec le dépôt :
|
||
<pre><span class="prompt">$</span> git pull</pre>
|
||
</li>
|
||
<li>
|
||
Si <code>unix/accents.html</code> n'existe pas déjà, créez-le :
|
||
<pre><span class="prompt">$</span> cd unix
|
||
<span class="prompt">$</span> tmltemplate accents.tml <em>"titre court"</em> <em>"titre long"</em>
|
||
<span class="prompt">$</span> emacs accents.tml</pre>
|
||
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 est étroit), le <em>titre long</em> apparaîtra en
|
||
haut de la page. Pour modifier un fichier existant, idem sauf le
|
||
<code>tmltemplate</code>.
|
||
</li>
|
||
<li>
|
||
Écrivez le contenu du fichier. Ce dernier sera passé dans une
|
||
moulinette qui s'appelle <code>xsltproc</code> qui, entre autres
|
||
choses, ajoute automatiquement à la page un plan du site sur gauche
|
||
et un sommaire en début de page.
|
||
La moulinette TML et la feuille de style <code>tuteurs.css</code>
|
||
permettent de faire facilement des encadrés, de jolis prompts,
|
||
etc. : voyez les pages existantes pour des exemples, et la feuille
|
||
de style elle-même (voire la moulinette) pour tous les détails. 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.
|
||
<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. Rappelons juste que toutes les balises doivent être
|
||
refermées, que leurs noms s'écrivent en minuscules, et qu'il est de
|
||
mauvais goût d'aller à la ligne sauvagement avec
|
||
<code><br></code>.
|
||
</li>
|
||
|
||
<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>
|
||
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">$</span> rebuild .</pre>
|
||
à la racine de votre copie de travail.
|
||
</li>
|
||
|
||
<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.
|
||
</li>
|
||
|
||
<li>
|
||
Répétez ce qui précède autant de fois que nécessaire. À la fin,
|
||
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> Trucs plus avancés </h2>
|
||
|
||
<h3> Masquer une page dans l'arbre de navigation </h3>
|
||
|
||
<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
|
||
contenir une liste séparée par des espaces ou des retours à la ligne de
|
||
choses de la forme « <code>fichier</code> » ou encore
|
||
« <code>répertoire/</code> ». Cela désactivera les liens éventuels vers
|
||
la page <code>fichier.html</code> ou vers l'index de
|
||
<code>répertoire</code>.</p>
|
||
|
||
<p>Par exemple, pour ne pas faire apparaître cette page de documentation
|
||
interne aux tuteurs (et quelques autres) dans l'index, la racine du
|
||
<code>CVS</code> contient :
|
||
</p>
|
||
|
||
<pre><span class="prompt">clipper ~tuteurs/www $</span> cat nolinks
|
||
doc-interne
|
||
aide
|
||
404
|
||
actualite
|
||
plan_site
|
||
</pre>
|
||
|
||
<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
|
||
install</code>) ;</li>
|
||
<li>effacez le fichier <code>nolinks</code>.</li>
|
||
</ul>
|
||
|
||
<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.
|
||
<date value="from git" />
|
||
</div>
|
||
|
||
</body>
|
||
</html>
|