Documentation de Cosma

Cosma est un logiciel de visualisation de graphe documentaire. Il permet de représenter des notes interreliées sous la forme d’un réseau interactif dans une interface web. Le logiciel est conçu pour fonctionner avec des fichiers texte en Markdown et s’adapte aussi bien à une petite collection (centaine de documents) qu’à une vaste documentation (jusqu’à plusieurs milliers de documents).

Cosma est développé dans le cadre du programme de recherche ANR HyperOtlet.

1 Présentation

Cosma est un logiciel de visualisation de graphe documentaire. Il permet de représenter des notes interreliées sous la forme d’un réseau interactif dans une interface web. Cosma n’est pas lui-même un logiciel de prise de notes : il est pensé pour fonctionner en complémentarité avec ces logiciels et nécessite que les notes soient structurées suivant un format bien précis.

La plupart des outils de visualisation concentrent leurs fonctionnalités dans une application à interface graphique, à partir de laquelle il est possible d’exporter des données structurées ou des images statiques. Cosma inverse cette logique : la partie application, surnommée cosmographe, est un simple formulaire de création, et c’est l’export, un fichier HTML surnommé cosmoscope, qui constitue la véritable interface de visualisation. Ce fichier autonome contient un graphe interactif, des outils de navigation interne (index, moteur de recherche, filtres) et le texte intégral des fiches ; il inclut aussi les données sources au format JSON et peut être utilisé hors connexion.

Cosma est conçu pour laisser un degré élevé de contrôle à ses utilisateurs.

Premièrement, le logiciel fonctionne avec un répertoire de fichiers au format texte qu’il se contente de lire : utiliser ou désinstaller le logiciel n’altérera pas vos fichiers et vous permet donc de mettre en œuvre les pratiques de stockage, de versionnement et d’édition de votre choix. De cette manière, si le logiciel s’envole les données restent.

Deuxièmement, de nombreux éléments d’interface sont personnalisables : algorithme de dessin de réseau, couleurs des nœuds, tracé des liens, raccourcis vers des vues particulières, etc.

Troisièmement, des enrichissements documentaires (métadonnées) et sémantiques (qualification des liens) sont possibles et se font par des mécanismes génériques : l’utilisateur est libre d’appliquer les typologies et ontologies de son choix.

Et quatrièmement, Cosma est un logiciel qui se veut modulaire, interopérable et portable mais surtout libre : le code est public, son développement est documenté, il est accessible et réutilisable gratuitement sous licence MIT. Le travail peut ainsi être évalué, archivé et continué par d’autres.

2 Installation

2.1 Pré-requis

Installez Node.js version 12 ou supérieure.

Utiliser le cosmoscope nécessite un navigateur web. Vous pouvez utiliser les navigateurs suivants, dans la version indiquée ou supérieure :

Le cosmoscope n’est pas compatible avec Internet Explorer.

2.2 Téléchargement

Téléchargez le dépôt git de Cosma en saisissant les commandes ci-dessous dans un terminal, ou en cliquant sur le lien suivant : https://github.com/hyperotlet/cosma/archive/master.zip

git clone https://github.com/hyperotlet/cosma.git

2.3 Installation des dépendances

Le fonctionnement de Cosma repose sur d’autres programmes qualifiés de dépendances. Cosma utilise le gestionnaire de dépendances NPM qui est installé en même temps que Node.js. Installez les dépendances nécessaires au bon fonctionnement de l’application avec la commande ci-dessous :

npm install --only=production

3 Configuration

Cosma utilise un fichier de configuration au format YAML. C’est une liste hiérarchisée de paramètres dont les valeurs modifient le comportement du logiciel.

Pour une introduction à YAML, cliquez ici. Dans le contexte de Cosma, il est notamment important de savoir qu’en YAML la hiérarchie des paramètres est mise en œuvre par l’indentation, c’est-à-dire la présence d’espaces en début de ligne, et que l’utilisation de tabulations pour indenter les lignes est interdite en YAML. Il est recommandé de choisir une unité d’indentation correspondant à un multiple de 2 espaces (2 ou 4) et de s’y tenir pour tout le fichier.

Exécutez la commande suivante pour créer le fichier de configuration (config.yml) s’il n’existe pas déjà. Vous pouvez aussi le supprimer et utiliser cette commande pour réinitialiser le fichier. Le fichier généré par cette commande est un modèle des paramètres qui doivent obligatoirement être renseignés pour une configuration valide.

node app config
node app c

3.1 Paramètres nécessaires

La configuration doit contenir les paramètres suivants.

