Nomnoml : des diagrammes UML dessinés avec une syntaxe textuelle

• Outil permettant de rédiger des diagrammes UML comme du code : quand on modifie la syntaxe textuelle à gauche, le diagramme rendu change en même temps
• Prend en charge de nombreux éléments de diagramme et notations de relations, notamment classes, composants, organigrammes, cas d’utilisation, bases de données et tables
• Le contenu édité est enregistré dans le localStorage du navigateur et peut rester disponible lors de la visite suivante, mais cette sauvegarde n’est pas garantie
• Le canevas peut être déplacé et agrandi/réduit par glisser-déposer et défilement dans le tiers droit de l’écran, et l’éditeur prend en charge une partie des raccourcis clavier de Sublime Text
• Les directives # et les directives de style . permettent d’ajuster les polices, l’orientation, l’espacement, les couleurs, l’apparence des lignes et les styles de classificateurs personnalisés

---

Des diagrammes construits avec une syntaxe textuelle

• Nomnoml est un outil qui permet de créer et de rendre des diagrammes avec une syntaxe textuelle

• Notation des relations

  • Il est possible d’utiliser association, dependency, generalization, implementation, composition, aggregation, ball and socket, note, hidden, etc.
  • Exemple : [Car]->[Engine]
  • Exemple : [Car] +-> 0..* [RustPatch]
  • Exemple : [Car]o->[Manufacturer]
  • Exemple : [Car]<:-[Pickup]

• Classificateurs pris en charge

  • Les diagrammes de classes prennent en charge, en plus de la classe par défaut, abstract, instance, reference, package et frame
  • Dans les diagrammes de composants, les notations socket et lollipop peuvent être utilisées
  • Les éléments d’organigramme incluent start, end, state, choice, sync, input, sender, receiver et transceiver
  • Les diagrammes de cas d’utilisation prennent en charge actor et usecase
  • D’autres éléments peuvent être utilisés, comme note, label, hidden, database, pipe et table
    • Un exemple de table se présente sous la forme [<table>Fruits| Apples | 17 || Oranges | 4711]

Édition, directives et styles

• // en début de ligne est traité comme un commentaire
  • // au milieu d’une ligne, comme dans [not //commented], n’est pas un commentaire
• L’attribut id permet de créer deux nœuds distincts avec le même nom affiché
  • Exemple : [<actor id=a>User], [<actor id=b>User], [a] -- [b]

• Ajuster la mise en page et le rendu avec les directives #

  • #import: filename
  • #direction: down | right
  • #edges: hard | rounded
  • #background: transparent
  • #font, #fontSize, #spacing, #padding, #stroke, #fill, #zoom
  • #ranker: network-simplex | tight-tree | longest-path

• Définir des styles de classificateurs avec les directives .

  • Exemple : #.box: fill=#8f8 dashed
  • Exemple : #.blob: visual=ellipse title=bold
  • Des paires clé/valeur comme fill, stroke, align, direction et visual peuvent être utilisées
  • Il est possible de définir le style du titre et du corps du texte, par exemple title=left,italic,bold et body=center,italic,bold
  • Les exemples d’utilisation incluent le changement de police, une mise en page compacte, la création de tables, les styles personnalisés et la séparation en plusieurs fichiers
  • La séparation en plusieurs fichiers utilise une forme comme #import: blobby_styles
  • Les modifications dans l’écran d’édition sont enregistrées dans le localStorage du navigateur, et le canevas peut être déplacé et agrandi/réduit par glisser-déposer et défilement dans le tiers droit de l’écran
  • L’éditeur prend en charge une partie des raccourcis clavier de Sublime Text, et Nomnoml est hébergé sur GitHub

[GN⁺]

Avis sur Hacker News

• Lien GitHub : https://github.com/skanaar/nomnoml

• Au début, c’était assez déroutant, et je n’ai compris qu’après avoir trouvé le bouton about.
  Peut-être que j’ai eu la chance de vivre sans savoir reconnaître l’UML au premier coup d’œil. Au début, je pensais que ça expliquait une sorte de syntaxe bidon en parler de pirate.

  • On reconnaît l’UML au fait qu’il y a plein de styles de flèches dont personne ne se souvient. Je suis convaincu à environ 90 % que c’est la principale raison pour laquelle l’UML ne s’est jamais vraiment imposé.
    Je préfère largement cette approche, qui accepte que personne ne mémorise 10 types de flèches pour lire occasionnellement un diagramme UML : https://buck2.build/docs/concepts/concept_map/
  • À strictement parler, je ne pense pas que ce soit de l’UML standard.
    Cela dit, c’est le cas de pas mal d’outils qui utilisent le terme « UML », et dans la pratique on a souvent besoin de quelque chose de moins précis et moins verbeux que l’UML théorique.

