Re : Et la documentation est de retour

Sorry tongue
J'ai mis dans dépannage smile - http://hoa-project.net/Forum/post/3066/#p3066

Dernière fois dit par Ecureuil Virtuel (08 Mar. 2011 16:49)

" L'imagination est plus importante que la connaissance. La connaissance est limitée alors que l'imagination englobe le monde entier, stimule le progrès, suscite l'évolution. " - Life in the cloud :: Getting Started with Hoa - Hoa débutant

62

Re : Et la documentation est de retour

Hey smile,

Je suis en train de brancher la documentation au site Web.
C'est intéressant car ça montre comment XYL peut être très utile ! Je vous fais des explications rapides.

J'ai un dépôt SCM (Mercurial) pour Hoa, un pour Literature (qui comprend le manuel d'apprentissage) et un pour le site Web. Le dépôt Literature est imbriqué dans celui du site Web.
On a cette architecture :

$ hoa tree . -d 3./
|-- Application/
|   |-- Controller/
|   |   |-- Default.php
|   |   |-- Literature.php
|   |   |-- Video.php
|   |-- External/
|   |   |-- Literature/
|   |-- Public/
|   |   |-- Css/
|   |   |-- Font/
|   |   |-- Forum/
|   |   |-- index.php
|   |   |-- Media/
|   |-- View/
|   |   |-- Error.xyl
|   |   |-- Literature/
|   |   |-- Main.xyl
|   |   |-- Video/
|   |   |-- Welcome.xyl

Vous noterez que l'on n'a pas de dossier Data, pas besoin pour l'instant. On trouve Application/External/Literature qui est notre dépôt imbriqué.

Au final, comment intégrer le manuel d'apprentissage ? Simplement en faisant :

<?xyl-use href="hoa://Application/External/Literature/Learn/Index.xyl"?>

dans Application/View/Literature/Learn.xyl, et le tour est joué. Au passage, les styles utilisés dans la documentation, s'ils existent dans mon application, seront utilisés, sinon leur utilisation sera ignorée (automatiquement). Les liens se réécrivent tout seul, les tables des matières et sommaires sont routés comme il faut, les liens également, tout est naturel.

Pourtant, on avait bien deux dépôts différents, deux « applications » différentes (c'était construit sans rapport), et voilà le résultat. Le tout se branche vraiment bien, je suis vraiment content.
Je vous avoue que c'est perturbant au début. Même moi j'hésite à faire des choses. C'est une manière complètement différente de voir son application et de la développer, surtout à cause de hoa:// et XYL. Mais au final, ça dépote méchament.

Bientôt donc, vous aurez la documentation sur le site. Les sources du site sont sur le dépôt, mais il n'est pas encore public (je dois cacher encore quelques mots de passes pour le forum).
Je prépare tout ça pour la beta2 qui devrait arriver cette semaine donc.

« Un handicap est le résultat d'une rencontre entre une déficience ou différence et une incapacité de la société à répondre à celle-ci. »

63

Re : Et la documentation est de retour

Je suis entrain de suivre le "tuto de démarrage" de Hoa et je remonte "à chaud" mon sentiment sur la partie Xyl. Tu introduits le concept de "Definition" au début de cette partie avant même que l'utilisateur voit l'output de son premier fichier Xyl, c'est assez déroutant à l'usage. A mon avis il faudrait introduire Xyl dans l'app (comme tu le fais au début du chapitre) puis proposer à l'utilisateur de voir le résultat (en ajoutant le render dans le contrôleur) et ensuite rajouter les notions de "Definition" théorique pour que l'utilisateur puisse les expérimenter directement sur son app ("visuellement" ai-je envie de dire).

Je n'arrive pas générer la doc en local, tout fonctionne mais mon fichier de sortie html contient :

Uncaught exception (Hoa\Xyl\Exception): Hoa\Xyl\Xyl::interprete(): (5) Cannot create the concrete tree because the root is unknown from the rank. in /Users/raphaelemourgeon/Sites/hoa/Central/Framework/Library/Xyl/Xyl.php at line 816.

J'ai aussi vu une ou deux petites fautes de français, je les remonte ici ou tu préfères un diff ?

Dernière fois dit par raphael (17 Apr. 2011 10:46)

64

Re : Et la documentation est de retour

Tu peux les remonter oui.

Pas bête pour l'introduction de XYL. Ça ne me plaisait pas non plus mais je ne savais pas comment m'en sortir. Je vais essayer ta proposition, elle me semble valable smile.

Pour le rendu de la documentation, j'ai changé le fonctionnement de XYL et je dois donc revoir aussi le xyl:render.

« Un handicap est le résultat d'une rencontre entre une déficience ou différence et une incapacité de la société à répondre à celle-ci. »

65

Re : Et la documentation est de retour

Alors voici un petit diff pour Learn.xyl :

diff -r c76f8bdcba69 Learn/Index.xyl
--- a/Learn/Index.xyl    Mon Mar 21 11:18:18 2011 +0100
+++ b/Learn/Index.xyl    Sun Apr 17 15:04:49 2011 +0200
@@ -175,7 +175,7 @@
         <blockcode language="php">require 'hoa://Data/Etc/Configuration/.Cache/HoaTest.php';</blockcode>
         <p>Il est bien évidemment possible, grâce au noyau, de créer vos
         propres liens sur le protocole.</p>
-        <p>Le noyau propose également un système d'événement natif à PHP. Il
+        <p>Le noyau propose également un système d'événements natif à PHP. Il
         est parfois très pratique d'utiliser ce paradigme. Cela permet une
         grande souplesse dans la façon dont les composants de notre programme
         peuvent communiquer entre eux. Ainsi, l'exemple suivant permet
@@ -413,7 +413,7 @@
         votre programme ;</item>
         <item><code>Etc</code>, les fichiers de configurations, les locales
         etc. ;</item>
-        <item><code>Lost+found</code>, les fichiers perdues (normalement,
+        <item><code>Lost+found</code>, les fichiers perdus (normalement,
         toujours vide) ;</item>
         <item><code>Module</code>, les bibliothèques utilisateurs réservées
         uniquement pour votre programme ;</item>
@@ -447,7 +447,7 @@
     <section3 id="Installer_Hoa" for="main-toc">
       <title>Installer Hoa</title>
 
-      <p>Il existe différente manière d'installer Hoa : soit à travers les
+      <p>Il existe différentes manières d'installer Hoa : soit à travers les
       archives, soit à travers
       <link href="http://mercurial.selenic.com/">Mercurial</link>. Ce dernier
       permet des mises à jour plus aisées, il est par conséquent conseillé.
@@ -549,7 +549,7 @@
     });</blockcode>
       <p>Tout d'abord, nous remarquons que la règle a été ajoutée avant la
       première car, de toute évidence, notre règle <code>g</code> est plus générique