files_origin
Chemin du répertoire contenant les fichiers Markdown à lire.
Exemple : /Users/user/Fiches/', D:\repertoire\
export_target
Chemin du répertoire où exporter le cosmoscope.
Exemple : ./', D:\repertoire\

Les chemins files_origin et export_target doivent obligatoirement se terminer par une barre oblique.

record_types
Liste des types de fiches. Chaque type est défini par une paire nom: valeur dans laquelle nom correspond au nom du type et valeur correspond à une couleur de votre choix. Les couleurs sont déclarées comme en HTML avec leur nom prédéfini ou bien une valeur RGB, HEX, HSL, RGBA ou HSLA entre guillemets.

Exemple :

record_types:
  undefined: '#546de5'
  très important: red
  fiche de lecture: 'rgba(157, 62, 12, 0.7)'
  concept: 'hsl(14, 100%, 80%)'
link_types
Liste des types de relations. Chaque type est défini par un paramètre nom dont la valeur est une liste de deux paramètres, lesquels affectent la représentation des liens dans le graphe : stroke correspond à la forme du trait et color à sa couleur. La valeur de stroke peut être simple (trait continu simple), double (trait continu double), dash (tirets) ou dotted (pointillés). Les couleurs sont déclarées comme en HTML, de la même manière que pour les types de fiches.

Exemple :

link_types:
  undefined:
    stroke: simple
    color: grey
  spécial:
    stroke: dash
    color: 'rgba(157, 62, 12, 0.7)'

Le type par défaut undefined doit obligatoirement être défini, que ce soit pour les types de fiches ou pour les types de liens.

La configuration des relations a une incidence sur leur lisibilité au sein du graphe. Dans l’exemple suivant, l’utilisateur a défini trois types de liens qualifiés à la manière d’un thésaurus (spécifique s, générique g et associé a). Les paramètres sont définis de manière à renforcer la visibilité des liens qualifiés : les liens non qualifiés (undefined) sont en pointillés (dotted) gris (grey), tandis que les liens qualifiés sont plus lisibles, grâce à des traits plus marqués et une couleur plus vive.

link_types:
  undefined:
    stroke: dotted
    color: grey
  s:
    stroke: simple
    color: 'rgba(157, 62, 12, 0.7)'
  g:
    stroke: simple
    color: 'rgba(157, 62, 12, 0.7)'
  a:
    stroke: dash
    color: 'rgba(157, 62, 12, 0.7)'

3.2 Paramètres du graphe

Les paramètres suivants définissent la valeur par défaut des paramètres du graphe. La plupart de ces paramètres peuvent être modifiés en direct dans l’interface du cosmoscope (voir Graphe plus bas). Vous pouvez tester différentes valeurs avant de les reporter dans le fichier config.yml ; les valeurs définies dans le fichier sont rétablies à chaque rechargement du cosmoscope.

graph_config:
  background_color: white
  highlight_color: red
  highlight_on_hover: true
  text_size: 9
  position:
    x: 0.5
    y: 0.5
  attraction:
    force: -50
    distance_max: 800
    verticale: 0
    horizontale: 0
  arrows: false
background_color
Couleur de fond du graphe.
Exemple : whitesmoke ,#ccc, rgb(57, 57, 57)
highlight_color
Couleur de surbrillance des éléments mis en sélection.
Exemple : red ,#0642ff, rgb(207, 52, 118)
highlight_on_hover
Survoler un nœud le met temporairement en surbrillance, ainsi que ses connexions. Valeur : true ou false.
text_size
Taille des étiquettes des nœuds. L’unité implicite est le pixel. La valeur minimale est 5 ; la valeur maximale est 15.
position
Position horizontale (x) et verticale (y) du centre du graphe. La valeur doit être comprise entre 0 (tout à gauche) et 1 (tout à droite).
attraction
Paramètres de la simulation de forces entre les nœuds.
force : puissance globale. Plus elle est faible, plus les liens entre les nœuds sont relâchés. Une valeur inférieure à 50 tend à provoquer des collisions incessantes.
distance_max : distance maximum entre les nœuds et îlots. Au-delà de 1000, ce paramètre n’a pas d’effet mesurable. La valeur de distance_max indique également la valeur maximale effective de force. Par exemple, si distance_max: 500, alors augmenter force au-delà de 500 n’aura pas d’incidence.
verticale : force d’attraction vers l’axe vertical. Une valeur de 0 signifie que ce paramètre est désactivée.
horizontale : force d’attraction vers l’axe horizontal. Une valeur de 0 signifie que ce paramètre est désactivée.
arrows
Affichage des flèches. Permet d’obtenir un graphe orienté ou non orienté. Valeur booléenne : true ou false.

