Cahier refonte des métadonnées

Informations épinglées

• Pour l'avancement du chantier, voir le milestone concerné.

Description

Le volet des métadonnées actuel est lié à l'éditeur de texte. Il est généré à partir d'un JSON que l'on peut trouver dans les sources de Stylo.

Ce Wiki décrit les modifications que l'on souhaite appliquer au volet des métadonnées. On distingue deux usages pour cette fonctionnalité : les métadonnées d'un article dans l'éditeur de texte et les métadonnées d'un corpus.

Objectifs de la refonte

• Faire du volet métadonnées un composant à part entière (on pourra le réutiliser ailleurs comme dans les corpus)
• Rendre le volet des métadonnées plus dynamique :
  • Plutôt que d'avoir un volet qui contient toutes les métadonnées il faudrait pouvoir le peupler en fonction d'un scénario particulier (ex: article de revue, chapitre de livre, chapitre de thèse, document)
  • Laisser aux usagers la possibilité d'ajouter un champ YAML personnalisé (ex: avec un formulaire contenant deux champs, clef:valeur) et indiquer que ce champ-là ne sera pas traité par l'export
  • Arrimer différentes API pour préremplir les valeurs de clé (ex: quelle autorité choisir pour les tags ?)
    • Il faut identifier les API que l'on peut utiliser (ex: Isidore)

Changements d'interface

suite à une discussion Roch-Maïtané :

• Créer un écran dédié au remplissage des métadonnées
  • le volet de droite à l'intérieur d'un document Stylo n'existera plus
  • (court terme) on rajoute au niveau des icônes Supprimer / Dupliquer / Envoyer etc… une copie de la page Articles ou Corpus une icône pour accéder à l'écran des métadonnées (sûrement une page dédiée sauf si contre-indication)
  • (long terme) refondre cette zone ^
• Travail ergonomique de mise en page / simplification /mutualisation (?) des formulaires existants sur ce nouvel écran

Work in Progress

• Les différents scénarios pour l'éditeur de texte sont en cours de finalisation (la priorité est pour le scénario "article de revue")

TO DO priorisée

1. mettre à jour l'infrastructure pour qu'on puisse implémenter le reste → le masque s'adapte à un modèle de scénario donné quelque part:
   • 4 templates yaml prédéterminés:
     • article de revue
     • chapitre de livre
     • chapitre de thèse
     • documents (travaux étudiants, propal, billets, notes de réunion, etc)
       • faire des exemples selon nos usages @all
   • créer un template yaml custom
   • ajout d'un masque clé:valeur
2. standardisation du yaml par défaut article de revue
3. arrimage à des API pour préremplir des valeurs de clé (voir par exemple #372
   • la clé est fixe d'une revue à l'autre, mais la liste des valeurs possibles s'adapte
   • Isidore
   • API adhoc (mapping vers un fichier json ou api)
4. versionner les métadonnées
5. mettre en place le système de métadonnées pour les corpus
6. dans un second temps on travaillera sur les métadonnées pour les corpus.

Les problèmes à résoudre

• #979 Intégrer le multilinguisme au volet des métadonnées
• #982 Le blocage des articles si le raw YAML n'est pas conforme avec le schéma de données
• #453 Sélectionne le modèle de métadonnées

Rétro-calendrier:

1. Réaliser le nouveau composant des métadonnées avec le choix d'un seul scénario possible (l'article de revue)
2. Tester le nouveau composant sur sa branche (ce sera aussi l'occasion de vérifier la sélection de métadonnées, tous les exports doivent être testés)
3. Créer de nouveaux scénarios (il faudrait qu'on puisse avoir la main pour créer ces scénarios, on passera par git + review pour les faire valider)
4. Tester les nouveaux scénarios sur la branche de dev (ces tests conditionneront aussi les scénarios de métadonnées pour les corpus)
5. Validation et déploiement en pre-prod
6. Tests en preprod
7. Validation et déploiement en prod (Stylo 3.1 ?)
8. Intégration du nouveau composant métadonnées dans la fonctionnalité corpus avec un seul scénario possible (le dossier de revue)
9. Tester avec tous les exports possibles sur la branche de dev
10. Créer de nouveaux scénarios pour les corpus (livres, thèse, etc)
11. Tester les nouveaux scénarios sur la branche de dev
12. Validation et déploiement en preprod
13. Tests en preprod
14. Validation des tests et déploiement en prod (Stylo 3.1.2 ?)

Compte-rendus des discussions

Point du 17 septembre 2024

Tout d'abord le rétro-calendrier a été validé, nous commençons les développements de cette refonte avec un seul scénario : l'article de revue. Les autres scénarios seront ajoutés dans une seconde phase.

Les besoins nécessaires au lancement du chantier sont :

• Finaliser le scénario sur les articles en ajoutant les noms techniques (les clefs yaml) et les types de données qu'elles se verront affectées (des chaînes de caractères courtes ou longues, des entiers, des dates, etc.). Le ticket #1019 répond à ce premier besoin.

Plusieurs points d'attention ont été soulevées pendant la discussion : 

• Les métadonnées sont directement liées aux exports, en conséquence il faudra faire attention à ce que 1) la refonte soit toujours compatible avec les feuilles de transformations et 2) la refonte soit rétrocompatible avec tous les articles existant dans Stylo (puisque les métadonnées YAML sont entrées comme du texte dans la base)

