en-têtes markdown

[revolunet]

Bonjour,

A propos des en-têtes de markdown, ne serait-li pas "mieux" de les mettre dans le "front matter", soit l'en-tête conventionnelle des fichiers markdowns au format yml ? Cela permet de séparer le contenu brut des textes des metadatas, et de pouvoir requêter sur celles-ci

merci

[Seb35]

Complètement d’accord de mettre les métadonnées d’en-tête ailleurs que dans le fichier lui-même.

Sur l’endroit où mettre ces métadonnées, je ne connaissais pas les en-têtes yaml ; si je comprends bien, c’est plus spécifiquement la variante MultiMarkdown avec ici la syntaxe des métadonnées.

Si c’est bien cela dont tu parles, je serais d’accord de changer le format par défaut de "markdown" à "multimarkdown" pour mentionner proprement la variante de Markdown. Dans ce cas, la seule différence entre "markdown" et "multimarkdown" serait la présence ou non de cet en-tête ; il faut noter que cela ne doit être que dans la version "--organisation=fichier-unique", les organisations "par articles" (1 fichier = 1 article) ne sont pas concernées.

Si tu veux proposer une PR, je pourrai la reviewer.

[revolunet]

Je ne sais pas si c'est vraiment "MultiMarkdown" (Github supporte les entetes yaml)

Voici ce que ça peut donner :
https://github.com/vkbansal/FrontMatter/blob/master/test/resources/yaml.md

Je n'ai pas compris le souci pour --organisation=fichier-unique mais je creuse :)

[Seb35]

Merci pour l’exemple, c’est effectivement pas mal. Pour le dialecte de Markdown, j’ai l’impression que les différentes extensions partent tellement dans tous les sens que ça devient difficile d’attribuer à tel ou tel variante les fonctionnalités, après vu que c’est du texte brut il y a aucun risque de non-compatibilité (au pire un moteur de rendu affiche le texte brut).

Sur "organisation = fichier unique", c’est qu’il y a actuellement deux types d’organisations : mettre tout le texte dans un seul fichier (exemple ou sur le site web) ou mettre un fichier par article (exemple, c’est le format attendu pour Amenda). Je suis en cours de réorganisation du code d’Archéo Lex pour mieux séparer les différentes variantes dans le format de sortie, ces deux types d’organisations de fichiers en font partie.

PS : voir aussi le calendrier des 2 prochaines semaines, je suis sur Paris jusqu’au 8 mars, si tu es intéressé pour venir au Bureau ouvert et/ou au séminaire à Sciences Po.

[Seb35]

Depuis un mois, les dépôts créés par Archéo Lex peuvent contenir plusieurs "versions" du texte : texte dans un seul fichier ou à raison d’un article par fichier ; et de plus je pense qu’il serait préférable d’inscrire quelque part les versions calculées, la date de dernière mise à jour, des métadonnées comme l’identifiant LEGITEXT (que je cherche tout le temps car il n’est pas dans les dossiers Git) ou d’autres.

Je pense qu’utiliser cette proposition d’en-tête peut être une bonne solution, et de mettre celui-ci dans une référence Git, par exemple refs/meta. De telles références Git sont déjà utilisées par d’autres sur-couches de Git (je connais Gerrit qui fait ça).

Je suis pas convaincu qu’il faille mettre cela en en-tête du fichier car d’une part certaines versions n’ont pas d’en-tête (un article par fichier) et d’autre part cela change les numéros des commits Git alors que j’aimerais qu’ils soient le plus canonique possible (par exemple il y avait auparavant la date de la base LEGI dans le champ Committer des commits, mais cela rendait les numéros de commits différents selon la date à laquelle on calcule le texte, c’est désormais terminé).

[revolunet]

merci pour les récents travaux 🎉

pour refs/meta : est-ce que ce sont des données associées à un "commit" ? si oui comment gérer les métas sur des fichiers en particulier ?

[Seb35]

Maintenant que c’est en prod, je vais prendre plus de temps pour améliorer le fond, et cette issue servira à améliorer la traçabilité et la maintenance des dépôts sur le long terme.

Pour les références Git, on peut en créer un peu comme on veut. Pour refs/meta, je viens de vérifier dans Gerrit (ici par exemple) et c’est plus précisément refs/meta/config qui est utilisé. En fait, le nom de la référence dépend surtout de ce qu’on veut en faire, mais je verrais bien une référence refs/meta unique contenant les métadonnées au format YAML, un peu comme dans l’exemple donné mais dans un fichier séparé.