3.3 Paramètres facultatifs

Vous pouvez ajouter au fichier de configuration les paramètres suivants :

library_origin
Chemin vers le fichier JSON CSL contenant la liste des références bibliographiques. Permet d’activer la bibliographie des fiches.
minify
Réduit le poids du fichier cosmoscope.html, au détriment de la lisibilité du code source. Valeur : true ou false. Désactivé par défaut.
custom_css
Applique les styles déclarés par l’utilisateur dans le fichier /template/custom.css. Valeur : true ou false. Désactivé par défaut.
history
Exporte une copie du cosmoscope et de ses données dans un sous-dossier horodaté du dossier history. Valeur : true ou false. Activé par défaut.
metas
Liste de métadonnées ajoutées sous la forme de balises meta dans l’en-tête <head> du fichier cosmoscope.html et dans le volet « À propos ».

Exemple :

metas:
  title: Mon cosmoscope
  author: Prénom Nom
  keyword:
    - Zettelkasten
    - graphe documentaire
  description: "Répertoire de fiches en ligne"
  url: https://domaine.fr/cosmoscope.html
focus_max
Valeur maximale du focus. La valeur doit un entier supérieur ou égal à 0.
views
Liste des vues apparaissant dans la section Vues du cosmoscope. Chaque vue est définie par une paire nom: valeur dans laquelle nom correspond au nom de la vue et valeur correspond à une chaîne de caractères générée via le bouton Sauvegarder la vue actuelle du cosmoscope.

Exemple :

views:
  Graphe: eyJmaWx0ZXJzIjpbImNvbmNlcHQiXX0%3D
  Graphe (focus 2): eyJyZWNvcmRJZCI6MjAyMTAyMjExNDQ0NTF9

3.4 Modifier la configuration en ligne de commande

Les commandes suivantes vous permettent de modifier rapidement la configuration.

Générer un fichier de configuration modèle :

node app config
node app c

Modifier le chemin vers les fichiers sources :

node app import <chemin>

Modifier le chemin d’export du cosmoscope :

node app export <chemin>

Ajouter des types valides :

node app atype <nom> <couleur>

Créer le fichier de style personnalisé custom.css dans le répertoire /template :

node app css

Ajouter des vues :

node app aview <nom> <code>

4 Utilisation du cosmographe

4.1 Format de données

Cosma ne prescrit pas de logiciel d’écriture, mais son fonctionnement repose sur l’adoption simultanée de plusieurs normes d’écriture qui visent à accroître l’interopérabilité et la pérennité des données :

Cette combinaison de normes d’écriture correspond au croisement de plusieurs cultures textuelles : documentation ; wikis ; prise de notes avec la méthode Zettelkasten ; écriture académique avec Pandoc. Cosma fonctionne donc particulièrement bien lorsqu’il est utilisé en tandem avec des environnements d’écriture qui partagent cette approche, comme Zettlr ou l’extension Foam pour Visual Studio Code et VSCodium.

Pour être correctement interprétés par Cosma, les fichiers Markdown doivent donc respecter une certaine structure, et notamment la présence d’un en-tête YAML au début du fichier.

Exemple :

---
title: Titre du document
id: 20201209111625
type: undefined
tags:
  - mot-clé 1
  - mot-clé 2
---

L’en-tête YAML est délimité par deux séries de trois tirets seuls sur une ligne (---). Cosma reconnaît et utilise les quatre champs suivants :

title
Titre de la fiche. Obligatoire.
id
Identifiant unique de la fiche. Obligatoire. Par défaut, Cosma génère des identifiants à 14 chiffres par horodatage (année, mois, jour, heures, minutes et secondes) sur le modèle de certains logiciels de prise de notes type Zettelkasten comme The Archive ou Zettlr.
type
Type de la fiche. Facultatif. Une fiche ne peut être assignée qu’à un seul type. Si le champ type n’est pas spécifié ou bien que sa valeur ne correspond à l’un des types enregistrés dans la configuration sous le paramètre record_types, Cosma interprètera le type de la fiche comme undefined.
tags
Mots-clés de la fiche. Facultatif. La valeur doit être une liste. Une fiche peut disposer d’autant de mot-clés que vous souhaitez.

Conformément à la spécification YAML, la liste des mots-clés peut être inscrite en mode block :

tags:
- mot-clé 1
- mot-clé 2

Ou bien en mode flow :

tags: [mot-clé 1, mot-clé 2]

