JavaScool:DocumentsHml : Différence entre versions

De Sciencinfolycee
Aller à : navigation, rechercher
m
m (Ouvrir une 2ème page de documentation)
 
(17 révisions intermédiaires par le même utilisateur non affichées)
Ligne 1 : Ligne 1 :
[[Catégorie:JavaScoolDev]]
+
[[Catégorie:JavaScoolDev]] __TOC__
 
 
 
<div class="label1">'''Rédiger les documents des «proglets» en HTML minimal'''</div>
 
<div class="label1">'''Rédiger les documents des «proglets» en HTML minimal'''</div>
  
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 [[JavaScool:DocFormatHml#Structurer_le_texte_en_divisions.|structuré en division]], le texte étant [[JavaScool:DocFormatHml#Enrichir_le_texte_en_modifiant_son_aspect.| enrichi pour qualifier son contenu]], tout en [[JavaScool:DocFormatHml#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 27 : Ligne 26 :
 
   </div>
 
   </div>
 
   <div class="notes">
 
   <div class="notes">
  <!-- référencées par des tags de la forme <l class="note" link="1"/> -->
 
 
     <div title="item 1">
 
     <div title="item 1">
 
     </div>
 
     </div>
Ligne 35 : Ligne 33 :
 
</pre>
 
</pre>
  
== Apprendre par l'exemple: des bouts de codes à réutiliser  ==  
+
=== Référencer les notes de bas de page ===
 +
 
 +
La section des notes, en fin de document numérote les notes de <tt>1, 2, ...</tt> et il est possible de les référencer dans le texte avec une construction de la forme:
 +
<div>
 +
<font color="#990000">'''&lt;l'''</font>
 +
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"note"</font>
 +
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"1, 2, .."</font>
 +
<font color="#990000">'''&lt;/>'''</font>
 +
</div>
 +
 
 +
=== Insérer une image ===
 +
 
 +
Une construction de la forme:
 +
<div>
 +
<font color="#990000">'''&lt;div'''</font>
 +
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"center"</font>
 +
<font color="#990000">'''>'''</font>
 +
<font color="#990000">'''&lt;l'''</font>
 +
<font color="#505000">icon</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-fichier-image"</font>
 +
<font color="#990000">'''/>'''</font>
 +
<font color="#990000">'''&lt;/div'''</font>
 +
</div>
 +
permet d'insérer une image dans le texte, en la centrant dans la page. Tous ces fichiers doivent être dans le répertoire de la proglet. On peut ajouter un lien avec l'attribut <font color="#505000">link</font>, un titre à l'image avec l'attribut <font color="#505000">text</font>, comme le permet le  [[JavaScool:DocFormatHml#Cr.C3.A9er_de_l.27.C2.ABhyper-texte.C2.BB_en_ajoutant_des_objets_et_des_liens.|format HML]].
 +
 
 +
== Insérer dans la documentation des morceaux 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.
+
Pour permettre à l'apprenant d'apprendre par l'exemple et 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 <tt>&lt;code></tt>permet de spécifier ces exemples qui seront présentés en couleur à l'utilisateur:
 
La balise <tt>&lt;code></tt>permet de spécifier ces exemples qui seront présentés en couleur à l'utilisateur:
Ligne 47 : Ligne 69 :
 
== Interagir  avec la plateforme Java's Cool au niveau de la documentation ==  
 
== Interagir  avec la plateforme Java's Cool au niveau de la documentation ==  
  
Pour aider à l'interaction avec l'apprenant
+
=== 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:
 +
<div class="code">
 +
<font color="#990000">'''&lt;l'''</font>
 +
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"newtab"</font>
 +
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-2eme-document.'''htm'''"</font>
 +
<font color="#505000">text</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"description-du-lien"</font>
 +
<font color="#990000">'''&lt;/>'''</font>
 +
</div>
 +
 
 +
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. Tous ces fichiers doivent être dans le répertoire de la proglet.
 +
 
 +
Attention: le nom du fichier (tutoriel.xml, exercice.xml, en_savoir_plus.xml, etc..) sera utilisé comme titre mais il ne ''doit pas'' contenir d'accents.
 +
 
 +
Sans le paramètre <tt>class="newtab"</tt> 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:
 +
<div>
 +
<font color="#990000">'''&lt;l'''</font>
 +
<font color="#505000">class</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"editor"</font>
 +
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-2eme-document.'''jvs'''"</font>
 +
<font color="#505000">text</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"description-du-lien"</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. Tous ces fichiers doivent être dans le répertoire de la proglet.
 +
 
 +
===Ouvrir des liens externes à Java's Cool===
 +
 
 +
Bien entendu il est possibles d'ouvrir tous les liens du Web avec une construction de la forme:
 +
<div>
 +
<font color="#990000">'''&lt;l'''</font>
 +
<font color="#505000">link</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"nom-du-2eme-document.'''jvs'''"</font>
 +
<font color="#505000">text</font><font color="#990000">'''<nowiki>=</nowiki>'''</font><font color="#008000">"description-du-lien"</font>
 +
<font color="#990000">'''&lt;/>'''</font>
 +
</div>
 +
dans c'est le navigateur du système de l'utilisateur qui sera sollicité.

Version actuelle datée du 29 août 2011 à 08:49

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 document structuré 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">
    <div title="item 1">
    </div>
  etc..
  </div>
</div>

Référencer les notes de bas de page

La section des notes, en fin de document numérote les notes de 1, 2, ... et il est possible de les référencer dans le texte avec une construction de la forme:

<l class="note" link="1, 2, .." </>

Insérer une image

Une construction de la forme:

<div class="center" > <l icon="nom-du-fichier-image" /> </div

permet d'insérer une image dans le texte, en la centrant dans la page. Tous ces fichiers doivent être dans le répertoire de la proglet. On peut ajouter un lien avec l'attribut link, un titre à l'image avec l'attribut text, comme le permet le format HML.

Insérer dans la documentation des morceaux de codes à réutiliser

Pour permettre à l'apprenant d'apprendre par l'exemple et 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. Tous ces fichiers doivent être dans le répertoire de la proglet.

Attention: le nom du fichier (tutoriel.xml, exercice.xml, en_savoir_plus.xml, etc..) sera utilisé comme titre mais il ne doit pas contenir d'accents.

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. Tous ces fichiers doivent être dans le répertoire de la proglet.

Ouvrir des liens externes à Java's Cool

Bien entendu il est possibles d'ouvrir tous les liens du Web avec une construction de la forme:

<l link="nom-du-2eme-document.jvs" text="description-du-lien" </>

dans c'est le navigateur du système de l'utilisateur qui sera sollicité.