tuteurs.ens.fr/www/doc-interne.html

378 lines
14 KiB
HTML
Raw Normal View History

<?xml version="1.0" encoding="UTF-8"?>
2024-04-02 20:48:26 +02:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
2024-04-02 20:48:26 +02:00
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Doc. interne</title>
2024-04-02 20:48:26 +02:00
<link rel="stylesheet" href="tuteurs.css" type="text/css" />
</head>
<body>
2024-04-02 20:48:26 +02:00
<div class="navigation">
<h1>Tuteurs informatique<br /><a href="meta/contact.html">Nous contacter</a></h1>
<hr />
<ul class="menu">
<li>
<a href="meta/charte_graphique.html">Utiliser ce site</a>
</li>
<li>
<a href="actualite.html">Actu et stages</a>
</li>
<li>
<a href="docs/">Docs à imprimer</a>
</li>
<li>
<a href="meta/plan_site.html">Plan du site</a>
</li>
<li>
<a href="search.html">Rechercher</a>
</li>
</ul>
<hr />
<ul class="arbre">
<li>
<a href="./">Les tuteurs</a>
<ul class="arbre">
<li>
<a href="debutants.html">Débutants</a>
</li>
<li>
<a href="docs/">Documentations</a>
</li>
<li>
<a href="faq/">FAQ</a>
</li>
<li>
<a href="internet/">Internet</a>
</li>
<li>
<a href="liens/">Liens</a>
</li>
<li>
<a href="logiciels/">Logiciels</a>
</li>
<li>
<a href="meta/">Meta</a>
</li>
<li>
<a href="ressources/">Ressources</a>
</li>
<li>
<a href="theorie/">Théorie</a>
</li>
<li>
<a href="unix/">Unix</a>
</li>
</ul>
</li>
</ul>
<hr />
<ul class="menu">
<li>
<a href="http://www.eleves.ens.fr/">Serveur des élèves</a>
</li>
<li>
<a href="http://www.ens.fr/">ENS</a>
</li>
<li>
<a href="http://www.spi.ens.fr/">SPI</a>
</li>
</ul>
</div>
<div class="corps">
<h1>Mettre à jour le site des tuteurs ou y ajouter du contenu</h1>
<div class="sommaire">
<ul>
<li>
<a href="#s1"> Préliminaires </a>
<ul>
<li>
<a href="#s1_1"> Le dépôt git </a>
</li>
<li>
<a href="#s1_2"> Les outils TML </a>
</li>
</ul>
</li>
<li>
<a href="#s2"> Créer ou modifier une page </a>
</li>
<li>
<a href="#s3"> Trucs plus avancés </a>
<ul>
<li>
<a href="#s3_1"> Masquer une page dans l'arbre de navigation </a>
</li>
<li>
<a href="#s3_2"> Ignorer un commit dans le calcul de la dernière modification </a>
</li>
<li>
<a href="#s3_3"> Ajuster le nom sous lequel on apparaît dans les dernières
modifications </a>
</li>
<li>
<a href="#s3_4"> Quelqu'un a modifié les fichiers de <code>www</code> ! </a>
</li>
<li>
<a href="#s3_5"> Doc technique </a>
</li>
</ul>
</li>
</ul>
</div>
<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>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
<h2>
<a name="s1" id="s1"> Préliminaires </a>
</h2>
<h3>
<a name="s1_1" id="s1_1"> Le dépôt git </a>
</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>.
2002-12-06 18:19:11 +01:00
</p>
2024-04-02 20:48:26 +02:00
<div class="attention">
<p>
On ne modifie jamais directement les fichiers du répertoire
<code>~tuteurs/www</code>.
</p>
2024-04-02 20:48:26 +02:00
</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)
2002-11-16 19:28:04 +01:00
</p>
2024-04-02 20:48:26 +02:00
<pre><span class="prompt">$</span> git clone tuteurs@sas.eleves:www.git </pre>
<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>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
<pre><span class="prompt">$</span> export GIT_AUTHOR_NAME="Tartempion"
<span class="prompt">$</span> export GIT_AUTHOR_EMAIL="tartempion@phare"</pre>
2024-04-02 20:48:26 +02:00
</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>
2024-04-02 20:48:26 +02:00
<pre><span class="prompt">$</span> git config --global user.name "Tartempion"
<span class="prompt">$</span> git config --global user.email "tartempion@clipper"</pre>
2024-04-02 20:48:26 +02:00
<h3>
<a name="s1_2" id="s1_2"> Les outils TML </a>
</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>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
<pre>
PATH=\
$HOME/bin/$SYSTEMNAME:\
$HOME/bin:\
$UTILPATH:\
$MAINPATH:\
$GAMESPATH:\
$MISCPATH:\
/users/staffs/tuteurs/bin
</pre>
2024-04-02 20:48:26 +02:00
<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
2013-10-20 00:04:58 +02:00
de les récupérer avec <code>git clone tuteurs@sas.eleves: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>
2024-04-02 20:48:26 +02:00
<h2>
<a name="s2" id="s2"> Créer ou modifier une page </a>
</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>
2024-04-02 20:48:26 +02:00
<ul>
<li>
Commencez par synchroniser votre répertoire de travail avec le dépôt :
<pre><span class="prompt">$</span> git pull</pre>
</li>
2024-04-02 20:48:26 +02:00
<li>
Si <code>unix/accents.html</code> n'existe pas déjà, créez-le :
2009-10-02 22:19:43 +02:00
<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>
2024-04-02 20:48:26 +02:00
<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>&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.
&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
2024-04-02 20:48:26 +02:00
<a href="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>&lt;br&gt;</code>.
</li>
2024-04-02 20:48:26 +02:00
<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
2009-10-02 22:19:43 +02:00
<pre><span class="prompt">$</span> rebuild .</pre>
à la racine de votre copie de travail.
</li>
2024-04-02 20:48:26 +02:00
<li>
Quand vous avez terminé une modification, « commitez » en faisant :
2009-10-02 22:19:43 +02:00
<pre><span class="prompt">$</span> git add accents.tml
<span class="prompt">$</span> git commit</pre>
Tâchez de mettre un commentaire explicite.
</li>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
</ul>
<h2>
<a name="s3" id="s3"> Trucs plus avancés </a>
</h2>
<h3>
<a name="s3_1" id="s3_1"> Masquer une page dans l'arbre de navigation </a>
</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>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
<pre><span class="prompt">sas ~tuteurs/www $</span> cat nolinks
doc-interne
aide
404
actualite
plan_site
</pre>
2024-04-02 20:48:26 +02:00
<p> Pour supprimer un fichier <code>nolinks</code>, procédez en
plusieurs étapes :</p>
2024-04-02 20:48:26 +02:00
<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>
2024-04-02 20:48:26 +02:00
<li>effacez le fichier <code>nolinks</code>.</li>
</ul>
<h3>
<a name="s3_2" id="s3_2"> Ignorer un commit dans le calcul de la dernière modification </a>
</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>
2024-04-02 20:48:26 +02:00
<h3>
<a name="s3_3" id="s3_3"> Ajuster le nom sous lequel on apparaît dans les dernières
modifications </a>
</h3>
<p> Voir le fichier <code>.mailmap</code>. </p>
<h3>
<a name="s3_4" id="s3_4"> Quelqu'un a modifié les fichiers de <code>www</code> ! </a>
</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>
2024-04-02 20:48:26 +02:00
<h3>
<a name="s3_5" id="s3_5"> Doc technique </a>
</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>
2024-04-02 20:48:26 +02:00
<div class="metainformation">
Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba.
2024-04-02 20:48:26 +02:00
Dernière modification : 2013-10-20 par Antoine Amarilli.
</div>
2024-04-02 20:48:26 +02:00
</div>
</body>
</html>