J'avais jamais vraiment creusé ce langage jusqu'à présent, car j'ai pas vraiment besoin personnellement d'un langage de doc technique, ayant juste écrit quelques pages man et pour ça un langage vraiment spécialisé comme mdoc(7) est plus adapté. Mais je suis toujours curieux au sujet des langages de balisages, j'ai donc regardé plus en détail. Je pensais que c'était simplement un markdown++ qui exportait vers docbook, mais le langage a quand même un certain nombre de trucs le rendant plus adapté à la maintenance d'un gros projet : possibilité d'être sémantiquement extensible et pas que présentationnel (ajout de classes et rendu personnalisable dans css, je sais pas ce que ça donne pour l'export LaTeX par contre), possibilité d'utiliser des directives style ifdef, pour personnaliser s'il le faut en écrivant du code différent pour des formats de rendus différents (autorisant par exemple une personnalisation LaTeX poussée sans empêcher l'export à d'autres formats). Ça gère plus de trucs de base, peut-être limite trop, car on maîtrise pas ça en deux heures, mais ça a son côté positif aussi si on en a besoin (tableaux complexes, balisage de blocs de code, etc.). Et le langage est extensible, bien qu'on dirait qu'il faut écrire du ruby pour ça, donc pas pour tout le monde, surtout vu le nombre de points d'extension différents et le côté bas niveau de l'API.
Par contre, pour de gros projets, sauf si je suis passé à côté ou oubli dans la doc, ça préserve un inconvénient à mon avis majeur du « tout est permis » du markdown : pas de messages d'erreur pour des trucs classiques comme oubli d'une étoile (balise fermante), a priori. On dirait qu'il y a des messages d'erreurs pour certains trucs spécifiques (contrairement à markdown ou tout est vraiment valide), mais c'est plutôt limité. C'est un truc qui me surprend, peut-être n'est-ce juste pas documenté dans la liste des diagnostics, j'ai pas testé en vrai (pas de paquet asciidoctor sur OpenBSD on dirait, donc testé avec le veil asciidoc). Je comprends que ce genre de syntaxe « intuitive » est en fait bien plus compliquée et que donc c'est moins facile d'avoir de bons messages d'erreur qu'avec une syntaxe plus explicite, mais je vois pas trop ce qui empêcherait une implémentation de prévenir l'utilisateur qu'il a oublié de fermer des balises (quitte à avoir une localisation sous-optimale).
Je ne vois pas non plus de vérification automatique possible que les classes personnalisées utilisées lors de l'utilisation des balises # font partie d'une liste spécifique et n'ont pas de typos : il faut se faire un script à part pour vérifier extraire ces infos et vérifier qu'on a pas fait de typos, je suppose.
Et puis, une dernière chose que j'ai cherché sans trouver, c'est une façon de faire de nouvelles macros/styles (sans passer par toute la machinerie ruby) capables d'abstraire le code spécifique à un format d'export de façon simple pour pas polluer le corps du texte. Sans ça, les ifdef sont quand même beaucoup moins utiles. Je vois donc pas non plus de façon de raccourcir simplement l'utilisation de code comme [.pathname]#/etc/#, donc si on tient vraiment à écrire de façon sémantique et non présentationnelle, ça devient un peu verbeux (plus de caractères même qu'en LaTeX ou groff où on aurait pu définir quelque chose comme \pathname{/etc/} — 2 symboles en moins).
# Langage intéressant mais certains trucs me chiffonnent
Posté par anaseto . En réponse au journal Documentation du format AsciiDoc en français. Évalué à 6.
J'avais jamais vraiment creusé ce langage jusqu'à présent, car j'ai pas vraiment besoin personnellement d'un langage de doc technique, ayant juste écrit quelques pages man et pour ça un langage vraiment spécialisé comme mdoc(7) est plus adapté. Mais je suis toujours curieux au sujet des langages de balisages, j'ai donc regardé plus en détail. Je pensais que c'était simplement un markdown++ qui exportait vers docbook, mais le langage a quand même un certain nombre de trucs le rendant plus adapté à la maintenance d'un gros projet : possibilité d'être sémantiquement extensible et pas que présentationnel (ajout de classes et rendu personnalisable dans css, je sais pas ce que ça donne pour l'export LaTeX par contre), possibilité d'utiliser des directives style ifdef, pour personnaliser s'il le faut en écrivant du code différent pour des formats de rendus différents (autorisant par exemple une personnalisation LaTeX poussée sans empêcher l'export à d'autres formats). Ça gère plus de trucs de base, peut-être limite trop, car on maîtrise pas ça en deux heures, mais ça a son côté positif aussi si on en a besoin (tableaux complexes, balisage de blocs de code, etc.). Et le langage est extensible, bien qu'on dirait qu'il faut écrire du ruby pour ça, donc pas pour tout le monde, surtout vu le nombre de points d'extension différents et le côté bas niveau de l'API.
Par contre, pour de gros projets, sauf si je suis passé à côté ou oubli dans la doc, ça préserve un inconvénient à mon avis majeur du « tout est permis » du markdown : pas de messages d'erreur pour des trucs classiques comme oubli d'une étoile (balise fermante), a priori. On dirait qu'il y a des messages d'erreurs pour certains trucs spécifiques (contrairement à markdown ou tout est vraiment valide), mais c'est plutôt limité. C'est un truc qui me surprend, peut-être n'est-ce juste pas documenté dans la liste des diagnostics, j'ai pas testé en vrai (pas de paquet asciidoctor sur OpenBSD on dirait, donc testé avec le veil asciidoc). Je comprends que ce genre de syntaxe « intuitive » est en fait bien plus compliquée et que donc c'est moins facile d'avoir de bons messages d'erreur qu'avec une syntaxe plus explicite, mais je vois pas trop ce qui empêcherait une implémentation de prévenir l'utilisateur qu'il a oublié de fermer des balises (quitte à avoir une localisation sous-optimale).
Je ne vois pas non plus de vérification automatique possible que les classes personnalisées utilisées lors de l'utilisation des balises
#font partie d'une liste spécifique et n'ont pas de typos : il faut se faire un script à part pour vérifier extraire ces infos et vérifier qu'on a pas fait de typos, je suppose.Et puis, une dernière chose que j'ai cherché sans trouver, c'est une façon de faire de nouvelles macros/styles (sans passer par toute la machinerie ruby) capables d'abstraire le code spécifique à un format d'export de façon simple pour pas polluer le corps du texte. Sans ça, les ifdef sont quand même beaucoup moins utiles. Je vois donc pas non plus de façon de raccourcir simplement l'utilisation de code comme
[.pathname]#/etc/#, donc si on tient vraiment à écrire de façon sémantique et non présentationnelle, ça devient un peu verbeux (plus de caractères même qu'en LaTeX ou groff où on aurait pu définir quelque chose comme\pathname{/etc/}— 2 symboles en moins).