From 8efb532022bd14c3bea8d7f88379a9b3d41c218a Mon Sep 17 00:00:00 2001 From: Marc Mezzarobba Date: Sun, 4 Oct 2009 18:30:54 +0200 Subject: [PATCH] Suppression de doc-interne-avancee.[h]tml... MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ...dont le contenu est très largement obsolète. Déplacement dans doc-interne des trucs importants qui n'y figuraient pas déjà. doc-interne-avancee redirige désormais sur doc-interne. --- .htaccess | 1 + doc-interne-avancee.tml | 544 ---------------------------------------- doc-interne.tml | 44 ++-- nolinks | 1 - 4 files changed, 30 insertions(+), 560 deletions(-) delete mode 100644 doc-interne-avancee.tml diff --git a/.htaccess b/.htaccess index 9fbe4a6..596ce57 100644 --- a/.htaccess +++ b/.htaccess @@ -142,3 +142,4 @@ RedirectPermanent /unix/shell.html http://www.tuteurs.ens.fr/unix/shell/ RedirectPermanent /jargon.html http://www.tuteurs.ens.fr/theorie/jargon.html RedirectPermanent /armoire.html http://www.tuteurs.ens.fr/ressources/armoire.html +RedirectPermanent /doc-interne-avancee.html http://www.tuteurs.ens.fr/doc-interne.html diff --git a/doc-interne-avancee.tml b/doc-interne-avancee.tml deleted file mode 100644 index faf7bf8..0000000 --- a/doc-interne-avancee.tml +++ /dev/null @@ -1,544 +0,0 @@ - - - - - Doc. interne avancée - - - -

Documentation interne avancée

- -
-Pour une première approche, consultez d'abord la page -de documentation interne sur la contribution -au site des tuteurs. -
- -

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

-
    -
  • É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 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. - -
- - - 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 @@ -

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

+

Mettre à jour le site des tuteurs ou y ajouter du contenu

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.

  • - É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 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>.
  • Sur clipper, ou si vous avez installé les outils nécessaires, diff --git a/nolinks b/nolinks index d856d3c..fbcfb40 100644 --- a/nolinks +++ b/nolinks @@ -1,5 +1,4 @@ doc-interne -doc-interne-avancee aide 404 actualite