Hamill

Ce document en français décrit le langage Hamill. English documentation is available here.

Hamill est un langage de balisage léger comme Markdown, Textile, AsciiDoc ou reStructuredText, pour écrire de la documentation dans un fichier texte avec des informations de structure (titres, divisions, paragraphes) et de formatages (gras, italique…).

Sa syntaxe légère rend plus facilement la lecture directe du fichier texte par rapport à un fichier HTML. Hamill fournit toutefois un outil pour transformer un fichier Hamill (extension .hml) en fichier HTML (extension .html)

Sa syntaxe est à la fois plus facile et plus complète que celle du Markdown originel de 2004.

Hamill existe depuis 2020, il est actuellement à sa version 2 depuis 2022 et dispose de deux implémentations qui produisent le même résultat :

Le code source du projet est disponible sur GitHub.

Vous pouvez l'essayer directement en ligne

La version actuelle est la version 2.0.5. Hamill est publié sous licence MIT.

Damien Gouteux 2020-2024

Sommaire

Utilisation

Hamill vient la sous la forme de deux scripts : hamill et weyland (extension .mjs pour la version JavaScript et .py pour la version Python). Weyland s'occupe de l'analyse lexicale et syntaxique des différents langages, et Hamill de la transformation du fichier Hamill (extension .hml) en un document composé de plusieurs nœuds. Ce document est ensuite traduit en HTML. Pour cela, il faut utiliser Hamill en ligne de commande :

node.exe hamill.mjs
python.exe hamill.py

Par défaut, il affichera le menu d'aide qui détaille les différentes commandes disponibles.

Running Hamill v2.0.5
---
> Use hamill.mjs --process (or -p) <input config filepath> to convert the HML file to HTML
  The file must be an object {} with a key named targets with an array value of pairs :
            ["inputFile", "outputDir"]
> Use hamill.mjs --tests (or -t) to launch all the tests (99).
> Use hamill.mjs --eval (or -e) to run a read-eval-print-loop from hml to html
> Use hamill.mjs --help (or -h) to display this message

Le fichier de configuration est un fichier JSON qui a un objet pour racine. Cet objet doit avoir une clé targets qui est une liste de paires, le premier élément indiquant le fichier hamill cible, le second élément indiquant le répertoire où mettre le résultat de la transformation en HTML. Le résultat portera le même nom de fichier que le fichier hamill cible, sauf que son extension sera .html au lien de .hml. Si le premier élément est la chaîne "comment", cette paire sera ignorée.

{
    "targets": [
        [
            "comment",
            "Pages racines"
        ],
        [
            "./input/index.hml",
            "../"
        ]
    ]
}

Commentaires, HR et BR

On peut faire des commentaires en mettant !rem ou §§ en début de ligne, toute la ligne est alors en commentaire.

!rem Ceci est un commentaire
§§ Ceci est un autre commentaire

Une ligne entièrement en commentaire sera exportée en l'HTML si la variable EXPORT_COMMENT est à true.

On peut faire une ligne horizontale avec une ligne constituée uniquement de - d'une longueur supérieure ou égale à 3.

---

On peut forcer un retour à la ligne avec ## entouré d'un espace avant et après et pas en début de ligne (sinon c'est un titre) :

ceci est un retour ## à la ligne.

ceci est un retour
à la ligne.

Titres

On met en début de ligne un nombre de # correspondant au niveau du titre que l'on veut.

### Titre de niveau 3

Modification de texte

Div, p et span

!css span.spoiler {background: black; user-select: none;}
!css span.spoiler:active {background: lightgrey; user-select: none;}
Ceci est un texte avec une partie cachée : {{.spoiler Dark Vador est le père de Luke}}. Pour ne pas spoiler.

Ceci est un texte avec une partie cachée : Dark Vador est le père de Luke. Pour ne pas spoiler.

Détails

<<Courte note -> Ceci est une courte note.>>
Courte noteCeci est une courte note.
<<Longue>>
* Ceci est une note longue
* Avec du Hamill dedans ##
<<end>>
Longue note
  • Ceci est une note longue
  • Avec du Hamill dedans

Code

On utilise @@pour du code inline@@. Hamill dispose d'un colorisateur syntaxique pour Python et JSON, on précise ainsi : @@python def function(par1, par2)@@.

Pour un bloc de code, il y a deux solutions :

On peut faire une ligne avec seulement @@ suivi éventuellement du langage qu'on souhaite puis des lignes avec @@ au début jusqu'à une ligne ne comportant que @@. Ainsi :

@@python
@@# Ceci est un commentaire
@@def function(par1, par2):
@@ return "Ceci est une fonction"
@@

Donnera :

# Ceci est un commentaire
def function(par1, par2):
    return "Ceci est une fonction"

On peut également faire une ligne avec seulement @@@ suivi éventuellement du langage qu'on souhaite puis des lignes sans rien jusqu'à une ligne ne comportant que @@@. Ainsi :

@@@python
# Ceci est un commentaire
def function(par1, par2):
return "Ceci est une fonction"
@@@

Donnera :

# Ceci est un commentaire
def function(par1, par2):
    return "Ceci est une fonction"

Listes

  1. + pour une liste numérotée, item 1/2
  2. + item 2/2
  1. - pour une liste numérotée inversée, item 1/2
  2. - item 2/2

Listes de définition

$ Cuirassier
    soldat à cheval lourdement équipé
Cuirassier
soldat à cheval lourdement équipé

Tables

Ceciestun tableau
Il estbeaumon tableau

On peut mettre bien sûr des modificateurs de textes, des liens ou une image dans un tableau.

Ceci estun tableau
Il est beau différentce tableau.

On peut également centré une case en faisant suivre la colonne ouvrante par = et d'aligner à droite avec > :

A gauche et aussi très long Centré A droite
A droite Centré A gauche et aussi très long

On peut également préciser un colspan avec #cVALEUR# par exemple : #c3# et combiner avec centrer =#c3# :

Colonne 1Colonne 2Colonne 3
Centré et colspan=3

LIMITATION : pas de listes dans un tableau

Liens

Images

Constantes

On peut définir des constantes en mettant !const en début de ligne. Les constantes peuvent être définies n'importe où dans le document mais une seule fois.

Certaines constantes sont prédéclarées mais sans valeur, on peut donc les définir une fois encore :

Certaines constantes sont prédéclarées avec une valeur, on ne peut donc pas les redéfinir :

Pour l'affichage du jour dans la semaine, seuls l'anglais et le français sont gérés en fonction de la constante LANG.

Variables

On peut définir des variables en mettant !var en début de ligne. On peut changer la valeur d'une variable en la redéfinissant dans le document autant de fois que l'on veut.

Si NEXT_TAB_CLASS et DEFAULT_TAB_CLASS sont définies, c'est la valeur de NEXT_TAB_CLASS qui sera prise en compte.

Inclusion de fichier HTML

On peut inclure un fichier HTML avec !include en début de ligne. Le contenu du fichier sera copié directement le document produit.

Liens vers un fichier CSS ou JavaScript

On peut lier notre document à fichier CSS ou JavaScript avec la commande !require en début de ligne.

Le lien vers un fichier CSS (.css) requis est automatiquement placé dans la tête du document HTML.

Le lien vers un fichier JavaScript (.js ou .mjs) requis est automatiquement placé dans la tête du document HTML.

Spécial