Journal AsciidoctorJ et extensions

Posté par  (site web personnel) . Licence CC By‑SA.
Étiquettes :
15
3
août
2024

Bonjour Aoutien•ienne,

La façon dont nous utilisons Asciidoc dans nos projets peut susciter l’intérêt chez certains d’entre vous, je voudrais partager ici cette expérience.

Asciidoc est proche du Markdown. Dans les grandes lignes, les 2 répondent aux mêmes besoins. Mais à l'usage, on peut différencier Asciidoctor de Markdown :

  • Syntaxe pouvant plus facilement s’inclure récursivement (tableau qui contient des tableaux qui contient des exemples, par exemple…) ;
  • Fonctionnalité bien plus riche par défaut, et homogène à travers les diverses implémentations ;
  • Syntaxe des tableaux plus agréables ;
  • Beaucoup d’extensions présentent par défaut ;
  • Facile à étendre

Nous utilisons AsciidoctorJ , il s’agit d’une implémentation Java, qui propose une API pour accéder à la structure du document et étendre simplement le langage.

Les extensions sont portables binairement, elles peuvent soit s’exécuter en ligne de commande ou soit s'intégrer dans un IDE.

Nous avons développé 2 extensions, qui sont décrite dans la page de l’application Intercom. L'une permet d'ajouter des slides dans une page (voir le menu news, l'autre, de lister des objets dans un Intranet (développé via notre Framework).

Nous utilisons un driver JDBC pour accéder au modèle de données de notre application. On utilise un petit langage dérivé du SQL (le TQL) pour créer un dataset, et un autre langage pour spécifier la présentation des données.

select                              
    u.rawImg,
    u.username,
    u.manager.username as manager
from User u
where u.dateCreated > '2024-01-01' and
    u.manager.username = 'admin';
--                                 
table rawImg as "Pic",
      username as "Name",
      manager as "Manager"

L’avantage de parser les requêtes est de valider l’accès aux données et d'améliorer le rapport d’erreur lors de la traduction de la requête. De plus, un bénéfice par rapport au HQL / SQL, est de  donner accès aux getters des classes mappées qui ne sont pas en Db.

Sans aller aussi loin qu’un Jupyter notebook, on peut déjà faire bien des choses de façon portable. L'intégration d'Asciidoctor est accessible dans la version Opensource d'Intellij.

  • # extensions et api

    Posté par  (Mastodon) . Évalué à 4 (+1/-0). Dernière modification le 07 août 2024 à 07:59.

    Est-ce que les extensions que vous avez écrites sont utilisables aussi avec les processeur asciidoctor en ruby et javascript ou ça demande une réécriture dans les langages concernés?

    Github est dans les chou et je ne connais le language asciidoc que "de loin", du coup je ne me représentes pas vraiment comment est écrit une extension asciidoc.

    • [^] # Re: extensions et api

      Posté par  (site web personnel) . Évalué à 2 (+1/-0).

      On peut exécuter le processeur ruby sur la jvm, donc il est possible d'utiliser les extensions ruby avec AsciidoctorJ et vice versa.

      Je ne sais pas pour JavaScript. Mais nous sommes entrain d'implémenter un éditeur wysiwyg en JavaScript (kotlinjs). L'implémentation fera que le serveur s'occupera du rendu, le JavaScript juste d'interroger le serveur.

  • # Respect de la norme

    Posté par  . Évalué à 1 (+4/-5).

    "Aoutien•ienne"

    Je sais bien que c'est à la mode d'utiliser les points médians mais si tu veux pas passer pour une truffe, il faut essayer de respecter la norme (ISO69064 - Activisme pseudo paritaire dans le discours courant - Méthodes et usages).

    Premier point, il faut utiliser le "point médian catalan" (et pas le premier truc qui ressemble comme le U+2022 Bullet Unicode Character).
    Le point médian (appelé punt volat en catalan) se place exclusivement entre deux ‹ l › ou deux ‹ L › en capitales. C'est un peu de l'appropriation culturelle de s'en servir pour faire de l'activisme pseudo paritaire mais pourquoi pas. L'avantage majeur que j'y vois est que si tu passes ton clavier linux en "Français Catalan", le point médian (catalan) est accessible très simplement.

    Deuxième point, tu as essayé de proposer une césure quelque part mais ce n'est pas clair. Je soupçonne que tu voulais écrire "Août•ien•ienne" ou l'on trouve une racine, puis un segment pour le masculin, puis un segment pour le féminin. Why not, mais tu peux faire plus court, "Aoûtien•ne" est accepté par la norme. A mon goût, c'est pas terrible "Aoûtien et aoûtienne" est beaucoup souple. "Aoûtienne et aoûtien", bien qu'un peu daté, sera accepté aussi.

    En conclusion, le langage est basé sur des conventions, ce qui permet de se comprendre. Je maintiens un bout de code qui désinclusifie les pages web pour quelqu'un qui en a besoin (ben oui, nos petites conneries, ça maintient des gens en dehors de nos discussions), et tous les trois mois, une nouvelle invention fais des pattes de mouches du coté de mes gentils utilisateurs.

    • [^] # Re: Respect de la norme

      Posté par  . Évalué à 9 (+7/-0).

      Vraiment j'essaie d'utiliser un langage épicène mais à chaque fois que je lis un commentaire comme le tiens, ça ne fait que me donner un peu plus envi d'y passer. Oui c'est de la réactance oui c'est con, mais par exemple mon commentaire comme le tiens n'utilisent pas les bonnes guillemets (simples comme double) est-ce que tu en chie une pendule pour autant ? D'ailleurs tu n'utilise pas d'espace fine insécable là où c'est conventionnel, tu as un usage guillemet en chevron simple qui ne respectent aucune typographie, les absences d'accent circonflexe, les absences d'accent sur les majuscules, l'utilisation de l'anglais à tout bout champ, un usage de la ponctuation aléatoire,… Et tu semble être prêt à accepter des modification de la norme comme la négation double.

      Bref au milieu d'un gros paquet de manquement à la norme qui permet d'être compris, il y en a une seule qui gène et tu semble plus insister sur la valeur politique que sur de véritables aspects grammaticaux.

      https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll

    • [^] # Re: Respect de la norme

      Posté par  (site web personnel) . Évalué à 3 (+2/-0). Dernière modification le 15 août 2024 à 10:43.

      Je ne connaissais pas l'existence de cette norme. Je suis pour la suppression du genre, ce sera moins moche et nettement plus simple.

      Je suis dyslexique, ambidextre, donc je me pardonne. Donc les normes illogiques, je ne peux les suivent, c'est dans ma nature.

    • [^] # Re: Respect de la norme

      Posté par  (Mastodon) . Évalué à 2 (+1/-2).

      On peut aussi admettre qu'on a compris qu'il s'adressait à tout le monde et ne pas se comporter comme un taliban.

    • [^] # Re: Respect de la norme

      Posté par  . Évalué à 1 (+1/-2).

      Je maintiens un bout de code qui désinclusifie les pages web

      Ça m'intéresse, vu qu'un certain nombre de méthodes utilisées à tendance à surcharger les textes et a les rendre très pénibles à lire.
      Du coup en général je regarde la densité du bruit et mets ça dans la balance avec, de l'autre côté, l'intérêt potentiel, et je règle la sensibilité en fonction de mon ennui. Selon le résultat, je me juste barre ou je fais un effort, le plus fréquent étant que je me barre.

      Bon, dans le cas de ce journal, c'était pas franchement gênant, par contre. La preuve, j'ai lu.

      Bref, un lien à partager du coup?

    • [^] # Re: Respect de la norme

      Posté par  . Évalué à 0 (+1/-3).

      Je maintiens un bout de code qui désinclusifie les pages web

      Ça m'intéresse, vu qu'un certain nombre de méthodes utilisées à tendance à surcharger les textes et a les rendre très pénibles à lire.
      Du coup en général je regarde la densité du bruit et mets ça dans la balance avec, de l'autre côté, l'intérêt potentiel, et je règle la sensibilité en fonction de mon ennui. Selon le résultat, je me juste barre ou je fais un effort, le plus fréquent étant que je me barre.

      Bon, dans le cas de ce journal, c'était pas franchement gênant, par contre. La preuve, j'ai lu.

      Bref, un lien à partager du coup?

Envoyer un commentaire

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.