-      et comprend tous les cas. L'ordre de déclarations des règles à un sens, il
+      et comprend tous les cas. L'ordre de déclarations des règles a un sens, il
       faut y prêter une attention toute particulière.</p>
       <p>Testons alors notre nouvelle application :</p>
       <blockcode language="shell">$ php index.php gordon
@@ -628,7 +628,7 @@
         d'exercice, à savoir visualiser simplement un site Web. Il va de soit
         que Bhoa est à but pédagogique uniquement, et pas à du déploiement réel.
         Pour l'utiliser, il suffit de le lancer de cette manière :</p>
-        <blockcode language="shell">$ myapp bhoa:start
+        <blockcode language="shell">$ myapp bhoa
 Server is up, on tcp://localhost:8888!
 Root: hoa://Application/Public/
 
@@ -650,7 +650,7 @@
         <p>Ou alors, si on utilise un serveur nginx, on pourra écrire dans les
         configurations :</p>
         <blockcode>if( !-e $request_filename ) {
-    
+
     rewrite ^(.*)$ index.php?$1 last;
     return  404;
 }</blockcode>
@@ -697,7 +697,7 @@
         on lui demande d'interpréter l'entrée comme de l'HTML.
         Les choses deviennent intéressantes. On va commencer par écrire notre
         fichier <code>hoa://Application/View/Main.xyl</code> qui sera notre vue
-        principale à laquelle va venir s'ajouter ou se greffer de nouvelles
+        principale à laquelle vont venir s'ajouter ou se greffer de nouvelles
         vues.</p>
         <p>Un fichier XYL peut-être de trois sortes : un document
         (<code>&amp;amp;lt;document&amp;amp;gt;</code>), des définitions
@@ -749,7 +749,7 @@
   &lt;/section1&gt;
 &lt;/document&gt;</blockcode>
         <p>Ainsi, le composant <code>&amp;amp;lt;page&amp;amp;gt;</code> sera
-        remplacer par sa définition décrite par <code>&amp;amp;lt;yield
+        remplacé par sa définition décrite par <code>&amp;amp;lt;yield
         name=page"&amp;amp;gt;</code>. Mais il est parfois préférable d'écrire
         les définitions de composants à l'extérieur de notre document (ce qui
         est très pratique pour obtenir des bibliothèques de composants). Une des
@@ -778,7 +778,7 @@
         dynamique. Cela implique que si on veut donner une autre définition à
         notre composant, on ne peut pas sauf en modifiant le document.
         C'est pourquoi, on est capable de spécifier à l'exécution quelle
