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).
-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. -
- - 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.
-
tmlPour 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>
-
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.
-
À 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.
-
htmlLes 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 ?
--<p> -En utilisant la suite spectrale de coniveau, on peut démontrer le -théorème [...]. -</p> --
<br>. D'ailleurs, ce genre de balises sont écrites
-sous la forme <br /> pour se conformer à la première
-exigence ;
--<img src="docs/hublot/hublot01/logoAI.png" alt="[Logo de l'Atelier Internet]"/> --
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.
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.
-
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 .
-
-
-Prenons un exemple. Supposons que vous souhaitiez écrire la page
-unix/accents.html.
-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).
--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.
-
-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). .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).
-
-bireme ~/tuteurs/cvs/web $ rebuild .
-
-
-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.
-
-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.
-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-
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.
-
-Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
-disparaître le fichier nolinks :
-
rebuild (ou make
-install) ;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.
-
-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.
- -cvs mais cvstuteurs.
-~tuteurs/cvs/ et en particulier ~tuteurs/cvs/web/.
-~tuteurs/www/web/.
-cvstuteurs commit,
- mais make install dans la racine de ton répertoire de travail.
-cvstuteurs add -kb
-foobar.png
-.gif tu ne créeras point, parce que c'est mal.
-00TODO et 00INDEX.
-Je vous prie de bien vouloir excuser les anglicismes -scandaleusement présents dans cette page.
- - - - - diff --git a/doc-interne.tml b/doc-interne.tml index 1794201..be88c28 100644 --- a/doc-interne.tml +++ b/doc-interne.tml @@ -8,7 +8,7 @@ -Les pages HTML du site web des tuteurs sont produites à partir de @@ -62,12 +62,18 @@
On peut aussi (ce n'est guère utile qu'aux gens qui n'ont plus de
compte clipper) cloner le dépôt git sur le compte tuteurs
- lui-même, par exemple dans tmp/moi. Dans ce cas, il
- est important de veiller avant tout commit à régler les nom et
- adresse utilisés pour identifier l'auteur du commit :
+ lui-même, par exemple dans tmp/moi.
+ Dans ce cas, il est important de veiller avant tout commit à régler + les nom et adresse utilisés pour identifier l'auteur du + commit : +
$ export GIT_AUTHOR_NAME="Tartempion" $ export GIT_AUTHOR_EMAIL="tartempion@phare"+
Quand on travaille depuis son propre compte, les valeurs par défaut
@@ -134,28 +140,36 @@ $MISCPATH:\
$ emacs accents.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
+ navigation est étroit), le titre long apparaîtra en
haut de la page. Pour modifier un fichier existant, idem sauf le
tmltemplate.
xsltproc qui rajoute
- automatiquement un plan du site à gauche et un sommaire de la page
- en cours de lecture. Les liens internes au site des tuteurs
- ne doivent pas mentionner l'adresse de la racine du site. Il
- faut soit faire des liens relatifs, soit faire référence à la racine
- en utilisant l'entité &url.tututeurs;, ce qui donne
- des liens de la forme :
+ Écrivez le contenu du fichier. Ce dernier sera passé dans une
+ moulinette qui s'appelle xsltproc qui, entre autres
+ choses, ajoute automatiquement à la page un plan du site sur gauche
+ et un sommaire en début de page.
+ La moulinette TML et la feuille de style tuteurs.css
+ permettent de faire facilement des encadrés, de jolis prompts,
+ etc. : voyez les pages existantes pour des exemples, et la feuille
+ de style elle-même (voire la moulinette) pour tous les détails. Les
+ liens internes au site des tuteurs ne doivent pas mentionner
+ l'adresse de la racine du site. Il faut soit faire des liens
+ relatifs, soit faire référence à la racine en utilisant l'entité
+ &url.tututeurs;, ce qui donne des liens de 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. <date value="from git" />. </div>- Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du + Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du tutoriel XHTML des - tuteurs. + tuteurs. Rappelons juste que toutes les balises doivent être + refermées, que leurs noms s'écrivent en minuscules, et qu'il est de + mauvais goût d'aller à la ligne sauvagement avec +
<br>.