• Il y avait autrefois un site open source qui comparait les outils de conversion « texte vers diagramme » : https://text-to-diagram.com/
  nomnoml n’y figure pas.

  • Ce site a été créé par les mainteneurs de D2, donc il peut y avoir un biais, mais je trouve quand même que la syntaxe de D2 est la plus accessible de cette famille, nomnoml compris.
    [1] : https://d2lang.com/

• J’aime bien Nomnoml. Dernièrement, je l’utilise dans un projet de gestion personnelle des connaissances (PKM) basé sur le navigateur sur lequel je travaille, pour visualiser une structure hiérarchique de tags.
  Les mises en page ressortent plutôt proprement. Exemple : https://imgbox.com/9A1mDyNv

• Le côté mobile semble avoir besoin d’un coup de propre. Je l’ai ouvert sur mon téléphone et le diagramme était dessiné par-dessus l’éditeur, ce qui rendait l’éditeur inutilisable.

  • Ce n’est que le comportement du site de démo de nomnoml. Il est conçu pour montrer que, quand on modifie le texte, le diagramme UML rendu change en temps réel.
    La bibliothèque JavaScript sous-jacente peut rendre directement vers un canvas HTML ou en SVG depuis un programme Node.js, et on peut aussi l’exécuter en ligne de commande si on le souhaite.

• Il y a quelque temps, j’ai construit quelques outils avec nomnoml, notamment des graphes de flot de contrôle et des graphes de dépendances pour du code assembleur GPU.
  J’ai vraiment adoré, mais j’ai regretté de ne pas avoir de moyen fiable de forcer certains éléments à être placés près les uns des autres. Sur de très grands diagrammes, il fait parfois de mauvais choix et ça devient brouillon.
  Même si la documentation n’est pas complète, le code est assez facile à modifier : j’ai pu le bricoler pour afficher des tooltips au survol et faire en sorte qu’un clic sur certaines boîtes mène à d’autres diagrammes. Je suis reconnaissant qu’un si bon outil soit open source.

• Obtenir une bonne mise en page dépend trop de l’ordre de définition. Pour de grands diagrammes, cela peut devenir difficile à résoudre pour l’utilisateur, mais sur de petits diagrammes ça paraît acceptable.
  Par exemple, si l’on écrit le même exemple de pirates dans un autre ordre, on obtient une mise en page valide mais peu agréable.

  • Le problème avec ce genre d’outils, c’est que même si l’on parvient d’une manière ou d’une autre à obtenir une bonne mise en page dans la documentation, il suffit d’ajouter, supprimer ou modifier quelque chose pour devoir tout reprendre.
    J’ai essayé plusieurs de ces produits de diagrammes pilotés par le code, en rêvant d’un monde où la documentation technique, diagrammes inclus, ferait partie du code source du projet ; mais il était difficile d’obtenir une mise en page acceptable, non seulement pour une diffusion externe, mais même en interne.
    Cette frustration mène généralement à deux mauvais résultats : soit les diagrammes deviennent illisibles, soit ils ne sont plus maintenus.
    Honnêtement, l’idée de relire la documentation en code review au moment du check-in relève presque du mythe. Les diffs de ce type de documentation sont très difficiles à comprendre, et il est quasiment impossible de vérifier de façon pertinente que le document est correct sans le rendre et regarder le résultat.
    C’est le genre de problème que j’aimerais vraiment voir résolu, et peut-être qu’un jour il le sera.
  • Correction : je pensais que la disposition se faisait de haut en bas, mais ce n’est pas le cas ; l’ordre est déterminé autrement.
    Si l’on compare le tableau Pirate d’origine avec celui du commentaire parent, le haut et le bas sont inversés. Même en définissant d’abord beard et parrot dans l’ordre d’affichage souhaité, le résultat reste inversé.
  • Il faudrait un autre outil qui optimise la permutation des phrases pour minimiser les chevauchements dans le diagramme final.
  • Cet exemple de pirates n’aide pas beaucoup à comprendre. Je me demande s’il existe une façon d’arranger ces mots en vrac pour qu’ils aient du sens.

• C’est joli, et ça a l’air bien mieux que les diagrammes de classes PlantUML.
  [0] : https://plantuml.com/class-diagram

  • C’est possible. Mais plutôt que de créer encore un standard fragmenté, je me demande s’il ne serait pas possible de rendre plus agréable le style par défaut d’un standard déjà assez bien pris en charge.
  • PlantUML prend en charge l’un des diagrammes que j’utilise le plus souvent, les diagrammes de séquence. Malheureusement, nomnoml ne les prend pas en charge.

• Ça me fait penser à graphviz.