Vous pouvez ajouter des champs supplémentaires de manière arbitraire, par exemple un champ description.

Après l’entête, vous pouvez librement inscrire votre contenu.

Le rendu des fichiers Markdown sous forme de fiche HTML dans le cosmoscope est limité aux éléments textuels. Les images par exemple ne sont pas incluses et seront remplacées par leur texte alternatif le cas échéant.

4.2 Créer des fiches via le cosmographe

Vous pouvez créer un fichier Markdown conforme pour Cosma à la main ou bien en utilisant la ligne de commande. Deux options sont proposées. La première est une commande qui déclenche une saisie guidée en plusieurs étapes :

node app record
node app r

La seconde est un one-liner qui permet de créer une fiche en une seule saisie :

node app autorecord <titre> <type> <mots-clés>
node app a <titre> <type> <mots-clés>

Seul le titre est obligatoire.

4.3 Créer des liens

À l’intérieur des fiches, vous pouvez créer des liens avec l’identifiant de la fiche cible entre double crochets. Le cosmographe reconnaît ces liens et les utilise pour modéliser la structure du graphe.

Exemple :

Un lien vers [[20201209111625]] une fiche.

Vous pouvez également qualifier le lien selon la typologie indiquée sous link_types dans la configuration. Le type de lien est alors ajouté comme préfixe à l’identifiant, avec un deux-points comme séparateur.

Exemple :

Le concept B dérive du [[générique:20201209111625]] concept A.

4.4 Bibliographie

Vous pouvez intégrer des clés de citation au sein de vos fiches. Elles peuvent être enregistrées avec le logiciel de références bibliographiques Zotero puis exportées avec un identifiant unique dans un fichier JSON CSL grâce à son extension Better BibTeX. Cet identifiant peut ensuite être inséré dans vos fiches (dans le style du logiciel Pandoc), entre crochets tel que ci-dessous.

D'après les références [@ledeuffTempsHumanitesDigitales2014, 22; @perretFonctionDocumentairePreuve2020].

Vous devez cibler au sein de la configuration le fichier JSON CSL exporté avec Zotero.

library_origin: 'D:\documents\ma_bibliotheque.json'

Les commandes suivantes permettent de générer un cosmoscope en utilisant le convertisseur Citeproc intégré à Cosma.

node app modelize --citeproc
node app modelize -c

Chaque clé de citation est alors remplacée par une courte référence et une entrée dans la bibliographie.

D'après les références (Le Deuff 2014, p. 22; Perret 2020).

Bibliographie
-------------

LE DEUFF, Olivier, 2014. Le temps de humanités digitales. FYP. ISBN 978-2-36405-155-5.

PERRET, Arthur, 2020. Fonction documentaire de preuve et données numériques. Arthurperret.fr [en ligne]. 9 septembre 2020. [Consulté le 14 septembre 2020]. Disponible à l’adresse : https://www.arthurperret.fr/fonction-documentaire-preuve-donnees-numeriques.html

Vous pouvez modifier le style de citation (par défaut : ISO690-author-date-fr) en remplaçant le fichier /template/citeproc/styles.csl. Téléchargez un nouveau style depuis la base de données de Zotero.

Vous pouvez modifier la traduction des mots-clés de la notice bibliographique (par défaut : français) en remplaçant le fichier /template/citeproc/locales.xml. Téléchargez une nouvelle traduction depuis la base de donnée CSL.

4.5 Export

Pour créer le fichier cosmoscope.html, utilisez l’une de ces commandes :

node app modelize
node app m

Vous pouvez aussi obtenir une version publication du cosmoscope avec la commande suivante. Elle permet de nommer, présenter et signer votre export depuis le menu « À propos » (accessible depuis le bouton, au pied du menu de gauche). Elle y intègre les métadonnées title, author et description renseignées dans la configuration (option metas). Si elle est renseignée, la métadonnée title vient aussi remplacer le logo en haut du menu gauche.

node app modelize --publish
node app m -p

Le fichier cosmoscope.html est exporté dans le répertoire défini par export_target dans la configuration. Si le fichier existe déjà au même emplacement, il est écrasé.

Si le paramètre history a pour valeur true, un sous-répertoire horodaté est également créé dans le répertoire /history avec les contenus suivants :

Cet export facilite le partage des données et leur réutilisation dans d’autres logiciels de visualisation.

5 Utilisation du cosmoscope

