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.

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'="new"> link'="nom-du-2eme-document.htm"> text'="description-du-lien"> </>

Bien noter que si le document

Pour aider à l'interaction avec l'apprenant

   * 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