tuteurs.ens.fr/doc-interne.tml
2007-06-08 14:25:14 +00:00

530 lines
18 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
"tuteurs://DTD/tml.dtd">
<html>
<head>
<title>Doc. interne</title>
</head>
<body>
<h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu</h1>
<p> Comme vous le savez, le site des tuteurs subit un lifting.
Marie-Lan et Nicolas ont notamment choisi les couleurs et la présentation
du <a href="./">nouveau site</a>, et Nicolas a implémenté un
certain nombre de scripts (ceux-ci se trouvent dans la branche
<code>utilitaires/tml</code> du <code>cvstuteurs</code>). </p>
<div class="attention">
<h1>&icone.attention; Attention &icone.attention;</h1>
<p>
Ne pas modifier la branche <code>utilitaires/tml</code> du
<code>cvstuteurs</code> à moins de savoir vraiment ce que vous faites,
puisque tout le site Web en dépend.</p>
</div>
<p>
Cette page a pour but :</p>
<ul>
<li>non seulement d'expliquer comment modifier le site;</li>
<li><em>mais aussi</em> de servir de fichier d'exemple pour l'élaboration des
pages.</li>
</ul>
<p>
Un bref résumé des choses à ne pas faire se trouve dans les dix
<a href="#commandements">commandements</a>.
</p>
<h2>Comment tout cela fonctionne ?</h2>
<p> Tout est géré depuis l'arborescence <code>web</code> du
<code>cvstuteurs</code>. (NDjriou: l'ancien site est toujours dans
l'arborescence <code>www</code> dudit <code>cvs</code>) </p>
<p>
Dans ce <code>cvs</code> figurent uniquement des fichiers
<code>.tml</code> et des fichiers téléchargeables (icônes, screenshots,
illustrations du Hublot, PostScripts gzippés d'icelui)
</p>
<p>
Le site Web en lui-même se trouve à l'adresse <a
href="./"><code>http://www.tuteurs.ens.fr/</code></a>.
Pour des raisons de compatibilité avec l'ancien site Web des tuteurs et
la phase transitoire, les adresses
<code>http://www.eleves.ens.fr/tuteurs/ancien-site/</code> sont
redirigées vers <code>http://www.tuteurs.ens.fr/</code> et les
noms sous lesquels les pages existaient avant sont redirigées vers leur
nouvelle position.
</p>
<h3>Les fichiers <code>tml</code></h3>
<h4>Théoriquement</h4>
<p>Pour faire une nouvelle page Web, il faut écrire un fichier
<code>foobar.tml</code>. C'est presque du HTML, mais il y a quelques
nuances. En effet, ces fichiers sont passés dans une moulinette qui
s'appelle <code>xsltproc</code> quand vous exécutez la commande :</p>
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web/docs/hublot $</span> ~tuteurs/bin/build hublot12.tml
</pre>
<p>Il en ressort normalement (s'il n'y a pas trop d'erreurs de syntaxe) un
fichier <code>html</code> très joli. Ce dernier utilise une feuille de
style <code>tuteurs.css</code>, contient une bande de navigation à gauche
présentant notamment un arbre du site et un sommaire de la page en cours
de lecture, le tout généré automatiquement grâce à la patience du
concepteur de la nouvelle charte graphique.</p>
<div class="encadre">
<p>Les scripts prennent en compte le <em>titre</em> des pages pour générer
l'arborescence. Il convient donc de les faire courts.</p>
</div>
<p>La moulinette et la feuille de style permettent de faire très simplement
beaucoup choses : des encadrés, des jolis prompts, des
tableaux...</p>
<p>
Par ailleurs, dans les fichiers <code>.tml</code>, tous les liens
internes à la page des tuteurs doivent être relatifs, mais il y a une
astuce : la racine de l'arborescence du site a pour synonyme
<code>&amp;url.tuteurs;</code>. Ainsi, dans
<code>logiciels/latex/astuces.tml</code>, on trouve le lien
suivant :</p>
<blockquote>
<p>&lt;p&gt; Mais cela ne doit pas vous empêcher de prendre de &lt;a
href="&amp;url.tuteurs;docs/hublot/typo.html"&gt;bonnes
habitudes&lt;/a&gt; quand vous tapez avec d'autres logiciels ou que vous
rédigez un courrier toutes les ponctuations sont suivies d'une espace,
seules les ponctuations doubles sont précédées d'une espace.&lt;/p&gt;</p>
</blockquote>
<h4>Concrètement...</h4>
<p>Pour faire un fichier <code>page.tml</code>, récupérez l'en-tête d'un
autre fichier <code>.tml</code> du site, et modifiez les titres:
</p>
<pre>
&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;!DOCTYPE html
PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
"tuteurs://DTD/tml.dtd"&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Les tuteurs&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;h1&gt;Le site des tuteurs&lt;/h1&gt;
&lt;p&gt; Bienvenue sur la page Web des tuteurs informatique de l'École
Normale Supérieure. Le contenu de ce site est organisé en grands
thèmes| :&lt;/p&gt;
</pre>
<p>
Il est également possible d'utiliser la commande <code>tmltemplate
<em>fichier.tml</em> [<em>titre</em>] [<em>titre long</em>]</code>.
</p>
<p>
Le titre de la page (ici « Les tuteurs ») doit être le plus court
possible car c'est lui qui est pris en compte pour faire l'arbre de
navigation qui se trouvent sur la gauche lors de l'affichage par un
navigateur en mode graphique de la page Web une fois générée par les
scripts.
</p>
<p>
Le titre qui s'affiche en gros tout en haut de la page doit être indiqué
avec une balise <code>&lt;h1&gt;</code>, les différentes sections avec
<code>&lt;h2&gt;</code>, etc... Enfin, un paragraphe doit se trouver à
l'intérieur d'une balise <code>&lt;p&gt;</code>.
</p>
<p>
Lorsque l'on exécute le script <code>build</code> sur un fichier
<code>.tml</code>, le fichier <code>.html</code> produit contient un
sommaire en dessous du gros titre, celui-ci est généré à partir des
balises <code>&lt;h2&gt;</code> et <code>&lt;h3&gt;</code> se trouvant
dans le fichier <code>.tml</code>.
</p>
<h4><a name="date" />Les dates de dernière modification</h4>
<p>À partir de l'instant où vous lisez ces lignes, quand vous écrirez une
page pour le site des tuteurs ou que vous en modifierez une, vous devrez
<strong>obligatoirement</strong> (de toute façon, vous ne pourrez pas
faire autrement, hé, hé...) mettre à la fin des lignes du type:
</p>
<pre>
&lt;div class="metainformation"&gt;
Auteur : Comptes tuteurs.
Dernière modification le &lt;date value="&#36;Date&#36;" /&gt;.
&lt;/div&gt;
</pre>
<p>Quand vous commiterez vos modifications avec <code>CVS</code>,
ce dernier modifiera votre fichier pour insérer la vraie date à côté de
<code>&#36;Date&#36;</code>. N'y touchez-plus, <code>CVS</code> et les
scripts de génération des fichiers <code>html</code> s'occupent de tout.
</p>
<h3>Les fichiers <code>html</code></h3>
<p>Les scripts transforment les <code>.tml</code> en <code>.html</code>. Ces
derniers doivent être du <strong>XHTML 1.0 Strict</strong>. Pour le
vérifier, passez les pages que vous modifiez au <a
href="http://validator.w3.org/">validateur</a>.</p>
<p>Quelles sont les différences entre le HTML usuel et le XHTML 1.0
Strict ?</p>
<ul>
<li><strong>Toutes</strong> les balises doivent être refermées. Ainsi,
pour faire un paragraphe on fait
<pre>
&lt;p&gt;
En utilisant la suite spectrale de coniveau, on peut démontrer le
théorème [...].
&lt;/p&gt;
</pre>
</li>
<li>On évite au maximum les retours à la ligne sauvages avec
<code>&lt;br&gt;</code>. D'ailleurs, ce genre de balises sont écrire
sous la forme <code>&lt;br /&gt;</code> pour se conformer à la première
exigence ;
</li>
<li>
Tous les paramètres doivent être mis entre guillements et les images
doivent avoir un paramètre alternatif :
<pre>
&lt;img src="docs/hublot/hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]"/&gt;
</pre>
</li>
<li>
Toutes les balises doivent être mises en minuscules.
</li>
</ul>
<p>Après que le repository du <code>cvstuteurs</code> est modifié
<em>via</em> la commande <a href="#makeinstall"><code>make
install</code></a> dans la racine de son répertoire de travail (ou celui
d'un autre), les fichiers <code>.tml</code> figurant dans
<code>~tuteurs/www/web</code> sont mis à jour, et le script
<code>rebuild</code> est lancé dedans : ce script exécute
<code>build</code> sur tous les fichiers <code>.tml</code> qui en ont
besoin, ce qui permet de mettre à jour les fichiers <code>.html</code> du
site.</p>
<h2>Comment modifier le site ?</h2>
<p>Comme le site est géré via <code>cvs</code>, il convient de connaître
le minimum nécessaire pour utiliser ce logiciel, nous allons le voir
ci-dessous. Pour en connaître plus sur CVS (en complément de ce qui est
indiqué ci-dessous), voyez
la <a href="&url.tuteurs;logiciels/cvs/">documentation sur CVS sur le
site des tuteurs</a>.
</p>
<h3>Se créer un répertoire de travail</h3>
<p>Pour utiliser <code>cvs</code>, il faut se créer un répertoire de
travail <em>chez soi</em>, c'est-à-dire récupérer les fichiers se
trouvant dans le <em>repository</em>, à savoir
<code>~tuteurs/cvs/web</code>. Pour cela, il suffit de taper la commande
suivante dans votre répertoire <code>~/tuteurs/cvs</code> par
exemple :</p>
<pre>
<span class="prompt">bireme ~/tuteurs/cvs $</span> cvstuteurs checkout web
</pre>
<p>Il est impératif d'utiliser <code>cvstuteurs</code> à la place de
<code>cvs</code> : ce permet de faire travailler <code>cvs</code>
directement dans le repository des tuteurs et de le faire travailler en
tant que membre du groupe tuteurs, ce qui est très important pour éviter
de tout casser (comme c'est arrivé le premier jour). Par conséquent, je
vous recommande vivement d'insérer la ligne suivante dans votre
<code>.zshrc</code> :</p>
<pre>
alias cvs='echo "Non, tu ne veux pas utiliser cvs directement, utilise cvstuteurs"'
</pre>
<p>
Vous voyez apparaître quelques fichiers <code>.tml</code> dans votre
répertoire de travail. Pour les transformer en <code>.html</code>,
faites :
</p>
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span> ~tuteurs/bin/rebuild .
</pre>
<h3>Contribuer au nouveau site</h3>
<p>Prenons un exemple. Supposons que vous souhaitiez écrire la page
<code>unix/accents.html</code>.</p>
<ol>
<li>
Commencez par synchroniser votre répertoire de travail avec le repository
(bien sûr, si un fichier de votre répertoire est plus récent que la
version du repository, il n'y a pas de modification). Faites sans
danger :
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span> cvstuteurs update
</pre>
Il arrive souvent que <code>cvs</code> vous demande de faire cette
man&oelig;uvre avant de faire un commit (i.e. de prendre en compte vos
modifications).
</li>
<li>Pour commencer à travailler sur ce nouveau fichier, faites :<br />
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span> cd unix
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span> tmltemplate accents.tml <em>"titre court"</em> <em>"titre long"</em> 
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span> cvstuteurs add accents.tml
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span> vim accents.tml
</pre>
La troisième commande permet de dire à <code>cvs</code> que vous préparez
un fichier <code>unix/accents.tml</code>, il faut que ce fichier existe
avant de lancer cette commande, c'est à cela que sert le script
<code>tmltemplate</code>.
Le <em>titre court</em> est celui qui apparaîtra dans l'arborescence du
site à gauche des pages, le <em>titre long</em> sera écrit en gros en
haut de la page.
</li>
<li>
Écrivez le contenu de la page Web, c'est-à-dire dans ce cas en mettant à
jour la page figurant sur l'ancien site et en le rendant conforme au
standard XHTML 1.0 Strict.
</li>
<li>
Vérifiez votre page avec :
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span> tmlcheck accents.tml
</pre>
La commande <code>tmlcheck</code> est un peu plus stricte que
build. S'il y a des erreurs d'équilibrage entre les balises ouvrantes et
fermantes, il peut être difficile de trouver la balise ouvrante
coupable. Pour ça, on peut utiliser <code>xmlbalance</code>, qui indique
la position des balises incriminées (en caractères, utiliser
<code>go</code> avec Vim). </li>
<li>
Lancez le script de conversion en <code>.html</code> en faisant :
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span> build accents.tml
</pre>
Notez que si d'autres fichiers <code>tml</code> se trouvent dans le
répertoire courant, leur syntaxe sera aussi vérifiée (pour créer
l'arborescence dans <code>accents.tml</code>).
</li>
<li>
Corrigez les fautes de syntaxe.
</li>
<li>Si vous avez fait beaucoup de modifications, il peut être utile de
faire :
<pre>
<span class="prompt">bireme ~/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>. Pour cela, il peut être
pratique de faire un lien symbolique permettant d'accéder par le Web à
votre répertoire de travail :<br />
<pre>
<span class="prompt">bireme ~/www</span> ln -s ../tuteurs/cvs/web tuteurs
</pre>
Cependant, il faudrait éviter que votre copie de travail se retrouve
répertoriée dans un moteur de recherche comme Google par exemple (cela
pourrait arriver si vous cliquez sur un lien depuis votre page). Donc,
essayez d'utiliser un fichier <a
href="&url.tuteurs;internet/web/htaccess.html"><code>.htaccess</code></a>
adapté pour limiter l'accès à votre copie du site depuis l'extérieur.
</li>
<li>
Un démon mensuel fait une liste des liens cassés sur le site, tenez-en
compte.
</li>
<li><a name="makeinstall"/>
Quand tout est au point, vous pouvez « commiter » en faisant :
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span> make install
</pre>
Pour information, voici le contenu du <code>Makefile</code>
<pre>
install:
cvstuteurs commit
su-tuteurs cvstuteurs update -d /users/staffs/tuteurs/www/web
su-tuteurs /users/staffs/tuteurs/share/tml/bin/rebuild /users/staffs/tuteurs/www/web
</pre>
La première ligne intéressante met à jour le repository compte tenu de
vos modifications et créations. La deuxième met à jour met à jour entre
autres les fichiers <code>tml</code> de la page Web en fonction du
repository nouveau et la troisième ligne met à jour les fichiers
<code>html</code> et en crée éventuellement de nouveaux.
</li>
<li>
Pendant l'exécution de <code>cvstuteurs commit</code>, on vous demande
d'indiquer des commentaires sur les man&oelig;uvres que vous avez faites
dans les différents répertoires. Il est extrêmement important que ceux-ci
soient précis et circonstanciés, autant que possible. En clair, éviter de
mettre
<pre>Correction d'un problème important dans foobar.tml</pre>
</li>
</ol>
<h3>Quelques astuces</h3>
<h4>Ne pas publier une page tout de suite</h4>
<p>Imaginons que vous avez commencé à travailler une nouvelle section du
site, que les pages que vous venez de faire ne soient pas tout-à-fait au
point. Vous pouvez alors 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>
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>
Un autre exemple : pendant le développement de la partie
<code>logiciels/mozilla/</code> du site, le fichier
<code>logiciels/nolinks</code> contenait:
</p>
<pre>
mozilla/
</pre>
<p>
On peut conseiller de ne pas rentrer ce fichier <code>nolinks</code> dans
<code>CVS</code>, mais seulement de le mettre au bon endroit à partir de
<code>~tuteurs/www/</code>, cela simplifie un peu les choses, et comme
cela, sur votre copie de travail, vous avez tous les liens.
</p>
<div class="attention">
<h1>&icone.attention; Attention &icone.attention;</h1>
<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
install</code>) ;</li>
<li>Effacez le fichier <code>nolinks</code>.</li>
</ul>
<p>En effet, si vous effacez directement le fichier <code>nolinks</code>,
<em>a priori</em>, le script de regénération ne refabriquera pas les
pages et les liens vers les nouvelles pages ne seront pas insérés.
</p>
</div>
<h2>Quoi faire ?</h2>
<p>
L'arborescence voulue du site se trouve dans le fichier
<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 assez régulièrement.
</p>
<p>Pour finir, voici quelques recommandations concernant la modification du
site Web.</p>
<div class="attention">
<h1>&icone.attention; <a name="commandements">Les dix commandements de
cvstuteurs/web</a> &icone.attention;</h1>
<ol>
<li>
Tu n'utiliseras pas <code>cvs</code> mais <code>cvstuteurs</code>.
</li>
<li>
Tu ne modifieras jamais directement ce qui se trouve dans
<code>~tuteurs/cvs/</code> et en particulier <code>~tuteurs/cvs/web/</code>.
</li>
<li>
Tu ne modifieras pas non plus directement <code>~tuteurs/www/web/</code>.
</li>
<li>
Pour commiter, tu ne feras point <code>cvstuteurs commit</code>,
mais <code>make install</code> dans la racine de ton répertoire de travail.
</li>
<li>
Tu ajouteras des fichiers binaires en faisant <code>cvstuteurs add -kb
foobar.png</code>
</li>
<li>
De fichiers <code>.gif</code> tu ne créeras point, parce que c'est <a
href="http://www.gnu.org/philosophy/gif.html">mal</a>.
</li>
<li>
Tu liras et upgraderas <code>00TODO</code> et <code>00INDEX</code>.
</li>
<li>
Des liens relatifs tu utiliseras.
</li>
<li>
Des commentaires précis tu indiqueras lors d'un commit.
</li>
<li>
Pour ne point laisser traîner des liens cassés, tu examineras les logs
du démon vérifieur qui se manifeste au début de chaque mois.
</li>
</ol>
</div>
<p><em>Je vous prie de bien vouloir excuser les anglicismes
scandaleusement présents dans cette page.</em></p>
<div class="metainformation">
Auteur : Joël Riou et Nicolas George.
Dernière modification le <date value="$Date: 2007-06-08 14:25:14 $" />.
</div>
</body>
</html>