# Doc. interne

# 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 :

- non seulement d'expliquer comment modifier le site;
- mais aussi de servir de fichier d'exemple pour l'élaboration des pages.

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 ?

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

### 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 suffit de taper 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. 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. É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. 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. 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. Corrigez les fautes de syntaxe.
7. Si vous avez fait beaucoup de modifications, il peut être utile de faire :

       bireme ~/tuteurs/cvs/web $ rebuild .

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. Un démon mensuel fait une liste des liens cassés sur le site, tenez-en compte.
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. 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

### 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` :

- Éditez-le pour qu'íl devienne vide ;
- Regénérez les pages avec `rebuild` (ou `make install`) ;
- 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.

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

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 .