Le fichier cosmoscope.html peut être lu avec un navigateur web depuis votre ordinateur. Il peut aussi être mis en ligne, par exemple déposé sur un serveur web par un simple envoi FTP. Ceci permet éventuellement de le partager largement. Vous pouvez notamment envoyer un lien vers une fiche en particulier sur un cosmoscope en ligne, en ajoutant son identifiant précédé d’un croisillon # en fin d’URL. Exemple :

https://domaine.fr/cosmoscope.html#20210427185546

5.1 Description générale de l’interface

L’interface de Cosma est organisée en trois colonnes :

Panneau latéral gauche (Menu)
Regroupe les fonctionnalités permettant de chercher de l’information et de modifier l’affichage de manière globale.
Zone centrale (Graphe)
Affiche le graphe et les contrôles associés (zoom, focus).
Panneau latéral droit (Fiche)
Affiche les fiches (métadonnées et contenu) ainsi qu’une liste des liens sortants (Liens) et entrants (Rétroliens).

Interface de Cosma (cliquez sur l’image pour l’afficher en grand)

5.2 Graphe

Le graphe située dans la zone centrale de l’interface affiche des nœuds étiquetés et interreliés. Chaque nœud correspond à une fiche ; l’étiquette correspond au titre de la fiche. Les liens correspondent aux liens établis entre les fiches via leur identifiant entre doubles crochets.

Si le paramètre highlight_on_hover est activé, survoler un nœud le met temporairement en surbrillance, ainsi que ses connexions. Cliquer sur un nœud le met en surbrillance, ainsi que ses connexions, et ouvre la fiche correspondante.

Vous pouvez zoomer dans le graphe à la souris, au pavé tactile, en double cliquant sur le fond du graphe ou bien avec les boutons dédiés situés en bas à gauche. Le bouton Recentrer (raccourci : touche R) réinitialise le zoom.

Les nœuds sont organisés dans l’espace par un algorithme de simulation de forces. Une barre colorée sous le logo Cosma témoigne de l’état de la simulation. Cliquez dessus (raccourci : touche Espace) pour lancer un cycle de simulation supplémentaire.

Quelques pressions sur la touche Espace permettent de « déplier » progressivement un graphe emmêlé.

Le graphe n’est pas figé, les nœuds peuvent donc être déplacés par cliquer-glisser. Ils restent soumis en permanence à la simulation, donc il n’est pas possible de les disposer manuellement de manière arbitraire.

L’affichage du graphe peut être modifié de manière temporaire via les contrôles placés sous Paramètres du graphe dans le panneau latéral gauche :

Pour modifier l’affichage de manière permanente, modifiez les valeurs par défaut des paramètres correspondants sous graph_config dans config.yml (voir Paramètres du graphe plus haut).

Modifiez force et distance_max pour adapter l’affichage à la résolution et la taille de votre écran. Modifiez verticale et horizontale pour appliquer une force centripète vers l’axe correspondant, ce qui permet notamment de ramener les îlots et nœuds isolés plus près du centre.

L’affichage est possible sur tous types d’écrans mais n’est pas optimisé pour les terminaux mobiles : le tactile ne donne pas accès à certaines interactions comme le survol, et les petits écrans restreignent l’utilité du graphe.

5.3 Fiches

Les fiches peuvent êtres ouvertes en cliquant sur un nœud, une entrée de l’index, une suggestion du moteur de recherche, ou un lien dans le corps d’une fiche. Ouvrir une fiche affiche son contenu dans le panneau latéral droit. Cela met aussi à jour l’URL de la page avec l’identifiant de la fiche : ceci permet de naviguer entre les fiches visitées via les fonctionnalités Précédent / Suivant du navigateur, mais aussi de les retrouver dans l’historique ou encore d’obtenir un lien direct vers la fiche.

Cliquer sur le bouton « Fermer » referme le volet et désélectionne le nœud correspondant dans le graphe.

Les liens présents dans les fiches sont cliquables. Vous pouvez ouvrir ces liens dans un nouvel onglet via un clic droit. Le titre du lien (affiché en infobulle après 1-2 secondes de survol) est celui de la fiche correspondante.

En bas de la fiche se trouve une liste des fiches vers lesquelles elle renvoie (liens sortants), ainsi que des fiches qui pointent vers elles (liens entrants ou rétroliens). Les liens et rétroliens sont contextualisés : au survol, une infobulle s’affiche, montrant le paragraphe dans lequel ce lien se trouve dans la fiche correspondante.

5.4 Mode focus

Le bouton Activer le focus (raccourci : touche F) situé en bas à gauche du graphe permet de restreindre l’affichage au nœud sélectionné : en mode focus, seules les connexions directes à la fiche sélectionnée sont affichées dans l’interface. Le mode focus ne fonctionne que si vous avez sélectionné une fiche.