• Toutes les métadonnées liées aux articles et au dossier de revue seront gérées depuis le document Stylo (comme c'est le cas actuellement). Il faudra 1) penser des mécanismes pour faire remonter certaines informations au niveau du corpus (exemple, le titre du dossier) et 2) Faire attention que le formulaire des métadonnées ne soit pas une liste d'entrée infinie dans laquelle seul le scroll permet de circuler (ce qui est le cas actuellement).

• Les scénarios de métadonnées doivent être modifiable par l'équipe de la Chaire (en respectant le protocole de modification via github, on ne pousse par sur main sans relecture)

• Il nous manque une entrée dans les métadonnées au niveau des mot-clés. Nous devons ajouter une entrée "catégorie" de mot-clef, voir le ticket #1020

• Guillaume a posé la question de l'emplacement du choix de scénario de métadonnées dans Stylo, est-ce que le choix est fait lors de la création d'un document Stylo ou dans le mode édition d'un document ? (réponse donnée serait a priori dans le mode édition mais ça peut changer ?)

• Roch a demandé s'il est envisageable de changer de scénario de métadonnées en cours d'écriture (exemple, transformation d'un article en chapitre de thèse). La réponse n'est pas évidente, proposition d'empiler les scénarios quitte à les différencier avec un préfixe.

• Rappel du besoin de laisser la possibilité à un utilisateur d'ajouter une clef yaml personnalisé dans le formulaire. Néanmoins, l'informer que cette clef ne sera pas traitée lors de l'export (elle sera cependant présente dans les sources).

• Marcello a demandé s'il ne faudrait pas penser dès maintenant au stockage des métadonnées en base dans MongoDB (plutôt qu'en texte) et lier les deux chantiers. Guillaume a répondu que ce n'était pas urgent et qu'on pouvait les dissocier.

Point du 1er octobre 2024

Au cours de l'atelier et de la réunion, nous avons abordé 3 axes de Stylo :

• Le chantier des métadonnées
• La refactorisation de la preview HTML (en termes d'architecture du code)

À propos du chantier des métadonnées:

Nous avons proposé de redécouper le chantier des métadonnées en plusieurs étapes. Chacune de ces étapes pourra faire l'objet d'une version avant de passer à la suivante.

Nous avons proposé de découper le chantier comme suit:

1. Résolution du bug du RAW YAML, voir le ticket #982 et la pull request #1029 qui répare ce problème.
2. Création d'un composant "Métadonnées" dans Stylo (détacher le volet des métadonnées de l'éditeur et en créer un à part). On pourra effectuer des tests à ce moment-là dans la partie éditeur pour vérifier que tout fonctionne bien (en cours)
3. Créer un bouton d'action pour éditer les métadonnées (ce bouton d'action pourra être inséré dans le gestionnaire d'articles, par exemple, pour appeler seulement le volet de métadonnées de l'article et les rendre accessibles en écriture sans avoir à entrer en mode édition)
4. Créer un document selon un modèle de document (en fonction des scénarios, voir le méta-ticket #1021 listant tous les scénarios de métadonnées que nous avons préparé). À cette étape, nous donnerons priorité au scénario 'article de revue', en particulier sur la compatibilité avec les différents exports. Dans la continuité de ce qui est déjà disponible dans Stylo, nous pourrions distinguer les métadonnées saisies par l'auteur de celles saisies par l'éditeur (et ainsi distinguer différents cas d'usages spécifiques, exemple : export Sens Public, export TEI Commons Publishing)
5. Créer un document en fonction du type de publication (chapitre de livre, chapitre de mémoire/thèse, article de revue, billet de blog, note de réunion, etc.)

Tout au long de la semaine, le ticket #1019 a fait l'objet de discussions que nous pouvons résumer comme suit.

• L'architecture des données actuelle en YAML dans Stylo peut être modifiée et adaptée pour être plus concise et mieux structurée (en déplaçant par exemple le champ titre traduit comme un sous-champ du titre). C'est une étape quasiment nécessaire surtout si on transforme les données dans MongoDB en entrées de la base et plus seulement en texte (on peut rendre les données accessibles aux requêtes GraphQL de cette manière). Le point d'attention de cette restructuration sera la rétrocompatibilité avec les anciens articles dans Stylo. Les articles existant doivent toujours fonctionner.

• Le fonctionnement de Pandoc permet de baliser les valeurs affectées aux clés YAML en Markdown. Certaines métadonnées comme le titre font l'objet d'une fonction strip-markdown() pour supprimer la structuration Markdown et ne garder que le texte brut. @Guillaume fait la remarque que ce comportement peut avoir des effets indésirables en termes d'usage si ce n'est pas indiqué à l'utilisateur.

À propos de la refactorisation de la preview HTML

Le template de la preview HTML des articles était depuis les débuts de Stylo sur un dépôt framagit. Pour l'appeler, Stylo devait cloner tout le dépôt pour ne récupérer que quelques fichiers. @Thomas s'est occupé de rapatrier le template dans le dépôt Github, voir la pull request #1022. Ce changement a également été l'occasion de rattacher la génération de la preview à la pandoc-api et de supprimer une version de Pandoc encore intégrée à Stylo (le poids de Stylo a diminué d'1Go).

En conséquence, l'installation d'une instance de Stylo est plus légère et ne nécessite plus de sous-module (pour récupérer le template de la preview).