diff --git a/doc-interne-avancee.tml b/doc-interne-avancee.tml new file mode 100644 index 0000000..ed22b48 --- /dev/null +++ b/doc-interne-avancee.tml @@ -0,0 +1,539 @@ + + + + + Doc. interne avancée + + + +

Comment mettre à jour le site des tuteurs ou y ajouter du contenu

+ + +

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 nouveau site, et Nicolas a implémenté un +certain nombre de scripts (ceux-ci se trouvent dans la branche +utilitaires/tml du cvstuteurs).

+ +
+

&icone.attention; Attention &icone.attention;

+

+Ne pas modifier la branche utilitaires/tml du +cvstuteurs à moins de savoir vraiment ce que vous faites, +puisque tout le site Web en dépend.

+
+ +

+Cette page a pour but :

+ + +

+Un bref résumé des choses à ne pas faire se trouve dans les dix +commandements. +

+ +

Comment tout cela fonctionne ?

+ +

Tout est géré depuis l'arborescence web du +cvstuteurs. (NDjriou: l'ancien site est toujours dans +l'arborescence www dudit cvs)

+ +

+Dans ce cvs figurent uniquement des fichiers +.tml et des fichiers téléchargeables (icônes, screenshots, +illustrations du Hublot, PostScripts gzippés d'icelui) +

+ +

+Le site Web en lui-même se trouve à l'adresse http://www.tuteurs.ens.fr/. +Pour des raisons de compatibilité avec l'ancien site Web des tuteurs et +la phase transitoire, les adresses +http://www.eleves.ens.fr/tuteurs/ancien-site/ sont +redirigées vers http://www.tuteurs.ens.fr/ et les +noms sous lesquels les pages existaient avant sont redirigées vers leur +nouvelle position. +

+ +

Les fichiers tml

+ +

Théoriquement

+ +

Pour faire une nouvelle page Web, il faut écrire un fichier +foobar.tml. C'est presque du HTML, mais il y a quelques +nuances. En effet, ces fichiers sont passés dans une moulinette qui +s'appelle xsltproc quand vous exécutez la commande :

+
+bireme ~/tuteurs/cvs/web/docs/hublot $ ~tuteurs/bin/build hublot12.tml
+
+ +

Il en ressort normalement (s'il n'y a pas trop d'erreurs de syntaxe) un +fichier html très joli. Ce dernier utilise une feuille de +style tuteurs.css, 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.

+ +
+

Les scripts prennent en compte le titre des pages pour générer +l'arborescence. Il convient donc de les faire courts.

+
+ +

La moulinette et la feuille de style permettent de faire très simplement +beaucoup choses : des encadrés, des jolis prompts, des +tableaux...

+

+Par ailleurs, dans les fichiers .tml, 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 +&url.tuteurs;. Ainsi, dans +logiciels/latex/astuces.tml, on trouve le lien +suivant :

+ +
+

<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'une espace, +seules les ponctuations doubles sont précédées d'une espace.</p>

+
+ + +

Concrètement...

+ +

Pour faire un fichier page.tml, récupérez l'en-tête d'un +autre fichier .tml du site, et modifiez les titres: +

+
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html
+  PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
+  "tuteurs://DTD/tml.dtd">
+<html>
+  <head>
+    <title>Les tuteurs</title>
+  </head>
+  <body>
+
+    <h1>Le site des tuteurs</h1>
+
+    <p> 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| :</p>
+
+ +

+Il est également possible d'utiliser la commande tmltemplate + fichier.tml [titre] [titre long]. +

+ +

+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. +

+

+Le titre qui s'affiche en gros tout en haut de la page doit être indiqué +avec une balise <h1>, les différentes sections avec +<h2>, etc... Enfin, un paragraphe doit se trouver à +l'intérieur d'une balise <p>. +

+

+Lorsque l'on exécute le script build sur un fichier +.tml, le fichier .html produit contient un +sommaire en dessous du gros titre, celui-ci est généré à partir des +balises <h2> et <h3> se trouvant +dans le fichier .tml. +

+ +

Les dates de dernière modification

+ +

À 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 +obligatoirement (de toute façon, vous ne pourrez pas +faire autrement, hé, hé...) mettre à la fin des lignes du type: +

+
+<div class="metainformation">
+Auteur : Comptes tuteurs.
+Dernière modification le <date value="$Date$" />.
+</div>
+
+ +

Quand vous commiterez vos modifications avec CVS, +ce dernier modifiera votre fichier pour insérer la vraie date à côté de +$Date$. N'y touchez-plus, CVS et les +scripts de génération des fichiers html s'occupent de tout. +

+ +

Les fichiers html

+ +

Les scripts transforment les .tml en .html. Ces +derniers doivent être du XHTML 1.0 Strict. Pour le +vérifier, passez les pages que vous modifiez au validateur.

+ +

Quelles sont les différences entre le HTML usuel et le XHTML 1.0 +Strict ?

+ + +

Après que le repository du cvstuteurs est modifié +via la commande make +install dans la racine de son répertoire de travail (ou celui +d'un autre), les fichiers .tml figurant dans +~tuteurs/www/web sont mis à jour, et le script +rebuild est lancé dedans : ce script exécute +build sur tous les fichiers .tml qui en ont +besoin, ce qui permet de mettre à jour les fichiers .html du +site.

+ + +

Comment modifier le site ?

+ +

Comme le site est géré via cvs, 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 documentation sur CVS sur le +site des tuteurs. +

+ +

Se créer un répertoire de travail

+ +

Pour utiliser cvs, il faut se créer un répertoire de +travail chez soi, c'est-à-dire récupérer les fichiers se +trouvant dans le repository, à savoir +~tuteurs/cvs/web.

+ +

Pour cela, il faut utiliser la commande cvstuteurs, qui +se trouve dans le +répertoire /users/staffs/tuteurs/bin/. Pour plus de +simplicité, vous êtes invités à rajouter le +répertoire /users/staffs/tuteurs/bin/ dans votre PATH (vous +pouvez configurer celui-ci dans votre fichier .profile).

+ +

Vous pouvez donc maintenant utiliser le CVS des tuteurs en tapant la +commande suivante dans votre répertoire ~/tuteurs/cvs par +exemple :

+ +
+bireme ~/tuteurs/cvs $ cvstuteurs checkout web
+
+ +

Il est impératif d'utiliser cvstuteurs à la place de +cvs : ce permet de faire travailler cvs +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 +.zshrc :

+
+alias cvs='echo "Non, tu ne veux pas utiliser cvs directement, utilise cvstuteurs"'
+
+ +

+Vous voyez apparaître quelques fichiers .tml dans votre +répertoire de travail. Pour les transformer en .html, +faites : +

+
+bireme ~/tuteurs/cvs/web $ ~tuteurs/bin/rebuild .
+
+ +

Contribuer au nouveau site

+ +

Prenons un exemple. Supposons que vous souhaitiez écrire la page +unix/accents.html.

+ +
    +
  1. +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 : +
    +bireme ~/tuteurs/cvs/web $ cvstuteurs update
+
    +Il arrive souvent que cvs vous demande de faire cette +manœuvre avant de faire un commit (i.e. de prendre en compte vos +modifications). +
    2. + +
  2. Pour commencer à travailler sur ce nouveau fichier, faites :
    + +
    +bireme ~/tuteurs/cvs/web $ cd unix
+bireme ~/tuteurs/cvs/web/unix $ tmltemplate accents.tml "titre court" "titre long" 
+bireme ~/tuteurs/cvs/web/unix $ cvstuteurs add accents.tml
+bireme ~/tuteurs/cvs/web/unix $ vim accents.tml
+
    +La troisième commande permet de dire à cvs que vous préparez +un fichier unix/accents.tml, il faut que ce fichier existe +avant de lancer cette commande, c'est à cela que sert le script +tmltemplate. +Le titre court est celui qui apparaîtra dans l'arborescence du +site à gauche des pages, le titre long sera écrit en gros en +haut de la page. +
    3. + +
  3. +É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. +
    4. + +
  4. +Vérifiez votre page avec : +
    +bireme ~/tuteurs/cvs/web/unix $ tmlcheck accents.tml
+
    + + La commande tmlcheck 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 xmlbalance, qui indique +la position des balises incriminées (en caractères, utiliser +go avec Vim).
    5. + +
  5. +Lancez le script de conversion en .html en faisant : + +
    +bireme ~/tuteurs/cvs/web/unix $ build accents.tml
+
    + +Notez que si d'autres fichiers tml se trouvent dans le +répertoire courant, leur syntaxe sera aussi vérifiée (pour créer +l'arborescence dans accents.tml). +
    6. + +
  6. +Corrigez les fautes de syntaxe. +
    7. + +
  7. Si vous avez fait beaucoup de modifications, il peut être utile de +faire : +
    +bireme ~/tuteurs/cvs/web $ rebuild .
+
    +
    8. + +
  8. +Passer la page que vous venez de créer au validateur. Pour cela, il peut être +pratique de faire un lien symbolique permettant d'accéder par le Web à +votre répertoire de travail :
    +
    +bireme ~/www ln -s ../tuteurs/cvs/web tuteurs
+
    +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 .htaccess +adapté pour limiter l'accès à votre copie du site depuis l'extérieur. +
    9. + +
  9. +Un démon mensuel fait une liste des liens cassés sur le site, tenez-en +compte. +
    10. + +
  10. +Quand tout est au point, vous pouvez « commiter » en faisant : +
    +bireme ~/tuteurs/cvs/web $ make install
+
    + +Pour information, voici le contenu du Makefile +
    +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
+
    +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 tml de la page Web en fonction du +repository nouveau et la troisième ligne met à jour les fichiers +html et en crée éventuellement de nouveaux. +
    11. + +
  11. +Pendant l'exécution de cvstuteurs commit, on vous demande +d'indiquer des commentaires sur les manœ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 +
    Correction d'un problème important dans foobar.tml
    +
    12. +
+ +

Quelques astuces

+ +

Ne pas publier une page tout de suite

+ +

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. +

+ +

+Pour cela, le script de génération des pages regarde dans chaque +répertoire si un fichier nolinks 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 « fichier » ou encore +« répertoire/ ». Cela désactivera les liens éventuels vers +la page fichier.html ou vers l'index de +répertoire. +

+ +

+Par exemple, pour ne pas faire apparaître cette page de documentation +interne aux tuteurs (et quelques autres) dans l'index, la racine du +CVS contient : +

+
+clipper ~tuteurs/www $ cat nolinks
+doc-interne
+aide
+404
+actualite
+plan_site
+
+ +

+Un autre exemple : pendant le développement de la partie +logiciels/mozilla/ du site, le fichier +logiciels/nolinks contenait: +

+
+mozilla/
+
+ +

+On peut conseiller de ne pas rentrer ce fichier nolinks dans +CVS, mais seulement de le mettre au bon endroit à partir de +~tuteurs/www/, cela simplifie un peu les choses, et comme +cela, sur votre copie de travail, vous avez tous les liens. +

+ +
+

&icone.attention; Attention &icone.attention;

+

+Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire +disparaître le fichier nolinks : +

+ + +

En effet, si vous effacez directement le fichier nolinks, +a priori, le script de regénération ne refabriquera pas les +pages et les liens vers les nouvelles pages ne seront pas insérés. +

+
+ +

Quoi faire ?

+ +

+L'arborescence voulue du site se trouve dans le fichier +00INDEX et le fichier 00TODO contient ce qui +est en cours, avec diverses rubriques. Il est important que ces deux +fichiers soient mis-à-jour assez régulièrement. +

+ + +

Pour finir, voici quelques recommandations concernant la modification du +site Web.

+ +
+

&icone.attention; Les dix commandements de +cvstuteurs/web &icone.attention;

+
    +
  1. +Tu n'utiliseras pas cvs mais cvstuteurs. +
    2. +
  2. +Tu ne modifieras jamais directement ce qui se trouve dans +~tuteurs/cvs/ et en particulier ~tuteurs/cvs/web/. +
    3. +
  3. +Tu ne modifieras pas non plus directement ~tuteurs/www/web/. +
    4. +
  4. +Pour commiter, tu ne feras point cvstuteurs commit, + mais make install dans la racine de ton répertoire de travail. +
    5. +
  5. +Tu ajouteras des fichiers binaires en faisant cvstuteurs add -kb +foobar.png +
    6. +
  6. +De fichiers .gif tu ne créeras point, parce que c'est mal. +
    7. +
  7. +Tu liras et upgraderas 00TODO et 00INDEX. +
    8. +
  8. +Des liens relatifs tu utiliseras. +
    9. +
  9. +Des commentaires précis tu indiqueras lors d'un commit. +
    10. +
  10. +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. +
    11. +
+
+ +

Je vous prie de bien vouloir excuser les anglicismes +scandaleusement présents dans cette page.

+ +
+ Auteur : Joël Riou et Nicolas George. +Dernière modification le . +
+ + + diff --git a/doc-interne.tml b/doc-interne.tml index af647ae..9b43aa9 100644 --- a/doc-interne.tml +++ b/doc-interne.tml @@ -8,428 +8,155 @@ -

Comment mettre à jour le site des tuteurs ou y ajouter du contenu

+

Comment mettre à jour le site des tuteurs ou y ajouter du contenu?

- -

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 nouveau site, et Nicolas a implémenté un -certain nombre de scripts (ceux-ci se trouvent dans la branche -utilitaires/tml du cvstuteurs).

- -
-

&icone.attention; Attention &icone.attention;

-

-Ne pas modifier la branche utilitaires/tml du -cvstuteurs à moins de savoir vraiment ce que vous faites, -puisque tout le site Web en dépend.

-
+

Rajouter ~tuteurs/bin dans votre PATH

-Cette page a pour but :

- - -

-Un bref résumé des choses à ne pas faire se trouve dans les dix -commandements. +La plupart des programmes utilisés dans la suite sont dans +~tuteurs/bin. +Éditez le fichier .profile à la racine de votre compte, +trouvez le passage qui parle du PATH et modifiez la fin. +Attention, ne pas oublier de mettre :\ à la fin de l'avant-dernière ligne, +et de tester (en vous logguant une deuxième fois) avant de se délogguer.

-

Comment tout cela fonctionne ?

- -

Tout est géré depuis l'arborescence web du -cvstuteurs. (NDjriou: l'ancien site est toujours dans -l'arborescence www dudit cvs)

- -

-Dans ce cvs figurent uniquement des fichiers -.tml et des fichiers téléchargeables (icônes, screenshots, -illustrations du Hublot, PostScripts gzippés d'icelui) -

- -

-Le site Web en lui-même se trouve à l'adresse http://www.tuteurs.ens.fr/. -Pour des raisons de compatibilité avec l'ancien site Web des tuteurs et -la phase transitoire, les adresses -http://www.eleves.ens.fr/tuteurs/ancien-site/ sont -redirigées vers http://www.tuteurs.ens.fr/ et les -noms sous lesquels les pages existaient avant sont redirigées vers leur -nouvelle position. -

- -

Les fichiers tml

- -

Théoriquement

- -

Pour faire une nouvelle page Web, il faut écrire un fichier -foobar.tml. C'est presque du HTML, mais il y a quelques -nuances. En effet, ces fichiers sont passés dans une moulinette qui -s'appelle xsltproc quand vous exécutez la commande :

-bireme ~/tuteurs/cvs/web/docs/hublot $ ~tuteurs/bin/build hublot12.tml
+PATH=\
+$HOME/bin/$SYSTEMNAME:\
+$HOME/bin:\
+$UTILPATH:\
+$MAINPATH:\
+$GAMESPATH:\
+$MISCPATH:\
+/users/staffs/tuteurs/bin
-

Il en ressort normalement (s'il n'y a pas trop d'erreurs de syntaxe) un -fichier html très joli. Ce dernier utilise une feuille de -style tuteurs.css, 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.

-
-

Les scripts prennent en compte le titre des pages pour générer -l'arborescence. Il convient donc de les faire courts.

-
+

Se créer un répertoire de travail

-

La moulinette et la feuille de style permettent de faire très simplement -beaucoup choses : des encadrés, des jolis prompts, des -tableaux...

-Par ailleurs, dans les fichiers .tml, 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 -&url.tuteurs;. Ainsi, dans -logiciels/latex/astuces.tml, on trouve le lien -suivant :

- -
-

<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'une espace, -seules les ponctuations doubles sont précédées d'une espace.</p>

-
- - -

Concrètement...

- -

Pour faire un fichier page.tml, récupérez l'en-tête d'un -autre fichier .tml du site, et modifiez les titres: +Tout d'abord, créez-vous un répertoire de travail sur votre compte avec + mkdir . Par la suite, nous supposerons que ce répertoire +s'appelle tuteurs/cvs .

-
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE html
-  PUBLIC "-//ENS/Tuteurs//DTD TML 1//EN"
-  "tuteurs://DTD/tml.dtd">
-<html>
-  <head>
-    <title>Les tuteurs</title>
-  </head>
-  <body>
 
-    <h1>Le site des tuteurs</h1>
+
Tapez les commandes suivantes: 
+

+      
+ teck ~/tuteurs/cvs $ cvstuteurs checkout web
+ teck ~/tuteurs/cvs $ cd web
+ teck ~/tuteurs/cvs/web $ rebuild .
+

+  
+  
Écrire une nouvelle page (ou la modifier)

 
-    <p> 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| :</p>
+     
Prenons un exemple. Supposons que vous souhaitiez écrire la page
+unix/accents.html. Pour cela, il va falloir écrire
+un fichier unix/accents.tml.
+

+      
    
+        
  1. 
+Commencez par synchroniser votre répertoire de travail avec le repository:
+
     teck ~/tuteurscvs/web $ cvstuteurs update
+
    
+
    2. 
+        
  2. Pour commencer à travailler sur ce nouveau fichier, faites :
+
+
     teck ~/tuteurs/cvs/web $ cd unix
+ teck ~/tuteurs/cvs/web/unix $ tmltemplate accents.tml "titre court" "titre long" 
+ teck ~/tuteurs/cvs/web/unix $ cvstuteurs add accents.tml
+ teck ~/tuteurs/cvs/web/unix $ emacs accents.tml
 
    
 
-
    
-Il est également possible d'utiliser la commande tmltemplate
-  fichier.tml [titre] [titre long].
-
    
+Si vous voulez modifier un fichier existant, il ne faut pas taper les
+commandes du milieu.
 
-
    
-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.
-
    
-
    
-Le titre qui s'affiche en gros tout en haut de la page doit être indiqué
-avec une balise <h1>, les différentes sections avec
-<h2>, etc... Enfin, un paragraphe doit se trouver à
-l'intérieur d'une balise <p>.
-
    
-
    
-Lorsque l'on exécute le script build sur un fichier
-.tml, le fichier .html produit contient un
-sommaire en dessous du gros titre, celui-ci est généré à partir des
-balises <h2> et <h3> se trouvant
-dans le fichier .tml.
-
    
+Le titre court est celui qui apparaîtra dans l'arborescence du
+site à gauche des pages (choississez-le concis, car l'arbre de navigation
+est étroit), le titre long sera écrit en gros en 
+haut de la page.
 
-
    Les dates de dernière modification
    
+
    Pour ajouter des fichiers binaires, il faut taper cvstuteurs add -kb
+foobar.png .
    
+
    3. 
 
-
    À 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
-obligatoirement (de toute façon, vous ne pourrez pas
-faire autrement, hé, hé...) mettre à la fin des lignes du type:
-
    
-
    +
  3. Écrivez le contenu du fichier.  Ce dernier sera passé dans une moulinette
+qui s'appelle xsltproc qui rajoute automatiquement
+un plan du site à gauche et un sommaire de la page en cours de lecture.
+
+Les liens internes à la page des tuteurs doivent être sous la forme:
+      
    
+       < a href="&url.tuteurs;docs/hublot/typo.html">
+      
    
+
+Il faut mettre à la fin du fichier des lignes du type:
+      
     <div class="metainformation">
 Auteur : Comptes tuteurs.
-Dernière modification le <date value="$Date$" />.
+Dernière modification le <date value="$Date: 2007-07-05 12:51:51 $" />.
 </div>
 
    
-
-
    Quand vous commiterez vos modifications avec CVS, 
-ce dernier modifiera votre fichier pour insérer la vraie date à côté de
-$Date$. N'y touchez-plus, CVS et les
-scripts de génération des fichiers html s'occupent de tout.
-
    
-
-
    Les fichiers html
    
-
-
    Les scripts transforment les .tml en .html. Ces
-derniers doivent être du XHTML 1.0 Strict. Pour le
-vérifier, passez les pages que vous modifiez au validateur.
    
-
-
    Quelles sont les différences entre le HTML usuel et le XHTML 1.0
-Strict ?
    
-
      
-
    • Toutes les balises doivent être refermées. Ainsi,
-pour faire un paragraphe on fait 
-
      -<p>
-En utilisant la suite spectrale de coniveau, on peut démontrer le
-théorème [...].
-</p>
-
      
-
      • 
-
    • On évite au maximum les retours à la ligne sauvages avec
-<br>. D'ailleurs, ce genre de balises sont écrire
-sous la forme <br /> pour se conformer à la première
-exigence ;
-
      • 
-
    • 
-Tous les paramètres doivent être mis entre guillements et les images 
-doivent avoir un paramètre alternatif :
-
      -<img src="docs/hublot/hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]"/>
-
      
-
      • 
-
    • 
-Toutes les balises doivent être mises en minuscules.
-
      • 
-
    
-
-
    Après que le repository du cvstuteurs est modifié
-via la commande make
-install dans la racine de son répertoire de travail (ou celui
-d'un autre), les fichiers .tml figurant dans
-~tuteurs/www/web sont mis à jour, et le script
-rebuild est lancé dedans : ce script exécute
-build sur tous les fichiers .tml qui en ont
-besoin, ce qui permet de mettre à jour les fichiers .html du
-site.
    
-
-
-
    Comment modifier le site ?
    
-
-
    Comme le site est géré via cvs, 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 documentation sur CVS sur le
-site des tuteurs.
-
    
-
-
    Se créer un répertoire de travail
    
-
-
    Pour utiliser cvs, il faut se créer un répertoire de
-travail chez soi, c'est-à-dire récupérer les fichiers se
-trouvant dans le repository, à savoir
-~tuteurs/cvs/web. 
    
-
-
     Pour cela, il faut utiliser la commande cvstuteurs, qui
-se trouve dans le
-répertoire /users/staffs/tuteurs/bin/. Pour plus de
-simplicité, vous êtes invités à rajouter le
-répertoire /users/staffs/tuteurs/bin/ dans votre PATH (vous
-pouvez configurer celui-ci dans votre fichier .profile).
    
-
-
     Vous pouvez donc maintenant utiliser le CVS des tuteurs en tapant la
-commande suivante dans votre répertoire ~/tuteurs/cvs par
-exemple :
    
-
-
    -bireme ~/tuteurs/cvs $ cvstuteurs checkout web
-
    
-
-
    Il est impératif d'utiliser cvstuteurs à la place de
-cvs : ce permet de faire travailler cvs
-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
-.zshrc :
    
-
    -alias cvs='echo "Non, tu ne veux pas utiliser cvs directement, utilise cvstuteurs"'
-
    
-
-
    
-Vous voyez apparaître quelques fichiers .tml dans votre
-répertoire de travail. Pour les transformer en .html,
-faites :
-
    
-
    -bireme ~/tuteurs/cvs/web $ ~tuteurs/bin/rebuild .
-
    
-
-
    Contribuer au nouveau site
    
-
-
    Prenons un exemple. Supposons que vous souhaitiez écrire la page
-unix/accents.html.
    
-
-
      
-
    1. 
-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 :
-
      -bireme ~/tuteurs/cvs/web $ cvstuteurs update
-
      
-Il arrive souvent que cvs vous demande de faire cette
-manœuvre avant de faire un commit (i.e. de prendre en compte vos
-modifications).
+  
+Pour le reste, c'est du XHTML 1.0 Strict.   
 
      2. 
 
-
    2. Pour commencer à travailler sur ce nouveau fichier, faites :
      
+        
    3. Vérifiez votre page avec :
+
       teck ~/tuteurs/cvs/web/unix $ tmlcheck accents.tml
+
      4. 
 
-
      -bireme ~/tuteurs/cvs/web $ cd unix
-bireme ~/tuteurs/cvs/web/unix $ tmltemplate accents.tml "titre court" "titre long" 
-bireme ~/tuteurs/cvs/web/unix $ cvstuteurs add accents.tml
-bireme ~/tuteurs/cvs/web/unix $ vim accents.tml
-
      
-La troisième commande permet de dire à cvs que vous préparez
-un fichier unix/accents.tml, il faut que ce fichier existe
-avant de lancer cette commande, c'est à cela que sert le script
-tmltemplate.
-Le titre court est celui qui apparaîtra dans l'arborescence du
-site à gauche des pages, le titre long sera écrit en gros en 
-haut de la page.
+
    4. Lancez le script de conversion en .html en faisant :
+
       teck ~/tuteurs/cvs/web/unix $ build accents.tml
+
       
      5. 
+
+
    5. Si vous avez fait beaucoup de modifications, il peut être utile de faire :
+
       teck ~/tuteurs/cvs/web $ rebuild .
+
      6. 
+
+
    6. Passer la page que vous venez de créer au validateur. 
 
      7. 
-
-
    7. 
-É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.
-
      8. 
-
-
    8. 
-Vérifiez votre page avec :
-
      -bireme ~/tuteurs/cvs/web/unix $ tmlcheck accents.tml
-
      
-
- La commande tmlcheck 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 xmlbalance, qui indique
-la position des balises incriminées (en caractères, utiliser
-go avec Vim).  
      9. 
-
-
    9. 
-Lancez le script de conversion en .html en faisant :
-
-
      -bireme ~/tuteurs/cvs/web/unix $ build accents.tml
-
       
-
-Notez que si d'autres fichiers tml se trouvent dans le
-répertoire courant, leur syntaxe sera aussi vérifiée (pour créer
-l'arborescence dans accents.tml).
-
      10. 
-
-
    10. 
-Corrigez les fautes de syntaxe.
-
      11. 
-
-
    11. Si vous avez fait beaucoup de modifications, il peut être utile de
-faire :
-
      -bireme ~/tuteurs/cvs/web $ rebuild .
-
      
-
      12. 
-
-
    12. 
-Passer la page que vous venez de créer au validateur. Pour cela, il peut être
-pratique de faire un lien symbolique permettant d'accéder par le Web à
-votre répertoire de travail :
      
-
      -bireme ~/www ln -s ../tuteurs/cvs/web tuteurs
-
      
-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 .htaccess 
-adapté pour limiter l'accès à votre copie du site depuis l'extérieur.
-
      13. 
-
-
    13. 
-Un démon mensuel fait une liste des liens cassés sur le site, tenez-en
-compte.
-
      14. 
-
-
    14. 
+        
+
    15. 
 Quand tout est au point, vous pouvez « commiter » en faisant :
-
      -bireme ~/tuteurs/cvs/web $ make install
-
      
-
-Pour information, voici le contenu du Makefile
-
      -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
-
      
-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 tml de la page Web en fonction du
-repository nouveau et la troisième ligne met à jour les fichiers
-html et en crée éventuellement de nouveaux.
-
      16. 
-
+
       teck ~/tuteurs/cvs/web $ make install
+
      
+        
 
    16. 
-Pendant l'exécution de cvstuteurs commit, on vous demande
-d'indiquer des commentaires sur les manœuvres que vous avez faites
+On vous demandera
+d'indiquer des commentaires sur les manœ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
-
      Correction d'un problème important dans foobar.tml
      
-
      17. 
+
      Correction d'un problème important dans foobar.tml
      
+
+
    17. L'arborescence du site se trouve dans le fichier
+00INDEX et le fichier 00TODO contient ce qui
+est en cours, avec diverses rubriques. Il est important que ces deux
+fichiers soient mis-à-jour.
      18. 
+
 
    
 
-
    Quelques astuces
    
-
 
    Ne pas publier une page tout de suite
    
-
-
    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
+      
+
    Vous pouvez 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.
-
    
-
-
    
-Pour cela, le script de génération des pages regarde dans chaque
+trouve sur la gauche des pages.
    
+      
+
    Pour cela, le script de génération des pages regarde dans chaque
 répertoire si un fichier nolinks 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 « fichier » ou encore
 « répertoire/ ». Cela désactivera les liens éventuels vers
 la page fichier.html ou vers l'index de
-répertoire.
-
    
-
-
    
-Par exemple, pour ne pas faire apparaître cette page de documentation
+répertoire.
    
+      
+
    Par exemple, pour ne pas faire apparaître cette page de documentation
 interne aux tuteurs (et quelques autres) dans l'index, la racine du
 CVS contient :
 
    
-
    -clipper ~tuteurs/www $ cat nolinks
+
+      
    clipper ~tuteurs/www $ cat nolinks
 doc-interne
 aide
 404
@@ -438,102 +165,25 @@ plan_site
 
    
 
 
    
-Un autre exemple : pendant le développement de la partie
-logiciels/mozilla/ du site, le fichier
-logiciels/nolinks contenait:
+Les fichiers nolinks peuvent être écrits directement, sans
+passer par CVS.  Comme cela, sur votre copie
+de travail, vous avez tous les liens.
 
    
-
    -mozilla/
-
    
-
-
    
-On peut conseiller de ne pas rentrer ce fichier nolinks dans
-CVS, mais seulement de le mettre au bon endroit à partir de
-~tuteurs/www/, cela simplifie un peu les choses, et comme
-cela, sur votre copie de travail, vous avez tous les liens.
-
    
-
-
    
-
    &icone.attention; Attention &icone.attention;
    
-
    
-Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
-disparaître le fichier nolinks :
-
    
-
      
-
    • Éditez-le pour qu'íl devienne vide ;
      • 
-
    • Regénérez les pages avec rebuild (ou make
+        
+
      Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
+disparaître le fichier nolinks :
      
+        
        
+          
      • Éditez-le pour qu'íl devienne vide ;
        • 
+          
      • Regénérez les pages avec rebuild (ou make
 install) ;
        • 
-
      • Effacez le fichier nolinks.
        • 
-
      
+          
    • Effacez le fichier nolinks.
      • 
+        
    
+          
 
-
    En effet, si vous effacez directement le fichier nolinks,
-a priori, le script de regénération ne refabriquera pas les
-pages et les liens vers les nouvelles pages ne seront pas insérés.
-
    
+
    
+Auteurs : Joël Riou, Nicolas George et Éric Levieil.
+Dernière modification le .
 
    
 
-
    Quoi faire ?
    
-
-
    
-L'arborescence voulue du site se trouve dans le fichier
-00INDEX et le fichier 00TODO contient ce qui
-est en cours, avec diverses rubriques. Il est important que ces deux
-fichiers soient mis-à-jour assez régulièrement.
-
    
-
-
-
    Pour finir, voici quelques recommandations concernant la modification du
-site Web.
    
-
-
    
-
    &icone.attention; Les dix commandements de
-cvstuteurs/web &icone.attention;
    
-
      
-
    1. 
-Tu n'utiliseras pas cvs mais cvstuteurs.
-
      2. 
-
    2. 
-Tu ne modifieras jamais directement ce qui se trouve dans
-~tuteurs/cvs/ et en particulier ~tuteurs/cvs/web/.
-
      3. 
-
    3. 
-Tu ne modifieras pas non plus directement ~tuteurs/www/web/.
-
      4. 
-
    4. 
-Pour commiter, tu ne feras point cvstuteurs commit,
- mais make install dans la racine de ton répertoire de travail.
-
      5. 
-
    5. 
-Tu ajouteras des fichiers binaires en faisant cvstuteurs add -kb
-foobar.png
-
      6. 
-
    6. 
-De fichiers .gif tu ne créeras point, parce que c'est mal.
-
      7. 
-
    7. 
-Tu liras et upgraderas 00TODO et 00INDEX.
-
      8. 
-
    8. 
-Des liens relatifs tu utiliseras.
-
      9. 
-
    9. 
-Des commentaires précis tu indiqueras lors d'un commit.
-
      10. 
-
    10. 
-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.
-
      11. 
-
    
-
    
-
-
    Je vous prie de bien vouloir excuser les anglicismes
-scandaleusement présents dans cette page.
    
-
-    
    
-      Auteur : Joël Riou et Nicolas George. 
-Dernière modification le .
-    
    
-
-  
+