tuteurs.ens.fr/doc-interne.tml

407 lines
13 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>
2002-11-16 19:28:04 +01:00
<h4>Th<54>oriquement</h4>
<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>
2002-11-16 19:28:04 +01:00
<h4>Concr<63>tement...</h4>
<p>Pour faire un fichier <code>page.tml</code>, r<>cup<75>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 informatiques de l'<27>cole
Normale sup<75>rieure. Le contenu de ce site est organis<69> en grands
th<EFBFBD>mes| :&lt;/p&gt;
</pre>
<p>
Le titre de la page (ici <20> Les tuteurs <20>) doit <20>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<EFBFBD>r<EFBFBD>e par les
scripts.
</p>
<p>
Le titre qui s'affiche en gros tout en haut de la page doit <20>tre indiqu<71>
avec une balise <code>&lt;h1&gt;</code>, les diff<66>rentes sections avec
<code>&lt;h2&gt;</code>, etc... Enfin, un paragraphe doit se trouver <20>
l'int<6E>rieur d'une balise <code>&lt;p&gt;</code>
</p>
<p>
Lorsque l'on <20>x<EFBFBD>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<EFBFBD>r<EFBFBD> <20> partir des
balises <code>&lt;h2&gt;</code> et <code>&lt;h3&gt;</code> se trouvant
dans le fichier <code>.tml</code>.
</p>
<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>
<li>
Toutes les balises doivent <20>tre mises en minuscules.
</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 "Non, tu ne veux pas utiliser cvs directement, utilise 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">
2002-11-16 19:28:04 +01:00
Auteur<75>: Jo<4A>l Riou. Derni<6E>re modification le 2002-11-16.
</div>
</body>
</html>