quickDoc : An ergonomic lightweight markup language with mnemonic inspirations for writing all kind of documents.

quickDoc An ergonomic lightweight markup language with mnemonic inspirations for writing all kind of documents Cyprien PIERRE 2025-10-24 Résumé Rédiger le résumé Mots-clés : Mot clé 1, Mot clé 2 1 Introduction Le présent document définit quickDoc, un nouveau langage de balisage léger conçu pour remplacer l’écosystème vieillissant T E X/L A T E X/BibLaTeX et les formats markdown actuels. quickDoc vise à unifier les avantages de ces systèmes tout en répondant à leurs limitations techniques, sémantiques et ergonomiques. Il est destiné à la rédaction de documents scientifiques, littéraires, de documentation technique et de publications, avec des sorties PDF et HTML5 conformes aux normes d’accessibilité WCAG niveau AAA. quickDoc permet de stocker et d’exprimer : — du contenu textuel formaté (sections, emphase, tableaux, etc.), — des données structurées (métadonnées, configurations, tables de données typées), — du code exécutable intégré (avec affichage du résultat dans le document), — des formules mathématiques (évaluables ou non par un moteur de calcul), — des références bibliographiques standard (interopérant avec CSL/BibTeX), — des figures, diagrammes, graphiques et annotations avec leur sémantique. Ce document est rédigé sous la forme d’une spécification normative de type ISO/RFC. Il énonce la terminologie, le modèle formel (syntaxe et grammaire), les exigences fonctionnelles et nonfonctionnelles, et les règles d’accessibilité et d’interopérabilité du langage quickDoc. Les mots ”doit” et ”ne doit pas” indiquent des exigences obligatoires, tandis que ”devrait” indique une recommandation. 1 2 Etat de l’art Laproductiondedocumentsformatéssuitdeuxapproches dominantes.Lapremièrereposesur des traitements de texte WYSIWYG comme MS Word, Google Docs ou OnlyOffice, qui exposent graphiquement les opérations de mise en forme mais atteignent vite leurs limites pour des documents exécutables, c’est-à-dire des textes où des éléments sont évalués puis remplacés parleursrésultats, commedu codegénérantun schéma ouundiagramme a [1,2,3].La seconde approche consiste à écrire le contenu et son balisage dans un éditeur texte (Neovim, Emacs, iA Writer, etc.) puis à confier le rendu à un outillage adapté, ce qui place un langage de balisage au cœur du flux de rédaction, avec des convertisseurs assurant la transformation vers HTML, PDF ou EPUB [4,5]. Dans ce cadre, on distingue des langages formels orientés structure et diffusion comme T E X ou HTML, et des langages de balisage léger (Lightweight Markup Language (LML)) tels que Markdown, Org-mode, AsciiDoc ou reStructuredText, préférés pour leur lisibilité en clair et leur intégration dans les pratiques «docs-as-code» [6,7,8,9]. T E X s’impose historiquement pour la composition de haute qualité via des macros qui soustendent L A T E X, ConTeXt, Texinfo et OpTeX, avec un écosystème de packages couvrant figures, bibliographies et disciplines spécialisées, mais au prix d’une infrastructure lourde, de choix techniques nombreux et de diagnostics d’erreurs difficiles sur de longs documents [10,11,12]. Des assistants comme LTeX+ et Writefull améliorent la qualité rédactionnelle et la conformité, sans toutefois résoudre les contraintes structurelles de la toolchain [13,14]. La question de l’accessibilitédemeure critique :laproductiondePDF balisésetconformes auxexigencesWCAG reste incertaine sans post-traitements spécifiques, en particulier pour les mathématiques, ce qui rend nécessaire l’intégration en amont de métadonnées et structures adaptées pour des sorties réellement utilisables par les technologies d’assistance [15,16,17,18]. Des systèmes récents cherchent à moderniser l’expérience de composition en combinant syntaxe compacte, prévisualisation rapide, contrôle programmatique de la mise en forme et messages d’erreur explicites, illustrant une direction de conception dont quickDoc peut s’inspirer pour viser une réactivité proche du temps réel tout en évitant les multiples passes et l’opacité des chaînes T E X traditionnelles [10,12]. D’autres approches, comme Scribble dans l’écosystème Racket, montrent l’intérêt d’une documentation programmable où le document est un programme générant du contenu, ce qui offre une extensibilité considérable mais reste fortement couplé à l’environnement hôte et peu accessible hors de celui-ci ; l’objectif pour quickDoc est de conserver l’extensibilité sans imposer la lourdeur d’un langage généraliste aux usages courants [16]. Côté LML, Markdown demeure le plus populaire grâce à une syntaxe minimale et lisible, mais son périmètre limité a provoqué la prolifération de dialectes hétérogènes selon les plateformes, malgré les efforts de normalisation de CommonMark et la documentation de variantes comme GFMetle registreIANA ;cettediversitéimposeauxauteursd’apprendredes sous-ensemblesdistincts et nuit à la portabilité inter-outils [6,19,20,21]. Org-mode, très intégré à Emacs, apporte une puissance sémantique et outillée supérieure pour la planification, les tableaux, l’exécution de code avec résultats reproductibles et l’export multi-formats, mais sa dépendance à Emacs limite sa portabilité et son adoption hors de cet environnement [7]. AsciiDoc, aujourd’hui sous a .Document exécutable : Désigne un document dont des éléments sont exécutés (p. ex. code) et remplacés par le produit de l’exécution (p. ex. schéma ou diagrammes). 2 / 30 gouvernance Eclipse, propose une couverture quasi exhaustive des besoins de documentation avec admonitions, inclusions, variables et macros, soutenue par une spécification et un TCK en cours de formalisation, ce qui en fait un choix robuste pour la documentation logicielle et les manuels, au prix d’une courbe d’apprentissage plus exigeante que Markdown [8,22,23, 24]. reStructuredText, conçu pour l’écosystème Python et Sphinx, offre des directives extensibles, des références croisées et des structures de haut niveau comparables à AsciiDoc, mais sa verbosité et ses conventions strictes le réservent souvent à son toolchain d’origine [9]. 3 Limites et opportunités L’émergence d’un besoin unifié naît des limites techniques, sémantiques et ergonomiques observées dans les systèmes existants et des exigences nouvelles liées aux flux «spec-driven » exploités avec des LLM, qui exigent des spécifications stables, testables et outillées dès le dépôt Git [25,26,27,28]. Depuis la création de Markdown, les LML se sont diffusés dans les dépôts, wikis, chaînes de documentation et blogs avec la promesse d’un texte lisible et convertible, mais la prolifération de variantes incompatibles et l’absence initiale de norme robuste ont généré des ambiguïtés et des coûts de portabilité entre outils [6,19,20,21]. Les utilisateurs pointent l’insuffisance des fonctionnalités natives pour les tableaux complexes, les références croisées et l’inclusion de fichiers, qui forcent à mélanger HTML et extensions, tandis que des alternatives plus riches comme AsciiDoc, reStructuredText et Org-mode demeurent surtout adoptées par des communautés spécialisées [7,8,9,22]. Les critiques récurrentes s’articulent autour de la non-standardisation de Markdown et de ses dialectes, qui obligent à composer avec plusieurs moteurs de rendu et alourdissent la charge cognitive, alors que des efforts de normalisation et de test ont montré leur efficacité quand ils sont accompagnés d’une spécification et d’un TCK publics [6,20,23,29]. Le manque de fonctions intégrées pour les notes, les références, les inclusions et les tableaux conduit à des pipelines hétérogènes, tandis que des langages orientés publication apportent admonitions, variables, macros et inclusions, au prix d’une syntaxe plus dense et d’outils dédiés (Asciidoctor, Antora, Sphinx, Emacs) [8,9,24,30]. La courbe d’apprentissage reste paradoxale : Markdown est privilégié pour sa lisibilité sur de petits documents, mais AsciiDoc et reST abaissent l’effort cognitif sur de larges corpus grâce à des structures et blocs dédiés [9,22,27]. Les points positifs et attentes se concentrent sur la lisibilité en clair, l’adoption large et la portabilité multiformat, mais les utilisateurs veulent une combinaison de simplicité Markdown etderichessed’AsciiDoc/reST, notammentadmonitions,tableaux,variables, macrosetsystème d’inclusion, intégrés sans HTML brut [8,22,24,31]. L’extensibilité pensée pour la publication et la conversion vers HTML, EPUB, PDF ou DocBook est appréciée, surtout quand elle s’adosse à un convertisseur pivot documenté et scriptable [4,5,9]. La lisibilité en texte brut reste un critère central pour la collaboration, la relecture et l’onboarding de contributeurs hétérogènes [6,8]. Lesrecommandationsquiendécoulentconvergentversunnoyausyntaxiqueminimalcomplété par des modules optionnels pour monter en puissance, afin de préserver la simplicité tout en couvrant admonitions, références croisées, imports, variables et macros, avec une syntaxe concise et uniforme pour tableaux, listes et blocs dédiés [9,22,24,31]. L’architecture devrait 3 / 30 être modulaire via plugins et blocs personnalisés, garantir des conversions fidèles vers HTML, PDF et EPUB, harmoniser la syntaxe des liens et employer des marqueurs explicites pour les opérations ambiguës, tout en conservant la lisibilité en clair [4,6,20]. La discipline de standardisation, soutenue par tests d’acceptation et TCK en intégration continue, est identifiée comme levier majeur pour limiter la dérive des variantes et sécuriser l’écosystème outillé, y compris dans des flux spec-driven avec LLM [23,25,29]. Les choix utilisateurs reflètent un arbitrage coûts-bénéfices entre «simplicité et adoption» et «puissance et structure» : Markdown est choisi par défaut pour sa popularité et ses intégrations plateformes, alors qu’AsciiDoc est mobilisé pour les manuels et publications structurées malgré l’installation d’outils spécifiques ; la décision dépend de la courbe d’apprentissage, de la prévisualisation, de la portabilité, de la compatibilité avec les workflows et de la collaboration [8,26,27]. Ce constat alimente un paradoxe : le langage le plus populaire n’est pas le mieux adapté à la documentation technique avancée, les freins à l’adoption de langages plus robustes étant surtout organisationnels et cognitifs, d’où l’intérêt d’un noyau minimal modulaire et d’une normalisation explicite des extensions [6,9,20]. Sur le plan cognitif, des marqueurs visibles et des structures uniformes réduisent la charge mentale et facilitent l’adoption, tandis que les admonitions et blocs dédiés améliorent la signalétiquedel’informationcritique ;desmécanismesdeportabilitételsquevariables,macros et includes simplifient la maintenance et la réutilisation à l’échelle des dépôts [4,8,24]. La recherchefuturedevraitanalyserdescorpuspluslargesetdespratiquesd’entreprisesen«docsas-code», quantifier la charge cognitive selon les LML chez novices et experts, et mesurer l’effet de la standardisation sur l’efficacité d’équipe et la qualité documentaire [26,32,33]. Les limites techniques et fonctionnelles appellent une spécification unique et stable qui empêche la dérive dialectale en définissant rigoureusement chaque fonctionnalité et en associant un banc de tests public, à l’image des démarches CommonMark, GFM et AsciiDoc-Lang [6,20, 23]. Les chaînes T E X/L A T E X souffrent de compilations multi-passes coûteuses sur gros documents, et un LML moderne devrait viser une compilation efficace et incrémentale avec des diagnostics clairs, dans un esprit de réactivité proche des pipelines continus observés dans les toolchains contemporaines [10,11,12]. L’accessibilité reste insuffisante par défaut : produire des sorties conformes WCAG et PDF/UA demande aujourd’hui des interventions spécifiques, d’où la nécessité d’intégrer nativement un balisage, des structures et des métadonnées A11Y-compatibles de bout en bout [15,16,18]. Le support de domaines comme mathématiques, chimie ou musique doit équilibrer expressivité et simplicité ; une intégration propre des formules, bibliographies et figures, avec éventuelle délégation calculatoire contrôlée, évite la dépendance à des modules externes ad hoc [34,35,36]. Enfin, un LML fondé sur une grammaire formelle déclarative et un Abstract Syntaxe Tree (AST) intermédiaire facilite parseurs robustes, linting, conversions et validations, comme l’illustrent les travaux sur grammaires formelles et MCSG pour langages «next-gen» [29,37,38]. Les limites sémantiques découlent du mélange fréquent entre présentation et contenu en L A T E X et du sous-balisage sémantique en Markdown ; un LML devrait proposer des rôles et styles nommés pour annoter code, noms propres, termes de glossaire, équations et objets multimédias, ce qui est cohérent avec les exigences d’accessibilité et de restitution assistée [9,16,24]. Les structures de haut niveau (figures avec légende et texte alternatif, tableaux titrés, références croisées d’objets numérotés) doivent exister dans un modèle unifié, au-delà des directives 4 / 30 propres à chaque outil [8,9]. Un mécanisme normé de métadonnées et de données embarquées, compatible avec les front-matter usuels et exportable en JSON, favorise interopérabilité et réutilisation [4,5]. La possibilité de marquer des expressions comme calculables, ou d’introduire des champs interactifs, ouvre la voie à des documents actifs côté HTML tout en restant statiques côté archivage [34,36]. Les limites ergonomiques plaident pour éviter la « soupe syntaxique» et imposent une seule forme par intention, une syntaxe auto-explicite et lisible en clair, sans dépendance à un environnement spécialisé, tout en offrant des éditeurs enrichis facultatifs et des messages d’erreur précis [7,17,38]. Des diagnostics au moment de la rédaction, une documentation normative accompagnée de tutoriels et d’exemples, et des validateurs intégrés à l’outillage CI renforcent l’adoption et la qualité globale [4,6,23]. En synthèse, ces constats justifient la création de quickDoc : un langage à noyau minimal, modulaire, formellement spécifié et testé, lisible en clair, extensible par profils contrôlés, couvrant nativement les blocs structurants, l’accessibilité, la sémantique et la portabilité multiformat, et aligné avec des workflows spec-driven compatibles LLM [6,16,23,24,25]. 4 Exigences du langage Sur la base des analyses précédentes, le présent chapitre formalise les exigences du langage quickDoc. Chaque exigence ( REQ.NN ) exprime un objectif général et chaque spécification ( SPEC.NN.MM ) détaille les conditions de satisfaction correspondantes. Les tests et règles associées seront dérivés de ces spécifications. 4.1 Fonctionnalités fondamentales REQ.01 quickDoc doit offrir un ensemble complet de mises en forme textuelles dans une syntaxe unifiée et non ambiguë. SPEC.01.01 Les éléments de mise en forme comprennent au minimum : titres hiérarchiques, emphases, gras, italique, souligné, barré, exposant, indice, surlignage et commentaires invisibles. SPEC.01.02 Une seule syntaxe doit exister pour chaque opération donnée afin d’éviter la multiplicité de notations observée dans Markdown et ses variantes [6,20,21]. SPEC.01.03 Les marqueurs doivent être explicites, lisibles et cohérents sur l’ensemble du langage afin de limiter la charge cognitive de l’utilisateur [22,38]. REQ.02 quickDoc doit intégrer les éléments structurés nécessaires à la production de documents techniques, scientifiques et éditoriaux. SPEC.02.01 Figures et images doivent pouvoir être insérées avec légende, texte alternatif et ancrage logique dans la structure du document. SPEC.02.02 Les tableaux doivent comporter titre, légende, en-têtes explicites et être navigables par les technologies d’assistance [9]. SPEC.02.03 Notes de bas de page et remarques en marge doivent être gérées nativement, avec possibilité de placement configurable. 5 / 30 SPEC.02.04 Citations bibliographiques et références croisées internes (sections, figures, équations, listings) doivent être automatiques et maintenues à jour lors de la compilation. SPEC.02.05 Les admonitions (avertissements, exemples, remarques) doivent être intégrées dans le cœur du langage [24]. REQ.03 quickDoc doit permettre l’inclusion et la gestion de données structurées à l’intérieur d’un document. SPEC.03.01 Les métadonnées documentaires (titre, auteur, date, licence, résumé, motsclés) doivent être exprimées dans un bloc standard de type front-matter. SPEC.03.02 Les données applicatives (tableaux, variables, paramètres) doivent être déclarables, accessibles et réutilisables dans le corps du document [4]. SPEC.03.03 L’export JSON ou YAML des métadonnées et des structures de document doit être garanti pour interopérabilité avec d’autres systèmes (par ex. doc-as-code, pipelines CI/CD). REQ.04 quickDoc doit permettre la production de documents reproductibles intégrant code et résultats. SPEC.04.01 L’inclusion de blocs de code (Python, R, Julia, Bash, etc.) doit être possible avec syntaxe claire. SPEC.04.02 Un paramètre doit définir si ces blocs sont exécutés ou non lors de la compilation. SPEC.04.03 Les résultats d’exécution doivent être automatiquement insérés au bon emplacement (texte, tableau, graphique). SPEC.04.04 Le comportement doit être aligné avec les principes du literate programming et des workflows reproductibles [1,2]. REQ.05 quickDoc doit gérer nativement les expressions mathématiques et leur évaluation. SPEC.05.01 Les formules doivent être exprimées dans une syntaxe textuelle claire, compatible avec L A T EX ou AsciiMath. SPEC.05.02 Certaines formules peuvent être marquées comme « calculables» et évaluées via un solveur symbolique externe (CAS). SPEC.05.03 Les graphiques ou courbes issus d’une formule doivent pouvoir être insérés automatiquement. SPEC.05.04 Les résultats numériques doivent être formatés selon les règles de locale et de typographie scientifique [35,36]. REQ.06 quickDoc doit intégrer une gestion bibliographique standardisée. SPEC.06.01 Le système de citation doit être compatible avec CSL-JSON, BibTeX et BibLaTeX. SPEC.06.02 Le style bibliographique doit être sélectionnable parmi la collection CSL existante. SPEC.06.03 Lesbibliographies doiventêtregénérées automatiquement etréactualisées à la compilation [4,33]. REQ.07 quickDoc doit disposer d’un mécanisme d’extension contrôlé. SPEC.07.01 L’utilisateur peut définir des macros nommées pour automatiser motifs et constructions récurrentes. SPEC.07.02 Les macros ne doivent pas altérer la grammaire de base ni rompre la compatibilité inter-documents. 6 / 30 SPEC.07.03 Le système d’extension doit être auditable et documenté (manifestes, dépendances, versionnage) [23,25]. 4.2 Structure, sémantique et modélisation REQ.08 quickDoc doit disposer d’une grammaire formelle publiée et stable. SPEC.08.01 La syntaxe doit être décrite en EBNF et les structures de données documentées via schémas JSON. SPEC.08.02 Tout changement de version doit maintenir la rétrocompatibilité ou fournir un mécanisme de migration automatique [29,37]. SPEC.08.03 Un AST (Abstract Syntax Tree) formel doit être défini pour permettre les transformations, linting et conversions vers d’autres formats [38]. REQ.09 quickDoc doit permettre une annotation sémantique riche du contenu. SPEC.09.01 L’utilisateur doit pouvoir marquer les entités textuelles par rôle : terme technique, code, nom propre, abréviation, acronyme, etc. SPEC.09.02 Les formules, figures, tableaux et citations doivent être typées dans le modèle de données (ex. figure scientifique, graphique statistique). SPEC.09.03 Les annotations doivent être exploitables pour l’accessibilité, la génération de métadonnées et la navigation contextuelle [16,39]. REQ.10 quickDoc doit permettre la modularisation et la composition documentaire. SPEC.10.01 Le langage doit inclure des directives d’inclusion ou d’import pour agréger des fichiers partiels. SPEC.10.02 La compilation doit reconstituer l’arborescence logique du document global. SPEC.10.03 Les inclusions doivent pouvoir être paramétrées (chemins relatifs, variables d’environnement). REQ.11 quickDoc doit garantir la cohérence hiérarchique et logique des structures. SPEC.11.01 Les titres doivent suivre une hiérarchie continue sans saut de niveau. SPEC.11.02 Les listes, tableaux et figures doivent être insérables dans n’importe quelle section sans altérer la structure. SPEC.11.03 Les références internes doivent être résolues de manière déterministe et vérifiées à la compilation. 4.3 Accessibilité, ergonomie et cognition REQ.12 quickDoc doit garantir la production de documents accessibles sans post-traitement manuel. SPEC.12.01 LessortiesPDFdoiventêtreconformesPDF/UAetlessortiesHTMLconformes WCAG 2.1 AAA [15,16]. SPEC.12.02 Chaque élément non textuel (image, graphique, audio, vidéo) doit comporter un texte alternatif ou une transcription. SPEC.12.03 Les structures logiques (titres, listes, tableaux) doivent être balisées sémantiquement pour la navigation assistée. 7 / 30 SPEC.12.04 Les formules mathématiques doivent être exportées en MathML ou dotées d’étiquettes aria-label. REQ.13 quickDoc doit offrir une syntaxe visuellement claire et cognitivement homogène. SPEC.13.01 Les marqueurs de mise en forme doivent être visibles, non ambigus et uniformes dans tout le langage. SPEC.13.02 Une seule notation par fonction doit exister pour éviter les variations dialectales. SPEC.13.03 La lisibilité en texte brut doit être conservée; tout document quickDoc doit rester compréhensible sans rendu [8,38]. REQ.14 quickDoc doit être simple à apprendre et à utiliser. SPEC.14.01 Un utilisateur novice doit pouvoir rédiger un document basique en moins d’une journée. SPEC.14.02 La documentation doit être claire, complète et illustrée d’exemples. SPEC.14.03 Chaque ajout syntaxique doit se justifier par un gain explicite de lisibilité ou de puissance expressive [26,27]. REQ.15 quickDoc doit favoriser la collaboration et la relecture. SPEC.15.01 Les documents doivent pouvoir être versionnés et comparés ligne à ligne dans un VCS (Git). SPEC.15.02 Des marqueurs de commentaires ou suggestions doivent être prévus pour l’annotation collaborative. SPEC.15.03 Le format texte clair doit permettre la revue sans outil spécifique [26,40]. 4.4 Portabilité, performance et sécurité REQ.16 quickDoc doit produire plusieurs formats de sortie standardisés. SPEC.16.01 Générer au minimum : PDF/A-3, PDF/UA, HTML5 + ARIA, EPUB 3, ODT et L A T E X. SPEC.16.02 Le contenu exporté doit conserver la structure logique et les métadonnées. SPEC.16.03 Les conversions doivent être contrôlées via une couche d’abstraction (AST →backend). SPEC.16.04 Chaque backend doit être testable par une suite de conformité [4,5]. REQ.17 quickDoc doit être interopérable et facilement intégrable. SPEC.17.01 Fournir un compilateur open-source (licence CeCILL-C). SPEC.17.02 Publier une Application Programming Interface (API) publique permettant d’utiliser le parseur et de manipuler l’AST. SPEC.17.03 Mettre à disposition une suite de tests de conformité Behavior-Driven Development (BDD) (Cucumber) et un TCK. SPEC.17.04 Prévoir des convertisseurs bidirectionnels (Markdown ↔ quickDoc ↔ HTML) [23,25]. REQ.18 quickDoc doit présenter de hautes performances sur de grands documents. SPEC.18.01 La compilation doit être incrémentale, multi-thread et à consommation mémoire contrôlée. SPEC.18.02 Un document de 100 pages avec figures doit se compiler en moins de deux secondes sur une machine standard. SPEC.18.03 Les tests de charge doivent inclure des centaines de pages et plusieurs 8 / 30 dizaines de mégaoctets d’images [10,12]. REQ.19 quickDoc doit garantir la sécurité lors de l’exécution de code ou du chargement de ressources. SPEC.19.01 Par défaut, aucun code inclus ne doit être exécuté. SPEC.19.02 Le mode d’exécution doit être explicitement activé par l’utilisateur. SPEC.19.03 Lesliensexternesnedoiventpasêtrechargésautomatiquementsansconfirmation. SPEC.19.04 Les configurations d’exception doivent être enregistrées dans un manifeste de sécurité. REQ.20 quickDoc doit assurer la compatibilité linguistique et typographique universelle. SPEC.20.01 Support complet d’Unicode, y compris alphabets non latins, symboles scientifiques et émojis. SPEC.20.02 Gestion multilingue et typographie locale (espacement, guillemets, ponctuation). SPEC.20.03 Les citations et références doivent respecter la locale sélectionnée. 4.5 Gouvernance, extensibilité et pérennité REQ.21 quickDoc doit être gouverné selon un modèle ouvert et transparent. SPEC.21.01 La spécification, les tests et les schémas doivent être publiés sous licence libre. SPEC.21.02 Les évolutions doivent être débattues publiquement et validées par version normative. SPEC.21.03 Les changements syntaxiques majeurs doivent faire l’objet d’une période de transition documentée [23]. REQ.22 quickDoc doit offrir un système de plugins standardisé pour étendre ses fonctionnalités. SPEC.22.01 Lesextensions(ex.nouveauxlangagesdecoloration,exports,filtres)doivent pouvoir être ajoutées sans modifier le cœur du compilateur. SPEC.22.02 Un registre officiel de plugins validés doit être maintenu pour garantir l’interopérabilité. SPEC.22.03 Les API d’extension doivent être stables et documentées [23,25]. REQ.23 quickDoc doit assurer la pérennité des documents produits. SPEC.23.01 Les documents doivent être archivables selon les formats ouverts (PDF/A, HTML, Markdown). SPEC.23.02 Les dépendances du langage (polices, modules) doivent être explicitement listées pour garantir la reconstruction future. SPEC.23.03 Un outil de validation doit pouvoir vérifier la conformité syntaxique et sémantique d’un document ancien avec une version donnée du langage. 9 / 30 5.5.8 Code Code délimiteur ` (backtick)entourantunmotouunephrasedecode.Exemple: `printf("hello")` donnera un <code> en monospace. Pour inclure un backtick littéral dans du code, on pourra utiliser `` `` (deux backticks entourant le code si celui-ci contient déjà un backtick). C’est la même règle que Markdown étendu. Un bloc affichant du code source brut. En quickDoc, on adopte la syntaxe de fences (clôtures) similaires à Markdown : trois accents graves ouvrants déclenchent un bloc de code jusqu’à rencontrer trois accents graves fermants. Après les initiaux, il est possible d’indiquer des paramètres sous la forme {set key:val ...} sur la ligne suivante. ```{<parametres>} <code sur plusieurs lignes> ``` Ceci indique un bloc de code en Python, à exécuter ( play:true ), et à exporter à la fois le code et le résultat (export:both). Les paramètres de bloc de code disponibles incluent : —lang (langage pour coloration syntaxique, ex : python,java,shell, etc.), —play (exécution autorisée = true/false), —runtime : moteur ou interpréteur spécifique si besoin, ex : node ou deno pour JavaScript, —export : choix entre verbatim,result,both,neither. Si play n’est pas true , le code n’est pas exécuté et seul le code brut est affiché (comme un exemple statique). Le résultat d’un bloc exécuté peut être du texte, une image (graphique), un tableau, etc., qui sera inséré à l’emplacement du bloc. Les blocs de codes peuvent être configurer de manière à obtenir plusieurs comportements. Les paramètres sont à inscrire sous la forme [[[set <parameter-name>:<value>]]] avec les parametres suivants : —lang : défini le langage utilisé pour le formatage du texte, —runtime : défini le moteur d’éxecution le cas échéant et si pertinent (e.g. deno, node, bun, etc.). —play : autorise l’execution du code avec tet l’empêche par défaut (nil). —export : précise ce qui doit être imprimé lors de l’export. Ce paramètre peut prendre spécifiquement les valeurs suivantes : —verbatim : imprime le code en police monospace avec son formatage et coloration synthaxique, —result : remplace le bloc de code avec son résultat (e.g. un graphique, un tableau, etc.), —both : imprime successivement le code en verbatim puis son résultat, —neither : n’imprime rien. 16 / 30 ```{set lang:python export:result} import matplotlib.pyplot as plt plt.plot([1, 2, 3], [4, 5, 6]) plt.show() ``` Listing 2 : Exemple de bloc de code complet FIGURE 1 : Résultat de l’exemple 17 / 30 5.5.9 Mathématique Pour les formules display (isolées au centre). LML utilise également une clôture dédiée, par exemple $$$ en début et fin de bloc (analogue à $$ ... $$ en L A T E X, mais sur plusieurs lignes). Entre ces délimiteurs, on place la formule en notation LML (très proche de la syntaxe L A T E X math). Des paramètres peuvent également être fournis après les $$$ initiaux via {set ...}, notamment : — solverpourspécifierunsolveursionsouhaitequelaformulesoitcalculée(ex:solver:sympy), — éventuellement d’autres paramètres comme le format d’affichage du résultat (exact vs numérique, nombre de décimales, etc. – ces détails pourront évoluer). Si un solveur est indiqué, la formule sera transmise à ce solveur et son résultat (par ex. simplification ou valeur numérique) pourra être inséré soit en sus, soit à la place, selon le contexte. Par défaut, sans solver, la formule est rendue telle quelle en notation mathématique. $$${<parametres>} <formule mathématique sur plusieurs lignes> $$$ Les blocs de mathématiques peuvent être associées à un résolveur d’équation tel que : $$ [[[set solver:<nom du résolveur>]]] <equation> Quelques exemples de résolveurs : Math.js, SymPy, Maxima, SageMath, Wolfram Alpha, etc. 5.5.10 Commentaire Commentaire délimiteur ; (point-virgule) pour mettre un court commentaire non visible dans la sortie, au sein d’une phrase. Ex : ;Note interne; sera complètement omis à l’export. quickDoc permet des commentaires de l’auteur qui ne seront pas rendus dans la sortie finale. Ceux-ci sont noté par ;;; en début de bloc et ;;; en fin. Tout texte à l’intérieur est ignoré lors du rendu. Alternativement, un double point-virgule ;; en début de ligne peut marquer un commentaire sur la ligne entière (notamment dans un bloc de code, pour commenter du code qui ne sera pas exécuté). Des commentaires enrichis sont possiblesvia des paramètres type : sur le bloc de commentaire. Par exemple type:todo ou type:todo-inline pour signaler une tâche à faire. Cela pourra se traduireparunencart”TODO”visibledanslePDF/HTML,éventuellementdanslamargeoudans le flux du texte. Ceci est utile en phase de rédaction (pour indiquer des sections incomplètes, etc.). ;;;{<parametres>} <commentaires sur plusieurs 18 / 30 lignes> ;;; Les blocs de commentaires sont de 4 types : — sans précision, ils ne sont pas exportées — avec type:todo-inline ils impriment un bloc de type ”TODO” en lieu et place ten que celui ci : bloc ”TODO” en ligne — avec type:todo ils impriment un bloc de type ”TODO” dans la marge du document tel que celui ci : e.g. 5.5.11 Propriétés Un bloc de propriété permet d’attacher des métadonnées à tout autre bloc. — inline : {get/set prop:value} — multiline : {{{get/set prop:value}}} Associer des propriétés à un bloc de texte : Ceci est un bloc de texte avec des propriétées attachées. {{set type:properties key1:value1 key2:value2}} Les propriétés peuvent être utilisés pour collecter des entrées utilisateurs et créer des formulaires en écrivant {get <property> <key>:<value>} où <key> correspond au type attendu et <value> correspond à la contrainte associée. Par exemple, voici des appels d’entrées valides : —{get user-name string:20}: donnera ____________________ etsera affecté à la propriété ”user-name”, —{get user-lang string:2} donnera __ et sera affecté à la propriété ”user-lang”. Lesdéclarationsdepropriétésmonolinesontdelaforme {{get/set prop:value}} .Elles sont particulièrement adaptéesà la déclaration de la mise en page du document (aligmnement du texte, mise en colonne des blocs, etc.). Ces opérations se réalisent en deux étapes : 1. Définir une mise en forme tel que : {{set text_style name:paraghaphe scope:raw-text al:justif size:12 long:80char color:black font:sourcesans-pro columns:nil}} 2. L’appliquer tel que : {{use text-style name:paragraphe}} La mise en forme sera appliquée à partir de sa déclaration ( use ) jusqu’à la déclaration d’un autre style. 19 / 30 5.5.12 Tableau La syntaxe des tableaux peut s’inspirer soit de Markdown (tabulation par des | ), soit d’AsciiDoc (lignes et colonnes séparées par | et formatage avancé via des cellules d’entête ! etc.). Une ligne d’en-tête optionnelle, encadrée de | et séparant les cellules par | . Une ligne de séparation en-dessouscomposée de |- - -| (aumoins 3 tiretsentrechaque | )indique la finde l’en-tête. Puis les lignes de corps du tableau, avec la même syntaxe de cellule séparées par |. | Colonne A | Colonne B | |-----------+-----------| | Valeur A1 | Valeur B1 | | Valeur A2 | Valeur B2 | Les cellules peuvent contenir du texte formaté (italique, etc.) mais pas de blocs multiples (pas de titre ou liste à l’intérieur d’une cellule, sauf en utilisant éventuellement des astuces non couvertes ici). La portée de cette spécification de tableau est limitée aux usages simples de type CSV mis en forme. Les aspects plus complexes (fusion de cellules, tableaux imbriqués) ne sont pas gérés nativement par LML v1, mais pourraient être ajoutés via des extensions. 5.5.13 Bloc sémantique utilise les </> 5.5.14 Multimédia L’insertion d’une image se fera via une directive de lien spécialisée (voir 5.6 sur les liens). Tout lien vers un fichier image (ex : [[img:chemin/figure.png]] ) insère l’image dans le document. Pour ajouter une légende, on pourra encapsuler cette image dans un bloc de figure, parexempleenla précédantd’untitredefigureouenutilisantunemacrodédiée.Une approche consiste à traiter une image insérée isolée avec un texte de légende suivant immédiatement comme une figure groupée. Par exemple : [[img:diagrams/schéma1.svg]] {{{set id:img1 title:"Processus illustré" alt-text:"Schéma illustratif du processus" description:"Une description factuelle de l'image" }}} 5.5.15 Snippets (fragments réutilisables) mécanisme permettant d’injecter du contenu ou des références (ex. inclusion de la valeur d’une propriété). 20 / 30 Tous les blocs de textes peuvent être associées à des tags. Un tag s’écrit #<tag> peut être insérée à n’importe quel endroit du bloc de texte en respectant les rêgles de balisage décrites au paragraphe 5.7. TABLE 2 : liste des snippets Type Lemma Behavior Ref Link @element Insère un [[lien]] unidirectionnel Tag #tag Insère un [[lien]] bidirectionnel Les tags sont utilisés pour faire de l’analyse sémantique. Ecrire un tag entraine la création ou la mise à jour d’un fichier ”tag_<nom-du-tag>.qdo” constitué comme ceci : # Nom-du-tag [[[get count:?]]] ;; nombre d'occurence dans le projet [[[get blocs:?nom-du-tag]]] ;; tous les blocs utilisants le tag L’instruction [[[get blocs:?nom-du-tag]]] peut être complété par un système de tris. Parexemple,pourlisterlesblocsparordrededatedécroissanteonécrira [[[get blocs:?nomdu-tag order-by:date-desc]]]. Unsystèmedetrâmepermettantauxutilisateursdepréconfigurercesdocumentsetdemodifier en lot leurs configuration serait un atoût en matière d’expérience utilisateur. Les snippets sont une fonctionnalité héritée notamment de quickDoc, permettant d’insérer dynamiquementdescontenusgénérésouderéférencerdesélémentstransversesdudocument. Ils se présentent sous forme de balises triple-crochets avec mot-clé, par exemple [[[get ...]]] ou [[[set ...]]]. 5.5.1 [[[set ...]]] – définition de propriété ou configuration La balise set est utilisée soit en tête de document pour définir des styles/config globales, soit au sein de blocs (comme vu plus haut) pour paramétrer un bloc spécifique (langage d’un code, type d’admonition, etc.). En général, [[[set X:Y ...]]] signifie «assigner la propriété X avec la valeur Y». Par exemple : [[[set color:blue]]] . Dans le cas des blocs, cette instruction apparaît immédiatement après l’ouverture du bloc (comme illustré pour les blocs de code, de maths, etc.). Dans le cas d’une configuration globale, on peut l’utiliser soit dans le front-matter, soit sur une ligne spéciale au début du document éventuellement introduite par un commentaire. QuickDoc montrait une inclusion de fichier de config via ;;[[[set config file:...]]] ,LML pourra avoir plus simplement dans le front-matter une section dédiée pour importer des configs. En résumé, [[[set ...]]] n’est pas exactement un snippet inséré dans le texte final, mais une directive de réglage affectant le rendu ou le comportement. 5.5.2 [[[get ...]]] – insertion de contenu généré La balise get permet de récupérer une valeur ou un contenu calculé. On l’utilise au sein du texte pour insérer, par exemple, la valeur d’un compteur, d’une propriété, ou le résultat d’une requête. Syntaxe générale : [[[get <source> <clé>:<filtre>]]]. 21 / 30 Exemples envisagés : [[[get count:?]]] pourrait renvoyer un nombre, par ex. le nombre d’éléments correspondant à une requête (voir plus bas). [[[get blocs:?tag]]] pour insérer la liste de tous les blocs taggés par #tag (notion de tag abordée en 5.5.3). [[[get property nom]]] pour insérer la valeur d’une propriété de métadonnée nommée nom définie dans le document (par ex. l’auteur ou le titre). [[[get date:now]]] pour la date du jour, etc., ou d’autres fonctions. LML devra définir une liste de sources accessibles via get : count (compteurs), blocs (collection de blocs répondant à un critère), property/meta (métadonnées), possiblement env (variables d’environnement ou arguments de compilation), etc. Des filtres ou paramètres peuvent affiner la requête, p. ex. [[[get blocs:?tag orderby:date-desc]]] pour trier les blocs taggés par date décroissante. Ce mécanisme puissant rapproche LML d’un outil de gestion de connaissances, permettant de générer des index, des tables des matières, des listes de tâches automatiques, etc. 5.5.3 Tags et étiquetage sémantique En LML, on autorise l’ajout de tags à n’importe quel bloc de texte pour une classification sémantique. Un tag s’écrit #motcle directement dans le texte ou en préfixe d’un bloc. Par exemple : #TODO au début d’une ligne de liste de tâche, ou #important dans un paragraphe. Ces tags ne sont pas affichés dans le rendu final, ou éventuellement transformés en éléments visuels discrets, mais surtout ils alimentent une indexation interne. L’utilisation de tags combinée à [[[get blocs:?tag]]] permet de générer par exemple un index de tous les blocs marqués d’un tag particulier. On peut s’en servir pour : liste des TODO restants, index thématique, glossaire (tag #terme sur la définition d’un terme), etc. Cette approche en fait un langage plus sémantique et orienté gestion de connaissances. Techniquement, LML pourrait créer en coulisse des fichiers ou des sections invisibles où sont listés les contenus par tag (comme quickDoc suggère un fichier tag_nom.qdo généré pour chaque tag). La spécification peut rester au niveau conceptuel (il n’est pas nécessaire de normer comment c’est implémenté, juste que le résultat est comme si un tel index existait). 5.5.16 Callouts Les callouts sont des liens bidirectionnels à l’intérieur d’un document et permettent de cibler des blocs. Ils sont utilisés pour sauter rapidement à un contenu, une note, une référence, etc. 5.5.17 Liens et références Les liens sont tous directionnels. Référence interne plusieurs types de callouts permettent de créer des liens internes : 22 / 30 TABLE 3 : Text callouts Type Lemma Behavior Reference [ref:id] Foot Note [fn:id] Quote [cite:id] Figure ref [fig:id] Table ref [tbl:id] Code ref [src:id] Header jump [head:id] —[ref:ID] pour référence générique à un élément repéré parl’identifiant ID (section, figure, etc.). Cela affichera soit le numéro de l’élément (ex : “Figure 3”) soit un texte par défaut. —[fig:ID] affiche “Figure X” en liant vers l’image de nom ID. —[tbl:ID] pour “Tableau X”. —[eq:ID] (éventuellement) pour les équations numérotées “(X)”. —[src:ID] pour référencer un listing de code. —[header:ID] pour pointer vers le titre de section identifié. —[cite:ID] insère un renvois vers la bibliographie et référence l’entrée bibliographique. —[fn:ID] —[rmq:ID] Liens externes La syntaxe générale des liens est [[URL|texte]] ou [[URL]] si pas de texte(afficheral’URLbruteoularessourceintégréesireconnu).Parexemple: [[https://example.com|site web]] pour un lien hypertexte. Si le protocole est img : ou file : ou autre, cela peut déclencher des comportements spécifiques. Tous les liens suivent l’écriture [[<CONTEXT>:<LINK>]|[<TEXT>]] pù seul le <LINK> doit être renseigné. Les autres éléments sont : —<CONTEXT> fournisdesinformationscomplémentairespourl’affichagedulien.Celapermet de mettre en oeuvre des affichages adaptés aux images, vidéos, player de musique, flux RSS, etc. —<LINK> is the path of the resource on the World Wide Web, in a file system, or on any supported network. We can call a ‘Header ID‘ from the current document or from another one. —<TEXT> est le texte de remplacement à afficher à la place du lien. un lien peut être attaché à des propriétés {get} est utilisé pour renvoyer vers une section particulière du lien (un titre, un callout, etc.). {set} est utilisé pour déclarer les éléments de descriptions et d’accessibilité. Tag #tag Mention @someting renvois à une personne ou à une étape d’un processus Radiolink [[[name]]] crée un lien dynamique contextuel renvoyant chaque mentions du name du radiolien à la déclaratio nde celui-ci. 23 / 30 TABLE 4 : <LINK> types Type Lemma Can be used to URI Web URL [[https:link]] Display a bookmark Local File [[file:<path>]] Musique [[:<path or url>]] Display a music player Image [[img:<path or url>]] Document [[doc:<path or url>]] Display a document viewer Video [[vid:<path or url>]] Display a video player Header ID [[id:headerId]] RSS Flow [[rss:<url>]] Display a list of last entries IRC Flow [[irc:<url>]] Display a list of last messages Email [[mailto:<email>]] Display a contact form 5.6 Normailsation et i18n insertion des espaces insécables associés au divers éléments au regard des regles lexicales de chaque langues (guillemets, citations, doubles-points, etc.) 5.7 Balisage Lists begins with a bullets that represent their meaning followed by a space. The following is supported : — Ordered lists starts with 1., — Unordered lists starts with -, — Headers are lists too and starts with a #, the number of #set the level of the header. Sublevels (nested lists) are supported for headers, ordered and unordered lists. There must be 4 spaces before the sublevel bullet. The export backend shall provide settings to customise desired formatting outputs of ordered lists (alpha-numeric numbering, dots, parentheses…) 6 Consistency analysis A consistent lightweight markup language shall have only one way to format text. Markdown variants on the 5are limited to those listed by IANA’s ”Markdown Variant” [21]. We exclude SSW and Quarto, the first one is too contextual and the second is based on Pandoc markdown. — Bol : Bold — Ita : Italique — OrL : Ordered List — UnL : Unordered List — Und : Underline — Hig : Highlight 24 / 30 TABLE 5 : Text formatting consistency versus Markdown variants Format Bol Ita OrL UnL Und Hig Str Ver Cod Sup Sub Com quickDoc 1 1 1 1 1 1 1 1 1 1 1 1 CMD[6] MMD[31] GFM[20] Pandoc[4] Fountain[41] MD for RFCs[42] Pandoc2rfc MDX[43] MyST[34] AsciiDoc reST Org-Mode Textile Djot Wikitext Creole txt2tags Setext — Str : Strike — Ver : Verbatim — Cod : Inline code — Sup : Superscript — Sub : Subscript — Com : Comment 7 Capacity analysis 8 Typesystem compatibility 9 Conclusion 25 / 30