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 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é.