tuteurs.ens.fr/doc-interne.tml

359 lines
12 KiB
Text
Raw Normal View History

<?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 <20> jour le site des tuteurs ou y ajouter du contenu</h1>
<p> Comme vous le savez, le site des tuteurs doit subir un lifting.
Marie-Lan et Nicolas ont notamment choisi les couleurs et la pr<70>sentation
du <a href="&url.tuteurs;">nouveau site</a>, et Nicolas a impl<70>ment<6E> 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;<3B>Attention<6F>&icone.attention;</h1>
<p>
Ne pas modifier la branche <code>utilitaires/tml</code> du
<code>cvstuteurs</code> <20> moins de savoir vraiment ce que vous faites,
puisque tout le site Web en d<>pend.</p>
</div>
<p>
Cette page a pour but<75>:</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'<27>laboration des
pages.</li>
</ul>
<p>
Un bref r<>sum<75> des choses <20> ne pas faire se trouve dans les dix
<a href="#commandements">commandements</a>.
</p>
<h2>Comment tout cela fonctionne<6E>?</h2>
<p> Tout est g<>r<EFBFBD> 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<EFBFBD>chargeables (icones, screenshots,
illustrations du hublot, PostScripts gzipp<70>s d'icelui)
</p>
<p>
Le site Web en lui-m<>me se trouve <20> l'adresse <a
href="&url.tuteurs;"><code>http://www.eleves.ens.fr/tuteurs/web/</code></a>
temporairement. Quand il sera termin<69>, il reviendra <20> sa place, <20> savoir
<code>http://www.eleves.ens.fr/tuteurs/</code>.
</p>
<h3>Les fichiers <code>tml</code></h3>
<p>Pour faire une nouvelle page Web, il faut <20>crire un fichier
<code>foobar.tml</code>. C'est presque du HTML, mais il y a quelques
nuances. En effet, ces fichiers sont pass<73>s dans une moulinette qui
s'appelle <code>xsltproc</code> quand vous <20>x<EFBFBD>cutez la commande :</p>
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web/docs/hublot $</span><3E>~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<74>s joli. Ce dernier utilise une feuille de
style <code>tuteurs.css</code>, contient une bande de navigation <20> gauche
pr<EFBFBD>sentant notamment un arbre du site et un sommaire de la page en cours
de lecture, le tout g<>n<EFBFBD>r<EFBFBD> automatiquement gr<67>ce <20> 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<EFBFBD>rer
l'arborescence. Il convient donc de les faire courts.</p>
</div>
<p>La moulinette et la feuille de style permettent de faire tr<74>s simplement
beaucoup choses<65>: des encadr<64>s, des jolis prompts, des
tableaux...</p>
<p>
Par ailleurs, dans les fichiers <code>.tml</code>, tous les liens
internes <20> la page des tuteurs doivent <20>tre relatifs, mais il y a une
astuce<EFBFBD>: 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<EFBFBD>:</p>
<blockquote>
2002-11-11 10:16:30 +01:00
<p>&lt;p&gt; Mais cela ne doit pas vous emp<6D>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<EFBFBD>digez un courrier toutes les ponctuations sont suivies d'un espace,
seules les ponctuations doubles sont pr<70>c<EFBFBD>d<EFBFBD>es d'un espace.&lt;/p&gt;</p>
</blockquote>
<h3>Les fichiers <code>html</code></h3>
<p>Les scripts transforment les <code>.tml</code> en <code>.html</code>. Ces
derniers doivent <20>tre du <strong>XHTML 1.0 Strict</strong>. Pour le
v<EFBFBD>rifier, passez les pages que vous modifiez au <a
href="http://validator.w3.org/">validateur</a>.</p>
<p>Quelles sont les diff<66>rences entre le HTML usuel et le XHTML 1.0
Strict ?</p>
<ul>
<li><strong>Toutes</strong> les balises doivent <20>tre referm<72>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<EFBFBD>or<EFBFBD>me [...].
&lt;/p&gt;
</pre>
</li>
<li>On <20>vite au maximum les retours <20> la ligne sauvages avec
<code>&lt;br&gt;</code>. D'ailleurs, ce genre de balises sont <20>crire
sous la forme <code>&lt;br<62>/&gt;</code> pour se conformer <20> la premi<6D>re
exigence<EFBFBD>;
</li>
<li>
Tous les param<61>tres doivent <20>tre mis entre guillements et les images
doivent avoir un param<61>tre alternatif :
<pre>
&lt;img src="hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]"&gt;
</pre>
</li>
</ul>
<p>Apr<70>s que le repository du <code>cvstuteurs</code> est modifi<66>
<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-<2D>-jour, et le script
<code>rebuild</code> est lanc<6E> dedans<6E>: ce script <20>x<EFBFBD>cute
<code>build</code> sur tous les fichiers <code>.tml</code> qui en ont
besoin, ce qui permet de mettre <20> jour les fichiers <code>.html</code> du
site.</p>
<h2>Comment modifier le site<74>?</h2>
<p>Comme le site est g<>r<EFBFBD> via <code>cvs</code>, il convient de conna<6E>tre
le minimum n<>cessaire pour utiliser ce logiciel, nous allons le voir
ci-dessous.
</p>
<h3>Se cr<63>er un r<>pertoire de travail</h3>
<p>Pour utiliser <code>cvs</code>, il faut se cr<63>er un r<>pertoire de
travail <em>chez soi</em>, c'est-<2D>-dire r<>cup<75>rer les fichiers se
trouvant dans le <em>repository</em>, <20> 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<EFBFBD>:</p>
<pre>
<span class="prompt">bireme ~/tuteurs/cvs $</span><3E>cvstuteurs checkout web
</pre>
<p>Il est imp<6D>ratif d'utiliser <code>cvstuteurs</code> <20> la place de
<code>cvs</code><3E>: 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<74>s important pour <20>viter
de tout casser (comme c'est arriv<69> le premier jour). Par cons<6E>quent, je
vous recommande vivement d'ins<6E>rer la ligne suivante dans votre
<code>.zshrc</code></p>
<pre>
alias cvs='echo "Attention, tu utilises cvstuteurs";sleep 2;cvstuteurs'
</pre>
<p>
Vous voyez appara<72>tre quelques fichiers <code>.tml</code> dans votre
r<EFBFBD>pertoire de travail. Pour les transformer en <code>.html</code>,
faites<EFBFBD>:
</p>
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span><3E>~tuteurs/bin/rebuild .
</pre>
<h3>Contribuer au nouveau site</h3>
<p>Prenons un exemple. Supposons que vous souhaitiez <20>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 moficiation). Faites sans
danger<EFBFBD>:
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span><3E>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 <20> travailler sur ce nouveau fichier, faites<65>:<br />
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span><3E>cd unix
<span class="prompt">bireme ~/tuteurs/cvs/web $</span><3E>cvstuteurs add accents.tml
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span><3E>vim accents.tml
</pre>
La deuxi<78>me commande permet de dire <20> <code>cvs</code> que vous pr<70>parez
un fichier <code>unix/accents.tml</code>.<br />
Vous pouvez alors ins<6E>rer la d<>coration du fichier
<code>accents.tml</code> (<28> savoir l'ent<6E>te) en faisant
<code>:r<>../index.tml</code> par exemple. Activez le syntax-highlight
HTML, par exemple en relan<61>ant <code>vim</code>.
</li>
<li>
<EFBFBD>crivez le contenu de la page Web, c'est-<2D>-dire dans ce cas en mettant <20>
jour la page figurant sur l'ancien site et en le rendant conforme au
standard XHTML 1.0 Strict.
</li>
<li>
Lancez le script de conversion en <code>.html</code> en faisant
<code>:!<21>build<6C>accents.tml</code>.
Notez que si d'autres fichiers <code>tml</code> se trouvent dans le
r<EFBFBD>pertoire courant, leur syntaxe sera aussi v<>rifi<66>e (pour cr<63>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 <20>tre utile de
faire<EFBFBD>:
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span><3E>rebuild .
</pre>
</li>
<li>
Passer la page que vous venez de cr<63>er au <a
href="http://validator.w3.org/">validateur</a>. Pour cela, il peut <20>tre
pratique de faire un lien symbolique permettant d'acc<63>der par le Web <20>
votre r<>pertoire de travail<69>:<br />
<pre>
<span class="prompt">bireme ~/www</span><3E>ln -s ../tuteurs/cvs/web<65>tuteurs
</pre>
</li>
<li><a name="makeinstall"/>
Quand tout est au point, vous pouvez <20><>commiter<65><72> en faisant<6E>:
<pre>
<span class="prompt">bireme ~/tuteurs/cvs/web $</span><3E>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<6D>re ligne int<6E>ressante met <20> jour le repository compte tenu de
vos modifications et cr<63>ations. La deuxi<78>me met <20> jour met <20> jour entre
autres les fichiers <code>tml</code> de la page Web en fonction du
repository nouveau et la troisi<73>me ligne met <20> jour les fichiers
<code>html</code> et en cr<63>e <20>ventuellement de nouveaux.
</li>
<li>
Pendant l'<27>x<EFBFBD>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<66>rents r<>pertoires. Il est extr<74>mement important que ceux-ci
soient pr<70>cis et circonstanci<63>s, autant que possible. En clair, <20>viter de
mettre
<pre>Correction d'un probl<62>me important dans foobar.tml</pre>
</li>
</ol>
<h2>Quoi faire<72>?</h2>
<p>
Essentiellement, il s'agit de r<>cup<75>rer les pages de l'ancien site, de
les mettre <20> jour en les convertissant en XHTML 1.0 Strict.
</p>
<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.
</p>
<p>
Il est important que ces le fichier <code>00TODO</code> soit mis-<2D>-jour
assez r<>guli<6C>rement.
</p>
<p>Pour finir, voici quelques recommandations concernant la modification du
site Web.</p>
<div class="attention">
<h1>&icone.attention;<3B><a name="commandements">Les dix commandements de
cvstuteurs/web</a><3E>&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>
Du XHTML 1.0 Strict tu <20>criras et seulement quand tu auras pass<73> le
validateur HTML, tu commiteras.
</li>
<li>
Pour commiter, tu ne feras point <code>cvstuteurs commit</code>,
mais <code>make<6B>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<63>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<70>cis tu indiqueras lors d'un commit.
</li>
</ol>
</div>
<p><em>Je vous prie de bien vouloir excuser les anglicismes
scandaleusement pr<70>sents dans cette page.</em></p>
<div class="metainformation">
Auteur<75>: Jo<4A>l Riou. Derni<6E>re modification le 2002-11-11.
</div>
</body>
</html>