Le curseur qui apparaît sous le bouton Activer le focus permet de faire varier la distance d’affichage, jusqu’au maximum permis par le paramètre focus_max dans la configuration.

Le curseur du niveau de focus est contrôlable via les flèches du clavier. Vous pouvez enchaîner les raccourcis : F pour activer le focus, puis les flèches pour augmenter le niveau de focus.

5.5 Moteur de recherche

Le champ de texte situé en haut du panneau latéral gauche est un moteur de recherche. Il suggère une liste de fiches dont le titre est proche de votre saisie (fuzzy search). Cliquer sur une suggestion sélectionne le nœud correspondant dans le graphe et ouvre la fiche correspondante dans le panneau latéral de droite.

Les suggestions disponibles sont contraintes par les filtres et le mode focus : une fiche masquée par l’une l’autre de ces fonctionnalités ne sera pas accessible via le moteur de recherche.

5.6 Filtrer l’affichage par types

La liste des types de fiches située en haut du panneau latéral gauche permet de filtrer l’affichage. Cliquer sur un type permet de masquer et réafficher les fiches du type correspondant dans le graphe, l’index et les suggestions du moteur de recherche. Cliquer sur un type en maintenant la touche Alt enfoncée permet de masquer et réafficher les fiches des autres types.

Pour qu’un type apparaisse, il doit être déclaré sous record_types dans la configuration et être présent dans au moins une fiche.

5.7 Mots-clés

La liste des mots-clés située dans le panneau latéral gauche permet de mettre en évidence les fiches qui utilisent chaque mot-clé. Sélectionner un mot-clé met en surbrillance l’étiquette des nœuds correspondants dans le graphe et restreint l’index aux fiches correspondantes. Vous pouvez activer simultanément plusieurs mots-clés. Pour désactiver un mot-clé, cliquez à nouveau sur le bouton correspondant.

Pour qu’un mot-clé apparaisse, il suffit qu’il ait été déclaré dans au moins une fiche via le champ tags.

5.8 Index

L’index alphabétique des fiches situé dans le panneau latéral gauche permet d’accéder directement à une fiche sans passer par le graphe. Cliquer sur un titre sélectionne le nœud correspondant dans le graphe et ouvre la fiche correspondante. L’index peut être trié par ordre alphabétique croissant ou décroissant. Les filtres, les mots-clés et le mode focus modifient l’affichage de l’index.

5.9 Vues

À tout moment, l’état du graphe (fiche sélectionnée, filtres actifs, mode focus) peut être sauvegardé pour un accès rapide. Cette fonctionnalité est une sorte de marque-page mais pour le graphe. Cliquez sur le bouton Sauvegarder la vue pour récupérer un code dans votre presse-papier. Ce code doit ensuite être déclaré à la suite d’un nom de vue sous le paramètre views dans la configuration :

views:
  Une vue intéressante: eyJwb3MiOnsieCI6MCwieSI6MCwiem9vbSI6MX19

Ceci ajoute un bouton éponyme dans la section Vues du panneau latéral gauche. Cliquer sur ce bouton applique tous les paramètres qui étaient actifs au moment de l’enregistrement de la vue. Cliquer à nouveau sur le bouton rétablit l’affichage normal.

5.10 Personnalisation de l’interface

L’interface du cosmoscope est conçue à partir des fichiers Nunjucks (.njk) et CSS présents dans le dossier /template du répertoire de Cosma.

L’interface peut être personnalisée via un fichier custom.css placé dans ce même dossier. Vous pouvez créer manuellement le fichier ou bien exécuter la commande suivante :

node app css

Le paramètre custom_css de la configuration permet d’activer ou désactiver la prise en compte de ce fichier sans avoir à le supprimer.

Les déclarations CSS ajoutées dans /template/custom.css remplacent celles présentes dans /template/styles.css et /template/print.css (pour les styles à l’impression). Elles s’appliquent au fichier /template/template.njk. Consultez ces fichiers ou utilisez l’inspecteur de votre navigateur web pour connaître les sélecteurs à utiliser pour telle ou telle déclaration. Les feuilles de style du cosmoscope utilisent notamment des variables CSS pour définir les couleurs et les polices utilisées. Vous pouvez redéfinir uniquement ces variables pour modifier tous les éléments d’interface auxquels elles s’appliquent.

Dans l’exemple ci-dessous, le fichier custom.css contient des déclarations qui modifient les polices utilisées dans le cosmoscope :