-        définition utilisée. On le verra dans notre contrôleur. Pour l'instant,
+        définition utiliser. On le verra dans notre contrôleur. Pour l'instant,
         on va se contenter d'écrire deux définitions différentes de notre
         composant <code>&amp;amp;lt;page&amp;amp;gt;</code> : une pour notre
         règle de routeur <code>g</code> (« toutes les requêtes ») et une pour la
@@ -813,9 +813,9 @@
         utiles à notre application, comme la vue et ses données, le routeur ou
         encore le dispatcheur lui-même. Ainsi :</p>
         <blockcode language="php">&lt;?php
-        
+
 class IndexController {
-  
+
     public function IndexAction ( $all, Hoa\Controller\Application $_this ) {
 
         $_this->data->hello = 'Hello ' . $all . '!';
@@ -824,7 +824,7 @@
         $_this->view->addUse('hoa://Application/View/Index.xyl');
         $_this->view->render();
     }
-    
+
     …</blockcode>
         <p>On dit : on assigne deux données, <code>hello</code> et
         <code>intro</code>, on va utiliser dynamiquement les définitions
@@ -911,10 +911,10 @@
       <title>Conclusion</title>
 
       <p>Cette exercice n'était qu'une courte introduction à la prise en main de
-      Hoa. Dans les prochains chapitres, nous verrrons comment construire nos
+      Hoa. Dans les prochains chapitres, nous verrons comment construire nos
       propres bibliothèques ce qui nous permettra de passer en revue toutes les
       fonctionnalités du noyau : le fonctionnement des exceptions, des
-      événements, des importations etc. Puis, nous retournons sur une nouvelle
+      événements, des importations etc. Puis, nous retournerons sur une nouvelle
       application plus complète.</p>
     </section3>
   </section2>

Juste une petite remarque, l'utilisation de "utilisatrice ou utilisateur" un peu partout est assez lourd, il serait nettement plus agréable de fixer cette règle une fois pour toute en haut du doc et utiliser le masculin tout le long.

Le terme "contrôle des données" concernant le MVC peut prêter à confusion, je préfère la définition de l'intro Wikipedia "logique de contrôle, gestion des événements, synchronisation" qui me semble plus appropriée.

66

Re : Et la documentation est de retour

C'est noté wink. On va fixer cette règle. Je vais préciser au début qu'on utilisera utilisateur pour désigner autant les utilisatrices que les utilisateurs. En anglais, quand on ne connait pas le genre du lecteur, on met au féminin. En français, on applique quelle règle ?

Pour le MVC, je vais revoir la majeure partie de cette partie de toute façon. Elle ne me plaît décidémment pas.

Je vais appliquer ton patch … mais : tu veux passer commiteur peut-être ? Tu aurais les droits de lecture et d'écriture sur le dépôt Literature.

C'est bien tout ça. Ça me motive smile.

« Un handicap est le résultat d'une rencontre entre une déficience ou différence et une incapacité de la société à répondre à celle-ci. »

67

Re : Et la documentation est de retour

Hywan a écrit:

C'est noté . On va fixer cette règle. Je vais préciser au début qu'on utilisera utilisateur pour désigner autant les utilisatrices que les utilisateurs. En anglais, quand on ne connait pas le genre du lecteur, on met au féminin. En français, on applique quelle règle ?

En français on applique le masculin (la masculin l'emportant toujours sur le double genre).

Hywan a écrit:

Je vais appliquer ton patch … mais : tu veux passer commiteur peut-être ? Tu aurais les droits de lecture et d'écriture sur le dépôt Literature.

Oui je veux bien, je te laisse me mailer des identifiants. Ce serait cool de fixer xyl:render rapidement si c'est possible, ça me faciliterait la relecture (pour les accents notamment, je viens de voir qu'ils sont faux par endroit et que je n'ai pas fait attention !).

Hywan a écrit:

C'est bien tout ça. Ça me motive .

Me too, c'est ce que l'on appelle l'émulation non ? smile

Dernière fois dit par raphael (17 Apr. 2011 20:58)

68

Re : Et la documentation est de retour

Je te laisse plutôt toi m'envoyer tes identifiants wink. Tu connais mon mail. Le mot de passe doit être crypter en SHA1 :

$ htpasswd -sc bla raphael // or whatever
New password:
Re-type password:
$ cat bla
// je veux ça ;-).

Comme ça, je ne connaitrais pas ton mot de passe.

« Un handicap est le résultat d'une rencontre entre une déficience ou différence et une incapacité de la société à répondre à celle-ci. »

69

Re : Et la documentation est de retour

Bienvenu en tant que commiter sur le dépôt Literature de Hoa wink. Je te laisse appliquer ton patch !

« Un handicap est le résultat d'une rencontre entre une déficience ou différence et une incapacité de la société à répondre à celle-ci. »