Début de doc pour modifier le site sous git.
This commit is contained in:
Marc Mezzarobba
parent
812a8b8436
commit
a89ea87c38
1 changed files with 109 additions and 116 deletions
225
doc-interne.tml
225
doc-interne.tml
|
|
@ -8,9 +8,20 @@
|
|||
</head>
|
||||
<body>
|
||||
|
||||
<h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu?</h1>
|
||||
<h1>Comment mettre à jour le site des tuteurs ou y ajouter du contenu?</h1>
|
||||
|
||||
<h3> Rajouter <code>~tuteurs/bin</code> dans votre <code>PATH</code></h3>
|
||||
<p> En bref : les pages HTML du site web des tuteurs sont produites
|
||||
à partir de fichiers dans un format XML maison appelé TML. Le
|
||||
répertoire <code>~tuteurs/bin</code> contient plusieurs commandes
|
||||
utiles pour travailler avec les fichiers TML.
|
||||
On ne travaille pas directement dans <code>~tuteurs/www</code> :
|
||||
tout le contenu du site est sous <a href="logiciels/git/">git</a>,
|
||||
et l'arborescence HTML est mise à jour automatiquement à chaque
|
||||
<code>push</code> (de la branche qui va bien) dans
|
||||
<code>~tuteurs/www.git</code>.
|
||||
</p>
|
||||
|
||||
<h2> Rajouter <code>~tuteurs/bin</code> dans votre <code>PATH</code></h2>
|
||||
|
||||
<p>
|
||||
La plupart des programmes utilisés dans la suite sont dans
|
||||
|
|
@ -32,121 +43,109 @@ $MISCPATH:\
|
|||
/users/staffs/tuteurs/bin
|
||||
</pre>
|
||||
|
||||
|
||||
<h3>Se créer un répertoire de travail</h3>
|
||||
<h2> Récupérer une copie de travail </h2>
|
||||
|
||||
<p>
|
||||
Tout d'abord, créez-vous un répertoire de travail sur votre compte avec
|
||||
<code>mkdir</code>. Par la suite, nous supposerons que ce répertoire
|
||||
s'appelle <code> tuteurs/cvs</code>.
|
||||
Le site web des
|
||||
<a href="logiciels/git/">git</a>. Je ne réexplique pas comment se
|
||||
servir de git ici, allez voir la page qu'on a déjà à ce sujet...
|
||||
</p>
|
||||
|
||||
<p>Tapez les commandes suivantes:
|
||||
<p>
|
||||
La première chose à faire pour modifier le site est donc de cloner le
|
||||
dépôt git. La meilleure façon est de commencer par mettre une clé ssh
|
||||
chez tuteurs (si on n'en a pas déjà) puis de faire
|
||||
</p>
|
||||
<pre>
|
||||
<span class="prompt"> teck ~/tuteurs/cvs $</span> cvstuteurs checkout web
|
||||
<span class="prompt"> teck ~/tuteurs/cvs $</span> cd web
|
||||
<span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .
|
||||
</pre>
|
||||
|
||||
<h3>Écrire une nouvelle page (ou la modifier)</h3>
|
||||
|
||||
<p>Prenons un exemple. Supposons que vous souhaitiez écrire la page
|
||||
<code>unix/accents.html</code>. Pour cela, il va falloir écrire
|
||||
un fichier <code>unix/accents.tml</code>.
|
||||
<pre><span class="prompt">$</span> git clone tuteurs@clipper:www.git </pre>
|
||||
<p class="continue">
|
||||
Cependant, depuis les machines de l'école, on peut aussi faire
|
||||
directement
|
||||
</p>
|
||||
<ol>
|
||||
<li>
|
||||
Commencez par synchroniser votre répertoire de travail avec le repository:
|
||||
<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> cvstuteurs update
|
||||
</pre>
|
||||
</li>
|
||||
<li>Pour commencer à travailler sur ce nouveau fichier, faites :
|
||||
<pre><span class="prompt">$</span> git clone ~tuteurs/www.git </pre>
|
||||
<p class="continue">
|
||||
sans clé ssh — du moins, il y a une magouille dans le Makefile qui
|
||||
essaie de faire en sorte que ça marche.
|
||||
</p>
|
||||
|
||||
<h2>Écrire une nouvelle page (ou la modifier)</h2>
|
||||
|
||||
<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> cd unix
|
||||
<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> tmltemplate accents.tml <em>"titre court"</em> <em>"titre long"</em>
|
||||
<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> cvstuteurs add accents.tml
|
||||
<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> emacs accents.tml
|
||||
</pre>
|
||||
<p>
|
||||
Supposons que vous souhaitiez créer ou modifier la page
|
||||
<code>unix/accents.html</code>. Pour cela, il va falloir écrire un
|
||||
fichier <code>unix/accents.tml</code>. </p>
|
||||
|
||||
Si vous voulez modifier un fichier existant, il ne faut pas taper les
|
||||
commandes du milieu.
|
||||
|
||||
Le <em>titre court</em> est celui qui apparaîtra dans l'arborescence du
|
||||
site à gauche des pages (choississez-le concis, car l'arbre de navigation
|
||||
est étroit), le <em>titre long</em> sera écrit en gros en
|
||||
haut de la page.
|
||||
|
||||
<p>Pour ajouter des fichiers binaires (par exemple des images), il faut
|
||||
taper :</p>
|
||||
<pre>
|
||||
<span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> <code>cvstuteurs add -kb foobar.png </code>
|
||||
</pre>
|
||||
</li>
|
||||
|
||||
<li>Écrivez le contenu du fichier. Ce dernier sera passé dans une moulinette
|
||||
qui s'appelle <code>xsltproc</code> 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:
|
||||
<!-- <blockquote><p> -->
|
||||
<pre>
|
||||
<a href="&url.tuteurs;docs/hublot/typo.html">
|
||||
</pre>
|
||||
<!-- </p></blockquote> -->
|
||||
|
||||
Il faut mettre à la fin du fichier des lignes du type:
|
||||
<pre>
|
||||
<div class="metainformation">
|
||||
<ul>
|
||||
<li>
|
||||
Commencez par synchroniser votre répertoire de travail avec le dépôt :
|
||||
<pre><span class="prompt">$</span> git pull</pre>
|
||||
</li>
|
||||
<li>
|
||||
Si <code>unix/accents.html</code> n'existe pas déjà, créez-le :
|
||||
<pre><span class="prompt">$</span> cd unix
|
||||
<span class="prompt">$</span> tmltemplate accents.tml <em>"titre court"</em> <em>"titre long"</em>
|
||||
<span class="prompt">$</span> emacs accents.tml</pre>
|
||||
Le <em>titre court</em> est celui qui apparaîtra dans l'arborescence du
|
||||
site à gauche des pages (choississez-le concis, car l'arbre de
|
||||
navigation est étroit), le <em>titre long</em> sera écrit en gros en
|
||||
haut de la page. Pour modifier un fichier existant, idem sauf le
|
||||
<code>tmltemplate</code>.
|
||||
</li>
|
||||
<li>
|
||||
Écrivez le contenu du fichier. Ce dernier sera passé dans une
|
||||
moulinette qui s'appelle <code>xsltproc</code> 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:
|
||||
<pre><a href="&url.tuteurs;docs/hublot/typo.html"></pre>
|
||||
Il faut mettre à la fin du fichier des lignes du type:
|
||||
<pre><div class="metainformation">
|
||||
Auteur : Comptes tuteurs.
|
||||
Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />.
|
||||
</div>
|
||||
</pre>
|
||||
|
||||
Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du
|
||||
<a href="&url.tuteurs;internet/web/html/">tutoriel XHTML</a> des
|
||||
tuteurs.
|
||||
</li>
|
||||
</div></pre>
|
||||
Pour le reste, c'est du XHTML 1.0 Strict. Vous pouvez vous aider du
|
||||
<a href="&url.tuteurs;internet/web/html/">tutoriel XHTML</a> des
|
||||
tuteurs.
|
||||
</li>
|
||||
|
||||
<li> Vérifiez votre page avec :
|
||||
<pre><span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> tmlcheck accents.tml
|
||||
</pre></li>
|
||||
<li> Vérifiez votre page avec :
|
||||
<pre><span class="prompt">$</span> tmlcheck accents.tml</pre>
|
||||
</li>
|
||||
|
||||
<li> Lancez le script de conversion en <code>.html</code> en faisant :
|
||||
<pre><span class="prompt"> teck ~/tuteurs/cvs/web/unix $</span> build accents.tml
|
||||
</pre> </li>
|
||||
<li>
|
||||
Lancez le script de conversion en <code>.html</code> en faisant :
|
||||
<pre><span class="prompt">$</span> build accents.tml</pre>
|
||||
Si vous avez fait beaucoup de modifications, il peut être utile de
|
||||
lancer
|
||||
<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> rebuild .</pre>
|
||||
à la racine de votre copie de travail.</li>
|
||||
|
||||
<li> Si vous avez fait beaucoup de modifications, il peut être utile de
|
||||
retourner dans le répertoire <code>web/</code> et de taper :
|
||||
<pre><span class="prompt"> teck ~/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>.
|
||||
</li>
|
||||
<li>
|
||||
Passez la page que vous venez de créer au <a
|
||||
href="http://validator.w3.org/">validateur</a>.
|
||||
</li>
|
||||
|
||||
<li><a name="makeinstall" id="makeinstall"></a>
|
||||
Quand tout est au point, vous pouvez « commiter » en faisant (depuis le
|
||||
répertoire <code>web/</code>) :
|
||||
<pre><span class="prompt"> teck ~/tuteurs/cvs/web $</span> make install
|
||||
</pre></li>
|
||||
<li id="makeinstall">
|
||||
Quand vous avez terminé une modification, vous pouvez « commiter »
|
||||
en faisant :
|
||||
<pre>
|
||||
<span class="prompt">$</span> git add accents.tml
|
||||
<span class="prompt">$</span> git commit
|
||||
</pre>
|
||||
Tâchez de mettre un commentaire explicite.
|
||||
</li>
|
||||
|
||||
<li>
|
||||
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
|
||||
<pre>Correction d'un problème important dans foobar.tml</pre></li>
|
||||
<li>
|
||||
Répétez ce qui précède autant de fois que nécessaire. À la fin,
|
||||
installez vos modifications sur le site web avec
|
||||
<pre><span class="prompt">$</span> make install</pre>
|
||||
(essentiellement équivalent à <code>git push</code>).
|
||||
</li>
|
||||
|
||||
<li>L'arborescence du site se trouve dans le fichier
|
||||
<code>00INDEX</code> et le fichier <code>00TODO</code> contient ce qui
|
||||
est en cours, avec diverses rubriques. Il est important que ces deux
|
||||
fichiers soient mis-à-jour.</li>
|
||||
</ul>
|
||||
|
||||
</ol>
|
||||
<h2> Astuces plus avancées </h2>
|
||||
|
||||
<h4>Ne pas publier une page tout de suite</h4>
|
||||
<h3>Ne pas publier une page tout de suite</h3>
|
||||
|
||||
<p>Vous pouvez décider de ne pas faire apparaître dans un
|
||||
premier temps vos nouvelles pages dans l'arbre de navigation qui se
|
||||
|
|
@ -165,35 +164,29 @@ interne aux tuteurs (et quelques autres) dans l'index, la racine du
|
|||
<code>CVS</code> contient :
|
||||
</p>
|
||||
|
||||
<pre><span class="prompt">clipper ~tuteurs/www $</span> cat nolinks
|
||||
<pre><span class="prompt">clipper ~tuteurs/www $</span> cat nolinks
|
||||
doc-interne
|
||||
aide
|
||||
404
|
||||
actualite
|
||||
plan_site
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
Les fichiers <code>nolinks</code> peuvent être écrits directement, sans
|
||||
passer par <code>CVS</code>. Comme cela, sur votre copie
|
||||
de travail, vous avez tous les liens.
|
||||
</p>
|
||||
|
||||
<p>Quand vos pages sont prêtes, procédez en plusieurs étapes pour faire
|
||||
disparaître le fichier <code>nolinks</code> :</p>
|
||||
<ul>
|
||||
<li>Éditez-le pour qu'íl devienne vide ;</li>
|
||||
<li>Regénérez les pages avec <code>rebuild</code> (ou <code>make
|
||||
install</code>) ;</li>
|
||||
<li>Effacez le fichier <code>nolinks</code>.</li>
|
||||
</ul>
|
||||
|
||||
<p> Vous trouverez des informations plus complètes sur la page de
|
||||
<a href="doc-interne-avancee.html">documentation interne avancée</a>.
|
||||
</p>
|
||||
<ul>
|
||||
<li>Éditez-le pour qu'íl devienne vide ;</li>
|
||||
<li>Regénérez les pages avec <code>rebuild</code> (ou <code>make
|
||||
install</code>) ;</li>
|
||||
<li>Effacez le fichier <code>nolinks</code>.</li>
|
||||
</ul>
|
||||
|
||||
<h3> Branches </h3>
|
||||
|
||||
|
||||
<div class="metainformation">
|
||||
Auteurs : Joël Riou, Nicolas George et Éric Levieil.
|
||||
Auteurs : Joël Riou, Nicolas George, Éric Levieil, Marc Mezzarobba.
|
||||
Dernière modification le <date value="$Date: 2008-10-05 11:20:36 $" />.
|
||||
</div>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue