Ajout d'une petite documentation sur comment modifier le site
This commit is contained in:
jriou
parent
13dd20633f
commit
2fbfafdb08
1 changed files with 324 additions and 0 deletions
324
doc-interne.tml
Normal file
324
doc-interne.tml
Normal file
|
|
@ -0,0 +1,324 @@
|
||||||
|
<?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 doit subir un lifting.
|
||||||
|
Marie-Lan et Nicolas ont notamment choisi les couleurs et la présentation
|
||||||
|
du <a href="&url.tuteurs;">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>
|
||||||
|
|
||||||
|
<h3>Comment tout cela fonctionne ?</h3>
|
||||||
|
|
||||||
|
<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 (icones, screenshots,
|
||||||
|
illustrations du hublot, PostScripts gzippés d'icelui)
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Le site Web en lui-même se trouve à l'adresse <a
|
||||||
|
href="&url.tuteurs;"><code>http://www.eleves.ens.fr/tuteurs/web/</code></a>
|
||||||
|
temporairement. Quand il sera terminé, il reviendra à sa place, à savoir
|
||||||
|
<code>http://www.eleves.ens.fr/tuteurs/</code>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h4>Les fichiers <code>tml</code></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 éxé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 : faire 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>&url.tuteurs;</code>. Ainsi, dans
|
||||||
|
<code>logiciels/latex/astuces.tml</code>, on trouve le lien
|
||||||
|
suivant :</p>
|
||||||
|
|
||||||
|
<blockquote>
|
||||||
|
<p> Mais cela ne doit pas vous empêcher de prendre de <a
|
||||||
|
href="&url.tuteurs;docs/hublot/typo.html">bonnes habitudes</a> quand vous tapez avec d'autres logiciels ou que vous rédigez un courrier toutes les ponctuations sont suivies d'un espace, seules les ponctuations doubles sont précédées d'un espace.</p>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
|
||||||
|
<h4>Les fichiers <code>html</code></h4>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
<p>
|
||||||
|
En utilisant la suite spectrale de coniveau, on peut démontrer le
|
||||||
|
théorème [...].
|
||||||
|
</p>
|
||||||
|
</pre>
|
||||||
|
</li>
|
||||||
|
<li>On évite au maximum les retours à la ligne sauvages avec
|
||||||
|
<code><br></code>. D'ailleurs, ce genre de balises sont écrire
|
||||||
|
sous la forme <code><br /></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>
|
||||||
|
<img src="hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]">
|
||||||
|
</pre>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>Quand le repository du <code>cvstuteurs</code> est modifié (ou plutôt
|
||||||
|
quand on fait <a href="#makeinstall"><code>make install</code></a> dans
|
||||||
|
la racine de son répertoire de travail), 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 éxécute
|
||||||
|
<code>build</code> sur tous les fichiers <code>.tml</code> qui en ont
|
||||||
|
besoin.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<h3>Comment modifier le site ?</h3>
|
||||||
|
|
||||||
|
<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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h4>Se créer un répertoire de travail</h4>
|
||||||
|
|
||||||
|
<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 "Attention, tu utilises cvstuteurs";sleep 2;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>
|
||||||
|
|
||||||
|
<h4>Contribuer au nouveau site</h4>
|
||||||
|
|
||||||
|
<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 moficiation). 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œuvre avant de faire un commit (i.e. de prendre un 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 $</span> cvstuteurs add accents.tml
|
||||||
|
<span class="prompt">bireme ~/tuteurs/cvs/web/unix $</span> vim accents.tml
|
||||||
|
</pre>
|
||||||
|
La deuxième commande permet de dire à <code>cvs</code> que vous préparez
|
||||||
|
un fichier <code>unix/accents.tml</code>.<br />
|
||||||
|
|
||||||
|
Vous pouvez alors insérer la décoration du fichier
|
||||||
|
<code>accents.tml</code> (à savoir l'entête) en faisant
|
||||||
|
<code>:r ../index.tml</code> par exemple. Activez le syntax-highlight
|
||||||
|
HTML, par exemple en relançant <code>vim</code>.
|
||||||
|
</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>
|
||||||
|
Lancez le script de conversion en <code>.html</code> en faisant
|
||||||
|
<code>:! build accents.tml</code>.
|
||||||
|
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>
|
||||||
|
</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>
|
||||||
|
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
Du XHTML 1.0 Strict tu écriras et seulement quand tu auras passé le
|
||||||
|
validateur HTML, tu commiteras.
|
||||||
|
</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>
|
||||||
|
De jolies pages Web tu pourras apprécier.
|
||||||
|
</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. Dernière modification le 2002-11-11.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
Loading…
Reference in a new issue