:root {
  --sans: "IBM Plex Serif", sans-serif;
  --serif: "IBM Plex Serif", serif;
  --mono: "IBM Plex Mono", monospace;
  --condensed: 'IBM Plex Sans Condensed', sans-serif;
}

6 Développement

Cette partie de la documentation s’adresse à des développeurs expérimentés en JavaScript. Elle présente l’arborescence et les concepts sur lesquels reposent les deux parties formant Cosma, le cosmographe et le cosmoscope.

Nous vous recommandons vivement de lire le reste de la documentation pour bien saisir l’ensemble des usages en jeu dans le code source présenté ci-dessous.

6.1 Terminologie

Les fichiers Markdown interprétés par Cosma sont qualifiés ici de « fiches » plutôt que de « notes », en référence à la tradition de la fiche érudite et à l’histoire de la documentation. L’acception documentaire de « fiche » n’a pas de traduction directe en anglais (sinon index card). En revanche, elle est conceptuellement proche du mot « record » issu du records management. Le code de Cosma emploie donc le mot record pour désigner une fiche.

6.2 Description générale de l’architecture

Cosma est principalement implémenté en JavaScript. Le logiciel repose sur deux systèmes distincts, le cosmographe et le cosmoscope.

Le cosmographe repose sur l’environnement Node.js. Une série de scripts permettent de :

Le cosmoscope est un fichier HTML exécuté sur navigateurs web, créé à partir d’un template Nunjucks (template.njk). Il intègre :

6.3 Arborescence

Vous trouverez ci-dessous une description complète de l’arborescence du logiciel. Vous pourrez ainsi distinguer les fichiers concernant le cosmographe et ceux du cosmoscope.

.
├── docs/                   | répertoire de la documentation
│   ├── api/                | répertoire des index des API
│   │   └── [x].md          | introduction à l'index [x] de l'API
│   └── api-config-[x].json | config. de l'index [x] de l'API
├── functions/              | fonctions du cosmographe
│   ├── autorecord.js       | création de fichiers Markdown formatés
│   ├── history.js          | création répertoires de l'historique des exports
│   ├── links.js            | analyse des liens wiki et de leurs attributs
│   ├── log.js              | affichage des alertes et création des registres
│   ├── modelize.js         | analyse des fichiers Markdown et création modèle de données
│   ├── record.js           | formulaire du terminal pour création des fichiers Md
│   ├── template.js         | intégration données, style et corps du cosmoscope
│   └── verifconfig.js      | validation et modification de la configuration
├── template/               | 
│   ├── libs/               | bibliothèques JavaScript
│   ├── scripts/            | fonctions du cosmoscope
│   │   ├── counter.js      | actuliser les compteurs d'entités
│   │   ├── filter.js       | appliquer filtres
│   │   ├── focus.js        | appliquer focus
│   │   ├── graph.js        | génération du graphe selon données et configuration
│   │   ├── history.js      | historique de navigation entre les fiches
│   │   ├── index.js        | contrôle des volets et boutons du menu gauche
│   │   ├── keyboard.js     | affectation des raccourcis clavier
│   │   ├── main.js         | variables globales et animation logo
│   │   ├── nodes.js        | affichage des nœuds
│   │   ├── record.js       | ouvrir/fermer le volet latéral droit
│   │   ├── search.js       | paramétrage moteur de recherche
│   │   ├── tag.js          | appliquer tags
│   │   ├── view.js         | enregistrer et appliquer une vue
│   │   └── zoom.js         | paramétrer les déplacement (latéral, zoom) au sein du graphe
│   ├── cosmalogo.svg       | logo du logiciel
│   ├── template.njk        | structure du cosmoscope
│   ├── print.css           | styles d'impression du cosmoscope
│   └── styles.css          | styles du cosmoscope
├── app.js                  | adressage des commandes du terminal
└── package.json            | liste des dépendances Node.js

6.4 Index des fonctions

Cliquez sur les liens ci-dessous pour consulter la liste des fonctions utilisées par le cosmographe et le cosmoscope :

6.5 Fonctionnement du cosmographe

Il a trois utilisations possibles via le terminal. Ces différentes requêtes sont réceptionnées par app.js qui les renvoie :

La configuration (le contenu du fichier config.yml devenu un objet JavaScript) est exportée de manière globale (depuis verifconfig.js). Elle peut être appelée comme ci-dessous.

const config = require('./verifconfig').config;

const folderToExport = config.export_target;

6.6 Lecture des fichiers

