JavaScool:DocumentsHml

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.