JavaScool:DocFormatHml

Documentation HML.: Introduction.

Pour bien comprendre la structure logique et les principes fondamentaux des langages HTML, le «sous-langage» HML proposé ici permet de spécifier de manière minimale une page HTML complète. Il est en fait très proche des derniers langages (XHTML ou HTML5).

Essentiellement une page «HML» est constitutée de méta-données puis du texte structuré en division, enrichit pour qualifier son aspect, intégrant des liens hyper-texte: ici seul le contenu compte, la mise en page et le rendu doit être spécifié ailleurs, dans les feuilles de style.

Décrire une page HML.

Un fichier HML contient une page qui va s'afficher dans un navigateur. Cette page doit contenir des méta-données permettant de prendre connaissance immédiatement de son contexte, et de la référencer ensuite. La construction est de la forme:

<page title = "value" .. (et autres méta-donnée) .. > .. (contenu de la page) .. </page>

les espaces et retour à la ligne n'étant pas significatifs. Les paramètres possibles sont:

name	type	default value
title	string	mandatory	Titre de la page.
icon	location	"null"	Icone permettant de reconnaitre la page.
author	identity	mandatory	Nom et email de l'auteur sous la forme Prenom Nom <email>.
tags	name*	mandatory	Liste de mots-clé de la page, séparés par des espaces, un mot composé étant construit avec le titre -.
style	location	"null"	Ficher de style CSS de la page.
script	location	"null"	Fichier des fonctions JavaScript de la page.
abstract	string	"null"	Description en quelques lignes du contenu de la page (utilisé par les moteurs d'indexation du web).
*	string	"null"	Autre(s) méta-donnée(s) éventuelle(s), à la discrétion de l'utilisateur.
Structure: "div*"			Cette construction contient une suite de division div.

Discussion.

Cette construction correspond à l'entête d'une page HTML (la construction ....). Elle force l'utilisateur à définir son identité (pas de page anonyme), un titre à la la page, et des mots-clé ou tag, de façon à ne pas générer de page sans aucun contexte permettant d'en comprendre la pertinence. Elle contraint les éléments de style et de script à être définis dans un unique fichier associé à la page (ce fichier pouvant lui-même en include d'autres), de façon à avoir une organisation de fichier bien organisée. L'encodage est forcément du UTF-8, le langage n'est pas spécifié en méta-donnée car le texte lui-même est potentiellement multilingue.

Structurer le texte en divisions.

Un texte est structuré de manière récursive en, par exemple, chapitre qui contiennent des sections, qui contiennent des paragraphes, etc. La construction est de la forme:

<div> title = "titre" .. (division) ..   '<div> .. (sous-division) ..    .. (etc.) ..   '</div> '</div>

comme un arbre dont la racine et la section globale du texte et les branches ses divisions et sous divisions jusqu'au feuilles qui sont des paragraphes du texte. Les paramètres possibles sont:

name	type	default value
title	string	"null"	Titre de la division.
id	name	"null"	Unique identificateur (étiquette) qui permet de référencer la division, chaque division doit avoir un identifiant différent.
class	name	"null"	Définit de quelle type de division il s'agit.
Structure: "(div|s|l|text())*" | | cette construction contient du texte avec des sous-division, des blocks de texte et des liens.

Le paramètre class prend, par exemple, une valeur correspondant:

class=ul	Liste d'items non-numérotés
class=ol	Liste d'items numérotés
class=table	Table avec des lignes et des collones
class=margin	Pour des notes en marge
class=center	Pour des informations centrales
class='*'	Autre type de structure, à la discrétion de l'utilisateur

qui correspondent à la façon dont le texte est structuré et à la façon dont le texte sera rendu sur la page.

A titre de raccourci les paragraphes peuvent s'appeler <p> au lieu de <div>, les deux noms étant complètement équivalent à ce niveau.

• Dans le cas d'une liste, les sous-divisions seront les items de la liste.
• Dans le cas d'une table, les sous-divisions seront les lignes de la table et leurs sous-divisions les cellules de la table (on les définit de gauche à droite puis de haut en bas).

La façon dont le texte sera rendu, le style est complètement séparé du contenu: on distingue complètement le fait d'écrire le texte de la façon de le mettre en page. Cette mise en page sera définie dans les fichier de style.

Discussion.

Cette construction correspond à tous les éléments HTML qui définissent des containers de texte. Elle force l'utilisateur à se concentrer sur le fond du contenu, pas sur sa forme. Le rendu peut en effet dépendre du support (grand écran, écran de balladeur, papier, ..). 

Enrichir le texte en modifiant son aspect.

Dans un éditeur on peut modifier l'aspect d'un morceau de texte en changeant sa couleur ou son style, etc. Cela permet de montrer que l'importance ou le sens de ce morceau de texte est différent du reste. Une telle construction est de la forme:

(texte ordinaire) ..{ s class="type-de-texte" .. (texte enrichi) .. } .. (suite du texte)

 où le texte enrichi est mis entre accolade en précisant la classe de texte en question. 

La syntaxe est:

name	type	default value
class	name	mandatory	Définit de quelle type de division il s'agit.
Structure: "(l|text())*" | cette construction contient du texte avec des blocks de texte et des liens.

Le paramètre class prend comme précédemment une valeur sémantique (qui décrit le sens que donne à cet enrichissement), indépendemment de la forme avec laquelle il sera redu. A titre de raccourci, les constructions suivantes sont définies:

<b>	(bold) Texte ou texte important à ne pas manquer lors de lecture rapide
<i>	(idiom) Mot ou texte utilisé dans un sens particulier ou d'une autre langue, dont le sens est à bien calculer
<c>	(code) Mot ou texte appartenant à un langage informatique ou formel
<S>	(sup) Mot ou texte en exposant (comme dans «x au carré» x{S 2}
<I>	(sub) Mot ou texte en indexe (inverse de l'exposant) pour décrire des objets paramétrés

cette liste n'étant pas limitative. Ces constructions sont des synonymes de <s class="bold", etc..

Discussion.

Cette construction correspond à l'élément HTML .. et à tous les éléments dérivés. L'introduction de raccourci allège la lecture et l'édition du texte source, que l'on veut rester lisible ici (contrairement au XML ou HTML qui sont supposés cachés à l'utilisateur). 

Créer de l'«hyper-texte» en ajoutant des objets et des liens.

Dans un texte il est possible de référencer d'autres textes, images ou animations. Soit on accède ces éléments soit en cliquant, soit ces éléments sont insérés dans le texte. La syntaxe de cette construction est:

{ l
name	type	default value
text	string	"null"	Texte décrivant le lien.
icon	location	"null"	Image décrivant ce lien.
link	location	"null"	Ressource décrite par ce lien.
class	name	"null"	Définit de quelle type de lien il s'agit.
no element
}

et cette construction ne contient rien. 

Le paramètre class prend comme précédemment une valeur sémantique, qui décrit en partculier si l'élément est inséré dans la page ou accessible par un clic. Il prend, par exemple, une valeur correspondant:

replace	Pour fermer cette page et ouvrir une autre page à la place.
include	Pour insérer le contenu d'un fichier Hml dans la présente page.
new	Pour s'ouvrir dans une autre fenêtre.
*	Pour un autre rendu, à définir par ailleurs.

. Une construction de la forme {l class="name} désigne une entité de nom name, c'est à dire un mot du texte qui sera rendu de manière particulière.

Discussion.

Cette construction correspond aux éléments HTML <a href="?page=api:/org/javascool/doc-files/..">. et <img src="/api//org/javascool/doc-files/..">. et à tous les éléments (tel que <object ...), qui incluent des contenus dans le texte. L'intégration des ces éléments étant considéré comme au-delà de la compétence d'un rédacteur de texte, la présente spécification se propose de les encapsuler, pour être utilisés sans ce donner la peine de les programmer.