Depuis le fichier modelize.js, on extrait de chaque fichier Markdown les métadonnées (l’entête YAML) et le contenu (suivant l’entête YAML) (fichier modelize.js).

catchLinksFromContent()
Le contenu est lu une première fois par une série d’expressions régulières pour en extraire les paragraphes, et pour chaque paragraphe les wikilinks contenus. Le paragraphe devient le contexte de ses liens et est transpilé en HTML.
convertLinks()
Le contenu du fichier est ensuite transformé pour y transformer les wikilinks en liens Markdown
cosmoscope()
Le contenu du fichier est intégralement transpilé du Markdown à l’HTML.

La première et la troisième fonction font appel à la bibliothèque markdown-it. Elle peut être remplacée.

6.7 Génération du cosmoscope

Le cosmoscope est généré grâce à la fonction cosmoscope().

Celle-ci instancie le modèle Nunjucks /template/template.njk et y injecte les données relatives à la configuration, aux fiches et aux entités du graphe ainsi que leurs styles (sérialisés par la fonction colors()).

Nunjucks importe par ailleurs dans son head les fichiers de style CSS et les bibliothèques JavaScript ainsi que les fonctions JavaScript dans des balises script en fin de document. Les données relatives aux fiches et à la configuration sont intégrées via des boucles et autres structures de contrôle de Nunjucks.

Le tout est enregistré dans un fichier cosmoscope.html et est exporté.

6.8 Affichage du graphe

La génération et l’animation du graphe reposent sur la bibliothèque D3.js. Celle-ci perçoit ses données depuis l’objet global graph. Cet object est composé de deux tableaux.

graph.nodes
Ce tableau contient toutes les données relatives aux nœuds, y compris une série de booléens permettant de connaître leur état d’affichage (voir la sérialisation par la fonction registerNodes()). Cet état indiqué est actualisé à chaque modification d’affichage.
graph.links
Ce tableau contient toutes les données relatives aux liens (voir la sérialisation par la fonction registerLinks()).

6.9 Affichage via d’autres bibliothèques

Les tableaux présentés dans la section précédente peuvent être injectés dans d’autres bibliothèques JavaScript de génération de graphe.

Exemple 1 : Vis.js Network (dépôt, exemple).

Extrait du fichier /functions/modelize.js :

function registerLinks(file) {
// ...
  for (const link of file.links) {
  // ...
    entities.links.push({
      // ...
      from: Number(link.source.id),
      to: Number(link.target.id),
      // ...
    });
  }
}

Extrait du fichier /template/scripts/graph.js

const network = new vis.Network(
  document.getElementById('network')
  , data = {
    nodes: new vis.DataSet(graph.nodes),
    edges: new vis.DataSet(graph.links)
  }
  , {  } // options
);

Exemple 2 : Sigma.js (dépôt, exemple).

const network = new sigma({
  graph: {
    nodes: graph.nodes,
    edges: graph.links
  },
  container: 'network'
});

6.10 Paramètres du graphe

Les paramètres du graphe sont extraits de la partie graph_config du fichier de configuration config.yml. Elle est injectée dans le modèle Nunjucks /template/template.njk via la fonction cosmoscope(). Dans le modèle, elle est à la fois utilisée comme valeur par défaut des formulaires du menu « Paramètres du graphe » et implémentée comme objet global JavaScript graphProperties.

Ce même objet global est actualisé par les différents formulaires du menu « Paramètres du graphe ». Ils font ensuite appel à la fonction updateForces() pour relancer l’évaluation de ces paramètres par la bibliothèque de visualisation D3.js.

6.11 Raccourcis clavier

L’ensemble des raccourcis clavier du cosmoscope sont implémentés dans le fichier /template/scripts/keyboard.js. L’objet global pressedKeys contient la liste des touches surveillées pour modifier un comportement. D’autres touches (des lettres) sont listées pour appeler certaines fonctions et ne sont pas ajoutées à l’objet global pressedKeys.

Le booléen global keyboardShortcutsAreWorking définit si les raccourcis peuvent être utilisés ou non. Lors de la saisie dans un champ, il ne faut pas que les lettres servent à autre chose qu’écrire.

7 Crédits

7.1 Équipe

7.2 Bibliothèques utilisées

Pour améliorer la maintenabilité et la lisibilité du code source, l’équipe de développement a recouru aux bibliothèques suivantes.

7.3 Historique du projet

Août 2020
Prototypage d’un « Lexicographe » avec l’interface de l’Otletosphère.
Décembre 2020
Début du développement de Cosma avec un nouveau cahier des charges.
Avril 2021
Finalisation de la première version de Cosma.