JavaScool:DocumentsHml : Différence entre versions

De Sciencinfolycee
Aller à : navigation, rechercher
m (Interagir avec la plateforme Java's Cool au niveau de la documentation)
m
Ligne 4 : Ligne 4 :
 
Afin que la documentation des «proglets» soit homogène, facile à maintenir et surtout que le lecteur se retrouve d'une «proglet» à une autre, les pages sont écrites en utilisant un sous ensemble minimal d'HTML le [[JavaScool:DocFormatHml|format HML]] en syntaxe XML, en clair: un document[[#Structurer_le_texte_en_divisions.|structuré en division]], le texte étant [[#Enrichir_le_texte_en_modifiant_son_aspect.| enrichi pour qualifier son contenu]], tout en [[#Cr.C3.A9er_de_l.27.C2.ABhyper-texte.C2.BB_en_ajoutant_des_objets_et_des_liens.|intégrant des liens hyper-texte]].
 
Afin que la documentation des «proglets» soit homogène, facile à maintenir et surtout que le lecteur se retrouve d'une «proglet» à une autre, les pages sont écrites en utilisant un sous ensemble minimal d'HTML le [[JavaScool:DocFormatHml|format HML]] en syntaxe XML, en clair: un document[[#Structurer_le_texte_en_divisions.|structuré en division]], le texte étant [[#Enrichir_le_texte_en_modifiant_son_aspect.| enrichi pour qualifier son contenu]], tout en [[#Cr.C3.A9er_de_l.27.C2.ABhyper-texte.C2.BB_en_ajoutant_des_objets_et_des_liens.|intégrant des liens hyper-texte]].
  
Il est donc '''recommandé d'écrire ces documentations en XML en code source''' en utilisant les [[JavaScool:DocFormatHml|format HML]] détaillé ici.
+
Il est donc '''recommandé d'écrire ces documentations en XML en code source''' en utilisant les [[JavaScool:DocFormatHml|format HML]] détaillé ici. Ce sont des fichiers sources d'extension '''.xml''' qui sont traduits automatiquement en HTML dans des fichiers d'extension '''.htm'''.
  
 
== Structure d'une documentation de «proglet» ==  
 
== Structure d'une documentation de «proglet» ==  
Ligne 50 : Ligne 50 :
 
Il est évidemment préférable de scinder un grand document en plusieurs pages: afficher l'énoncé de l'exercice dans une page, la documentation de l'exemple dans une autre, un texte complémentaire dans un 3ème etc..
 
Il est évidemment préférable de scinder un grand document en plusieurs pages: afficher l'énoncé de l'exercice dans une page, la documentation de l'exemple dans une autre, un texte complémentaire dans un 3ème etc..
  
Dans ce cas on rédige plusieurs pages HML et on peut les lier par un lien de la forme
+
Dans ce cas on rédige plusieurs pages HML et on peut les lier par un lien de la forme:
 
<div class="code">
 
<div class="code">
 
<font color="#990000">'''&lt;l'''</font>
 
<font color="#990000">'''&lt;l'''</font>
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"new"</font><font color="#990000">''>'''</font>
+
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"newtab"</font><font color="#990000">''>'''</font>
 
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-2eme-document.'''htm'''"</font><font color="#990000">''>'''</font>
 
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-2eme-document.'''htm'''"</font><font color="#990000">''>'''</font>
 
<font color="#505000">text</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"description-du-lien"</font><font color="#990000">''>'''</font>
 
<font color="#505000">text</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"description-du-lien"</font><font color="#990000">''>'''</font>
Ligne 59 : Ligne 59 :
 
</div>
 
</div>
  
Bien noter que si le document  
+
Bien noter que si le document initial est d'extension '''.xml''' c'est bien le document traduit en HTML d'extension '''.html''' qu'il faut lier.
  
Pour aider à l'interaction avec l'apprenant
+
Sans le paramètre <tt>class="newtab"</tt> le 2eme document remplace le 1er.
    * D'ouvrir un fichier .jvs dans l'éditeur
 
    * D'ouvrir simultanément une page web dans le navigateur intégré de Java's Cool
 
  
Ceci permet par exemple d'afficher l'énoncé de l'exercice dans la page, ou encore la documentation de l'exemple. La page web doit être spécifiée au format .htm mais il est préférable de la rédiger en .xml
+
* Ouvrir un fichier source dans l'éditeur
 +
 
 +
Il est possible d'ouvrir un fichier dans l'éditeur pour permettre à l'éleve de travailler dessus en utilisant un lien de la forme:
 +
<font color="#990000">'''&lt;l'''</font>
 +
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"editor"</font><font color="#990000">''>'''</font>
 +
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-2eme-document.'''jvs'''"</font><font color="#990000">''>'''</font>
 +
<font color="#505000">text</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"description-du-lien"</font><font color="#990000">''>'''</font>
 +
<font color="#990000">'''&lt;/>'''</font>
 +
</div>
 +
 
 +
Bien noter que si le document est d'extension '''.jvs''' puisque c'est un document en Java simplifier comme utilisé sur la plateforme Java's Cool.

Version du 19 août 2011 à 23:07

Rédiger les documents des «proglets» en HTML minimal

Afin que la documentation des «proglets» soit homogène, facile à maintenir et surtout que le lecteur se retrouve d'une «proglet» à une autre, les pages sont écrites en utilisant un sous ensemble minimal d'HTML le format HML en syntaxe XML, en clair: un documentstructuré en division, le texte étant enrichi pour qualifier son contenu, tout en intégrant des liens hyper-texte.

Il est donc recommandé d'écrire ces documentations en XML en code source en utilisant les format HML détaillé ici. Ce sont des fichiers sources d'extension .xml qui sont traduits automatiquement en HTML dans des fichiers d'extension .htm.

Structure d'une documentation de «proglet»

Typiquement une documentation précise les objectifs de l'activité, donne des éléments introductifs pour faire connaître le contexte, rappeler les prérequis, puis propose un travail de programmation qui va permettre de vérifier que les concepts sont compris, les éléments complémentaires étant données en note à la fin du document.

Celà s'implémente à travers le squelette suivant:

<div title="La «proglet» @name">
  <div class="objectif">
  </div>
  <div class="intros">
    <div title="item 1">
    </div>
  etc..
  </div>
  <div class="works">
    <div title="item 1">
    </div>
  etc..
  </div>
  <div class="notes">
   <!-- référencées par des tags de la forme <l class="note" link="1"/> -->
    <div title="item 1">
    </div>
  etc..
  </div>
</div>

Apprendre par l'exemple: des bouts de codes à réutiliser

Pour permettre à l'apprenant d'obtenir rapidement un premier résultat à partir duquel il va réfléchir et aller plus loin, il est conseiller de proposer des bouts de codes exemples qui seront naturellement copiés/collés pour initier le travail.

La balise <code>permet de spécifier ces exemples qui seront présentés en couleur à l'utilisateur:
<code>
    void main() {
    }
</code>

Interagir avec la plateforme Java's Cool au niveau de la documentation

  • Ouvrir une 2ème page de documentation

Il est évidemment préférable de scinder un grand document en plusieurs pages: afficher l'énoncé de l'exercice dans une page, la documentation de l'exemple dans une autre, un texte complémentaire dans un 3ème etc..

Dans ce cas on rédige plusieurs pages HML et on peut les lier par un lien de la forme:

<l class'="newtab"> link'="nom-du-2eme-document.htm"> text'="description-du-lien"> </>

Bien noter que si le document initial est d'extension .xml c'est bien le document traduit en HTML d'extension .html qu'il faut lier.

Sans le paramètre class="newtab" le 2eme document remplace le 1er.

  • Ouvrir un fichier source dans l'éditeur

Il est possible d'ouvrir un fichier dans l'éditeur pour permettre à l'éleve de travailler dessus en utilisant un lien de la forme: <l class'="editor"> link'="nom-du-2eme-document.jvs"> text'="description-du-lien"> </>

Bien noter que si le document est d'extension .jvs puisque c'est un document en Java simplifier comme utilisé sur la plateforme Java's Cool.