Bonjour,
Comme annoncé sur le Grimoire-Command.es (https://www.grimoire-command.es/2019/asciidoc_quickdoc_in_french.html#_version_fr ) le sous-ensemble « quickdoc » de la documentation officielle d’AsciiDoctor a été traduit en français (par des bénévoles de Gebull.org dont je fais partie).
Dans l’attente de la publication de cette traduction par l’équipe du projet, il est possible de la consulter en ligne sur Framagit :
https://framagit.org/Siltaar/asciidoctor-docs-fr
Le travail peut être complété et mis à jour si vous souhaiter y contribuer.
En attendant, puisque Framagit sait interpréter le format AsciiDoc, il est agréable de lire cette version de la documentation directement depuis le dépôt de code.
# Langage intéressant mais certains trucs me chiffonnent
Posté par anaseto (site web personnel) . É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).[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par bepolymathe . Évalué à 1.
Comment intéressant anaseto (comme d'hab). D'ailleurs, quid de Frundis ?
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par anaseto (site web personnel) . Évalué à 4. Dernière modification le 28 novembre 2019 à 15:25.
Les points que je soulève (abstraction sémantique et messages d'erreurs) sont effectivement des points que j'ai eu en tête en créant Frundis, me souvenant de mes aventures avec LaTeX, pandoc, EPUB et surtout mandoc(1), ma plus grande source d'inspiration au sujet des messages d'erreur.
Ceci dit, Frundis n'est pas un langage pour écrire de la doc technique, donc ce n'est pas vraiment comparable : la doc de Frundis est en mdoc(7) d'ailleurs, évitant le piège classique consistant à utiliser son propre langage lorsqu'il y a un outil plus adapté :-) Par contre, pour des textes pas suffisamment spécifiques pour justifier l'utilisation d'un outil spécialisé (tutoriel oui, page man non) et pas trop demandants (genre sans équations ou figures et tableaux complexes) ou de simples pages web (je fais ça pour une bonne partie de mon site statique) ça fait bien l'affaire, et c'est plus facile à maintenir que du markdown et moins verbeux que du html.
Après, s'il n'y a pas de solution évidente rien n'empêche bien sûr d'expérimenter. J'ai écrit une thèse d'info avec après tout. Mais ça demande de définir de nouvelles balises techniques pour les différents formats que l'on veut, c'est potentiellement du travail pour réussir à abstraire tout ce qu'on veut (quand c'est possible). Du coup, j'avais défini des balises que pour l'export LaTeX en l'occurrence (facile), perdant une bonne part de l'intérêt de Frundis (export multi-format), profitant au final juste de messages d'erreur moins brutaux que LaTeX et une syntaxe que je préfère, car moins d'accolades et qui s'harmonise mieux avec grep et diff.
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par bepolymathe . Évalué à 0.
Oui c'est vrai que tout dépend l'usage. De mon côté, je suis complétement passé sur org-mode pour rédiger l'ensemble de mes documents. La simplicité du balisage couplé l'environnement d'outils que permet Emacs (spacemacs dans mon cas) me comble.
Par contre, je reconnais qu'il y a des lourdeurs en terme d'écriture. Si on veut mettre une citation dans un document…
… mais par contre la gestion des tableaux et notes de bas de page est royal.
En tout cas, je trouve passionnant ces discussions autour des langages même si je suis pas dans le milieu de l'informatique.
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par anaseto (site web personnel) . Évalué à 2.
Pour ceci Frundis n'est pas le langage à choisir a priori par contre, car assez dépourvu par défaut : ça fait partie des trucs pour lesquels j'ai dû définir des balises enrobant du LaTeX lorsque j'ai écrit ma thèse. Après, tout dépend aussi de chacun (comme je maîtrise bien l'outil et sait l'étendre assez facilement, je serais tenté de l'utiliser dans plus de cas).
En même temps, c'est pas forcément les informaticiens qui vont être intéressés par un langage de balisage donné. La personne qui utilise le plus Frundis (en gros, tous les jours depuis plusieurs années), c'est pas moi mais une écrivain (ma sœur) ayant suivi une formation littéraire, et qui a d'ailleurs fait une présentation au CDL il y a peu (par contre, on voit pas bien les slides dans la vidéo, ils sont disponibles ici aussi).
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par bepolymathe . Évalué à 0.
Merci pour le partage de la vidéo. C'est éclairant pour son usage. La gestion des références croisées et d'une vaste bibliographie est par contre une nécessité pour moi. Il faudrait que je m'amuse un peu avec.
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par barmic 🦦 . Évalué à 1.
C'est un point sur le quel j'avais beaucoup aimé feu-txt2tags.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par anaseto (site web personnel) . Évalué à 2.
Tu dis feu-txt2tags, le langage est vraiment mort ou fini ?
Si je me souviens bien, c'est un langage très orienté regexp et extension via substitutions textuelles, filtres et/ou pipes ? Ça a le mérite d'être une approche simple, même si question fiabilité et précision des messages d'erreurs du coup, c'est a priori difficile. Et c'est probablement lent mais ça c'est rarement important, je réagis juste au very fast sur le site comme si c'était particulièrement rapide pour un langage de balisage ;) (peut-être comparé à pandoc ou autre programme pas super rapide).
[^] # Re: Langage intéressant mais certains trucs me chiffonnent
Posté par barmic 🦦 . Évalué à 1.
Je pense qu'il se veut plus simple que rapide. Je parle simple dans son fonctionnement plus que dans son utilisation. Les substitutions font partie du document source ce qui le rend auto-porté, txt2tags tiens dans un seul script python (c'était une bêtise amha), etc
Il est effectivement mort, je crois qu'une version était en chantier mais n'a jamais vu le jour.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.