Nota, un langage documentaire pour les articles académiques et les billets de blog dans le navigateur
(nota-lang.org)- Au-delà des limites des PDF et des pages web statiques, l’objectif est un langage documentaire qui permette au navigateur de comprendre la structure du document et aux lecteurs de l’exploiter directement
- Les documents Nota sont compilés en programmes JavaScript et exécutés dans le navigateur, ce qui permet d’utiliser variables, fonctions et structures de données pour la rédaction
- Conçu en gardant à l’esprit l’intégration de bibliothèques JavaScript comme KaTeX, Vega-Lite et Penrose, ainsi que la prise en charge des exigences d’accessibilité
- Le paquet
@nota-lang/notapermet d’installer l’exécutablenotaet de manipuler les documents via des flux de build ou d’édition interactive - Il s’agit encore d’une technologie nouvelle et en évolution : l’architecture et l’API peuvent changer, et il faut s’attendre à des bugs, des manques ou des inexactitudes dans les outils et la documentation
Une structure documentaire que le navigateur comprend
- Nota est un langage destiné à écrire des documents comme des articles académiques et des billets de blog
- Son objectif est d’amener les documents vers un média du XXIe siècle
- À l’intérieur d’un document, on trouve souvent des structures que le lecteur doit suivre, comme les définitions de termes et les références
- Par exemple, le mot
Notarenvoie à un terme défini dans le paragraphe précédent - Nota permet à l’auteur d’exprimer cette structure, et au navigateur de la comprendre afin que le lecteur puisse l’exploiter
- Sur la page d’exemple, on peut cliquer ou double-cliquer sur la référence
Notapour voir son comportement
- Par exemple, le mot
- Les documents Nota sont compilés en programmes JavaScript
- Les documents peuvent être consultés sur tout appareil disposant d’un navigateur web
- On peut utiliser des variables, des fonctions et des structures de données pour simplifier la rédaction
- Intégration possible avec des bibliothèques JavaScript comme KaTeX, Vega-Lite, Penrose
- Il est plus facile de prendre en charge des exigences d’accessibilité comme les lecteurs d’écran
Installation et flux d’édition
- Nota peut être utilisé en installant l’exécutable
notavia le paquet@nota-lang/nota- Les prérequis sont NodeJS ≥ 16 et npm ≥ 6
- Le répertoire des binaires globaux de NodeJS doit être présent dans le
PATHdu shell
- Un document Nota unique peut être compilé avec le flux suivant
npm install --global @nota-lang/notaecho "@Title: Hello world" > index.notanota build index.notaopen dist/index.html
- Les fichiers Nota peuvent être modifiés en édition interactive avec la commande
nota edit index.nota - La méthode de rédaction est décrite dans la Reference
- Pour ajouter Nota à un site web ou consulter l’architecture, voir l’Integration guide
Le fossé entre PDF et web statique
- Les principaux supports des documents numériques se divisent entre PDF et pages web
- Le PDF est conçu pour refléter les documents physiques et conserve les contraintes du papier, comme la pagination, la largeur fixe et un style immuable
- Les pages web permettent un formatage dynamique, comme le redimensionnement pour mobile, la traduction dans d’autres langues ou le changement de couleurs pour les personnes atteintes de daltonisme
- Les pages web permettent aussi des interactions dynamiques, comme du texte qui demande plus de contexte, des diagrammes qui changent de point de vue ou des annotations pour la suite
- Aujourd’hui, ces fonctions dynamiques restent surtout accessibles aux développeurs web spécialisés
- Les outils documentaires existants comme LaTeX, Pandoc, Markdown et Scribble ne produisent pour la plupart que des pages web statiques
- Nota cherche à réduire ce fossé avec un langage documentaire à faible barrière d’entrée, à fort potentiel d’extension et à courbe d’apprentissage progressive
État actuel et références
- Nota est encore une technologie nouvelle et en évolution
- L’architecture et l’API évoluent en permanence
- Les outils peuvent contenir des bugs et des fonctionnalités manquantes
- La documentation peut être incomplète ou inexacte
- Le projet cherche actuellement des premiers utilisateurs prêts à participer à la création de Nota comme langage documentaire du futur
- Les composants
@Definitionet@Refpermettent, si l’auteur ajoute une petite quantité d’annotations au document, au runtime Nota d’afficher dans le contexte la définition d’une référence sous forme d’infobulle- De futures versions de Nota pourraient inclure des fonctions comme la recherche de toutes les références vers une définition donnée
- La philosophie de conception est développée dans A New Medium for Communicating Research on Programming Languages
1 commentaires
Avis de Hacker News
Je suis le créateur de Nota, et depuis le prototype initial de la page web, je suis en train d’en retravailler la conception
Je pose des bases plus solides pour des questions comme comment mêler contenu et calcul (https://arxiv.org/abs/2310.04368), ou la façon dont la syntaxe rend le travail documentaire facile/difficile/impossible (https://github.com/cognitive-engineering-lab/doclang-benchma...)
Je crois toujours à la grande philosophie du projet, mais Nota devrait beaucoup changer d’ici environ 6 mois. Entre-temps, je considère que l’avancée la plus intéressante dans le domaine des langages de document est Typst, et je vous recommande d’y jeter un œil : https://typst.app/
La prochaine version de Nota sera écrite à 99 % en Rust :-)
Si les performances sont un vrai problème, Rust a plus de sens que JavaScript, mais je ne sais pas si ce sera déterminant dans la plupart des cas d’usage
Je n’ai jamais aimé LaTeX, même après avoir beaucoup rédigé de gros documents avec ; c’était une sorte de monstre pour le monde académique, pas pour l’entreprise. Même dans Word, les choses qu’on veut faire de manière cohérente ne sont pas toujours simples, les styles s’emmêlent vite, et la numérotation comme les listes à puces sont propices aux erreurs
Quand plusieurs cycles de révision s’enchaînent, le suivi des modifications devient un gros problème, et on finit par devoir faire confiance à l’autre partie pour ne pas écraser le suivi. Un produit qui garantirait que toutes les modifications, du début jusqu’à l’approbation finale, soient correctement visibles pourrait à lui seul devenir une killer app appréciée des entreprises et des avocats
En saupoudrant un peu de blockchain là-dessus, il serait peut-être plus facile de lever des fonds, mais en réalité cela ressemble davantage à un problème de cryptographie de base qu’à un sujet de blockchain, et ce niveau de complexité ne semble pas nécessaire
Le plus important pour un langage de document est de donner la priorité à ces deux activités. Par exemple, un document TeX commence par du code préparatoire comme
\documentclass, plusieurs\usepackage, des définitions de théorèmes ou des réglages de polices, alors qu’un document R Markdown/Quarto commence directement par le sens réel du texte, comme le titre, l’auteur et le résuméLa différence d’accent est évidente
Cela inclut des mises en page denses et riches en informations comme les posters de conférence A0, des styles de documents imposés par des normes nationales comme GOST dans l’espace post-soviétique, les exigences de styles bibliographiques qui explosent selon les traditions internationales, le fait de donner l’apparence du style par défaut d’une version précise de MS Word, le placement précis d’images ou de texte par-dessus des figures pour des corrections rapides dans un article, et l’ajustement conscient de ce genre de choses
Dans l’univers TeX, tout cela est techniquement possible, mais en pratique cela exige une magie noire si profonde que même un utilisateur ordinaire diplômé n’a pas envie de s’y plonger
Ces derniers mois, je m’en suis servi avec plaisir pour explorer des idées d’animations SVG (https://simpatico.io/svg) ou pour concrétiser de nouvelles structures de données/algorithmes (https://simpatico.io/stree3)
L’ensemble du serveur et du processeur Markdown tient en environ 500 lignes de code Node lisibles, avec très peu de dépendances, aucune dépendance transitive et aucune étape de compilation nécessaire. Par défaut, le serveur n’autorise aucune ressource tierce ni aucun cookie, d’aucune sorte
C’est sous licence MIT sur GitHub, et je suis en train de le nettoyer en le déplaçant d’un dépôt personnel vers un dépôt d’organisation. Pour référence : https://simpatico.io/lit
Là où une « dynamicité essentielle » n’est pas nécessaire, son absence est plutôt une fonctionnalité, pas un bug, à mon avis
Sur mobile, je préfère de loin lire des pages web plutôt que des PDF, car une page web raisonnablement conçue peut généralement s’adapter à l’écran du téléphone
Il faut un format qui encode à la fois l’information visuelle et l’information numérique. La couche numérique n’a pas besoin d’être visible par défaut, mais elle doit être accessible quand c’est nécessaire
Bien sûr, ces « fonctionnalités » ont été considérées comme des bugs et supprimées de la spécification ISO PDF/A destinée à l’archivage à long terme : https://en.wikipedia.org/wiki/PDF/A
L’idée, c’est que parfois un document doit simplement être un document. Pour les articles scientifiques, LaTeX est écrit par des humains pour des humains, et grâce aux commandes personnalisées et aux packages, on peut rédiger un document en texte brut aussi lisible que l’article généré. C’est aussi bon pour l’accessibilité
Les documents dynamiques ouvrent un territoire intéressant encore peu exploré, mais il faut de bons exemples d’usage élégant
En résumé, c’est plus proche de LaTeX, avec quelques éléments de Markdown ; c’est écrit en JavaScript, donc beaucoup de gens peuvent contribuer dans un langage qu’ils connaissent déjà, et le fait que ce soit sous licence MIT est un plus
Je ne sais pas si j’en aurai l’usage tout de suite, mais ça a l’air assez chouette. Si je devais écrire un texte nécessitant des fonctionnalités à la LaTeX, sans que la destination impose LaTeX, j’essaierais probablement Nota
Je considère presque Knuth comme une figure semi-divine, mais il n’est pas descendu du ciel pour nous donner TeX en disant : « n’essayez jamais rien de nouveau pour l’éternité »
Il lui manque aussi beaucoup trop de garde-fous et de fonctionnalités de confort que les langages modernes offrent. Quand j’utilise LaTeX, je dois fortement m’appuyer sur des fragments
\input{}pour isoler les blocs et éviter qu’un simple caractère d’échappement oublié ne casse toutJ’espère toujours une réinterprétation moderne, mais j’ai l’impression qu’on est coincés dans un optimum local difficile à quitter, à cause de décennies d’inertie et de packages accumulés autour de TeX
Parmi les choses similaires, il y a https://pandoc.org/, https://quarto.org/, https://markdoc.dev/, https://mdxjs.com/, https://typst.app/
Le problème, avec une nouvelle tentative dans ce domaine, c’est qu’elle arrive sur un terrain déjà beaucoup trop encombré. Le fait que les solutions existantes ne soient pas parfaites n’a pas vraiment d’importance
C’est un peu comme entrer dans une ville historique européenne, avec mille ans d’histoire architecturale, et défendre la conception d’un excellent nouveau bâtiment. Les terrains libres sont rares, et les gens ne démolissent pas simplement les structures anciennes pour essayer du neuf. Il faut un avantage écrasant
En architecture, l’acier et le béton armé ont ouvert la dimension verticale et fortement amélioré l’utilisation de l’espace ; l’histoire a ensuite changé
La question clé est de savoir s’il existe une dimension inexplorée suffisamment forte pour attirer les gens vers un énième format de document censé « améliorer » ASCII, reStructuredText, wikitext, Markdown, TeX/LaTeX, AsciiDoc, HTML, etc.
La réponse courante, c’est une infrastructure d’hypertexte sémantique. La vision originelle n’a pas encore été réalisée. Si l’on suppose que les écosystèmes fermés d’aujourd’hui sont un cauchemar passager, alors un web à nouveau décentralisé aura besoin d’une infrastructure de rédaction de documents moderne, conviviale et émancipatrice
Mais il peut aussi exister d’autres dimensions capables d’élever la rédaction et le partage de documents à un nouveau niveau. La beauté de l’innovation, c’est qu’elle n’est pas prisonnière des règles et sagesses établies
Il faut un format de document efficace, et pour cela un format qui n’essaie pas de tout faire. Autrement dit, les tableaux devraient être séparés par type de document au niveau des fichiers, comme dans un format standard de tableur, au lieu que HTML essaie de tout faire lui-même, tableaux, graphiques (SVG), etc.
En séparant chaque élément dans un fichier distinct, les utilisateurs peuvent choisir le programme qu’ils veulent pour consulter ou manipuler les documents, au lieu de tout voir dans un seul navigateur ; cela aide aussi à la distribution réseau et reste avantageux dans les environnements à faible stockage ou faible bande passante
De mon point de vue, il n’y a donc rien de nouveau à inventer. Il suffit de spécialiser et de polir ce qui a déjà été inventé
En suivant le lien, https://willcrichton.net/nota/ montre des avantages convaincants dans la niche visée par Nota, à savoir rendre les articles de recherche en langages de programmation plus faciles à comprendre
Pouvoir effectuer un rendu en PDF de haute qualité est évidemment une nécessité et une question. Pour la compatibilité avec les systèmes existants, un rendu vers LaTeX serait peut-être même préférable
Fondamentalement, Nota est du balisage + du code (JavaScript), et cette combinaison correspond au domaine visé par MDX. Quand quelqu’un l’a déjà mentionné par le passé, le créateur avait dit que Nota était orienté documentation, tandis que MDX était orienté sites web : https://news.ycombinator.com/item?id=31349579
Dans ce cas, pour que Nota décolle, je pense que quelqu’un devra l’enrober dans un produit. Le résultat a l’air bon, mais devoir manipuler Node.js pour créer des documents est trop fastidieux, et donne de nouveau une impression à la LaTeX. La plupart des gens préféreront Notion ou un traitement de texte
De plus, Nota n’est pas un concurrent direct de la famille TeX. Nota produit quelque chose destiné à être lu par un navigateur web, tandis que xxxTeX produit quelque chose destiné à être lu par un lecteur PDF. Je sais que xxxTeX peut aussi produire d’autres formats de sortie, mais la plupart des gens l’utilisent pour générer des PDF
MDX est prêt à être utilisé avec n’importe quel framework, React/Vue, etc., mais cela signifie qu’il ne propose en gros aucune opinion par défaut
Nota donne l’impression de pouvoir être branché sur un générateur de site statique. Bien sûr, il faudrait les faire fonctionner ensemble, mais cela me semble un objectif atteignable pour quelqu’un d’un peu plus investi que moi
Je ne vois pas pourquoi il faudrait un langage qui compile vers JavaScript pour créer des pages de texte. AsciiDoc répond au même objectif
De vrais éditeurs comme O’Reilly utilisent aussi AsciiDoc comme format d’entrée pour produire des livres et des sites web
J’utilise AsciiDoc depuis quelques années et je l’apprécie. Je ne reviens à Markdown que là où AsciiDoc n’est pas encore pris en charge. Par exemple, GitHub et GitLab prennent en charge le rendu AsciiDoc
PyPI ne le prend malheureusement pas encore en charge, mais il semble que davantage de personnes s’y intéressent, ce qui est une bonne chose : https://github.com/pypa/readme_renderer/issues/205
En revanche, les outils actuels sont frustrants. Je vois bien l’énorme travail investi dans Asciidoctor et je l’apprécie, mais il n’y a pas de sortie HTML5 sémantique, l’intégration avec des générateurs d’images est difficile, ou du moins plus difficile que nécessaire, et c’est suffisamment lourd pour être la seule dépendance Ruby sur toute ma machine
En dehors du problème de Ruby, ces questions sont ouvertes sur GitHub, donc avec davantage de temps et de ressources, elles devraient pouvoir être résolues
Je ne sais pas trop. Emacs org-mode semble meilleur et moins dépendant de JavaScript
https://docusaurus.io/ est aussi très bon et flexible. Pour étendre Nota de manière similaire, je recommande de regarder ces deux-là
Je réfléchissais justement à la façon la plus simple de créer un blog avec du contenu majoritairement statique, tout en pouvant y ajouter des graphiques interactifs ou des personnalisations arbitraires si besoin. Je me demande si Nota est un bon choix
Parmi les autres options, j’ai aussi regardé Quarto (https://quarto.org/), et je ne sais pas s’il serait possible d’utiliser un simple blog de site statique comme Jekyll, puis de modifier directement le HTML généré quand nécessaire
Cela permet d’utiliser tout HTML, de personnaliser le processus de génération, de gérer les dépendances assez facilement, et les formats concernés sont standardisés
Avec Astro, on écrit des composants de style React et il compile en fait en HTML/CSS pur, sauf dans les cas où JavaScript est réellement nécessaire. Mon site personnel et mon blog sont aussi faits avec Astro : https://sjer.red/, et le code source est ici : https://github.com/shepherdjerred/shepherdjerred.com
Il existe aussi un tutoriel pour créer un blog avec Astro : https://docs.astro.build/en/tutorial/0-introduction/