Pour l’affichage en tant qu’en-tête des métadonnées, tu y tiens vraiment, par exemple pour faire des dépôts qui rendent bien sur GitHub ? ou est-ce que la solution de mettre ces métadonnées dans une référence séparée te convient ? Ça m’est un peu égal, mais ça ferait 2 issues un peu différentes (personnellement la référence séparée m’intéresse, mais si tu veux l’en-tête ça peut être une autre variante).

Sur ta question "associé à un commit", dans mon esprit la référence sera globale, mais Git contient en standard les "notes Git" permettant d’associer une note à un commit, et certaines interfaces peuvent proposer d’afficher ces notes. Voir man git-notes, ça peut être une option intéressante pour certaines choses - j’ai pas d’idée comme ça mais ça a du potentiel.

[revolunet]

Hello

Les metas pourraient être dans un fichier séparé, tant qu'on garde un lien avec le fichier et qu'elles sont versionnées... ca évitera de "polluer" l'en-tête avec des infos techniques.

A ce moment là pourquoi ne pas utiliser un fichier yaml dédié commité dès que les metas changent ?

[Seb35]

Le problème de mettre le fichier YAML (ou tout autre fichier comme un README) dans le même commit que le texte est que ça change le numéro du commit, et donc si on met des données susceptibles d’être différentes d’une exécution à l’autre (par exemple la date de dernière exécution), ça va changer les numéros de commits et c’est pas pratique. Maintenant que les dépôts générés par AL ont des numéros de commit "canoniques" (=sont reproductibles tant que le texte reste le même), je trouve ça tellement bien que je suis assez réticent à changer ce comportement.

En fait ce qui serait bien serait que les interfaces web Git proposent d’afficher un README venant d’une autre branche/référence, mais ça va être difficile de proposer ça à GitHub ou Gitlab -- en fait un peu comme GitHub fait avec les sites dans gh-pages.

J’ai travaillé ce week-end à créer un meta.yaml dans une référence refs/meta qui ressemble à ça :

titre: "code des instruments monétaires et des médailles"
nature: code
état: vigueur
id: LEGITEXT000006070666
cid: LEGITEXT000006070666
éditorialisation:
  nb-versions: 1
  dernière-date: 2018-09-20
vigueur:
  promulgation: null
  début: 1952-06-29
  fin: null
  actuelle: 2009-05-14
  future: null
statistiques:
  nb-versions-vigueur-actuelle: 13
  nb-versions-vigueur-future: 0

Et j’ai commencé à utiliser ça dans l’interface web archeo-lex.fr (en local sur mon ordi pour l’instant) pour trier la liste des codes par dernière entrée en vigueur (un classement parmi d’autres, mais je pense que c’est un classement utile pour de la veille juridique). En fait au-delà d’un meilleur suivi des repos, ça peut permettre aussi de faire une interface web puissante, par exemple qui peut trier les codes selon leur dernière entrée en vigueur, montrer ceux qui sont abrogés, etc. y compris dynamiquement en JavaScript (disons que c’est possible en JS pour les codes car il y en a peu, ça n’est plus vraiment possible pour les lois (3000) ou a fortiori les décrets et arrêtés où il faut des interfaces de recherche).

[Seb35]

Bon, après, je mets le fichier dans refs/meta, mais ce n’est pas pratique car, par défaut, Git ne télécharge que les branches (refs/heads/*) et il faut batailler pour avoir les autres références. De ce que j’ai trouvé, il faut "git clone" puis modifier la config remote.origin.fetch pour retirer "heads" puis "git fetch origin", ou alors "git clone --mirror" mais dans ce cas on n’a pas un repo "bare" et il faut le transformer en "non-bare", ce qui n’est pas trivial (ça se fait mais ça n’est pas pratique).

Du coup, je me pose la question de faire une branche "meta" pour avoir accès plus facilement à ce fichier.

[revolunet]

Merci Seb.

Pour le problème des commits canoniques, si les métadonnées sont stables, ca devrait être bon, mais je ne suis pas sûr qu'il faille intégrer ici de métadonnées "calculées" (comme éditorialisation et statistiques) ?

Au final, je me dis que le plus simple serait encore de mettre ces données dans l'en-tête du markdown, avec une option du CLI pour générer ou pas ces en-têtes. Les commits seraient alors canoniques dans chaque version (avec ou sans metadata).

L'intérêt que j'y vois c'est que ces en-têtes pourraient servir pour ajouter du contexte et "naviguer" dans les textes. (dans le cas d'un export "article par article")