→ 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 a été développé initialement dans le cadre du programme de recherche ANR HyperOtlet.

Spécificités de Cosma

Dans le vaste champ des outils qui servent à penser (tools for thought), Cosma se démarque par trois originalités :

D'abord, Cosma n'est pas lui-même un logiciel de prise de notes. Il est pensé pour fonctionner en complémentarité avec ces logiciels. Nous nous sommes inspirés ici du fonctionnement de logiciels comme Deckset, qui applique ce principe aux présentations.

Ensuite, Cosma repose sur des normes d'écriture interopérables, ouvertes et standardisées. Ceci accroît la pérennité des données, facilite l'utilisation combinée avec des outils qui partagent ces normes (comme Zettlr), tout en laissant la possibilité de changer d'outil à tout moment.

Enfin, Cosma permet de partager simultanément les données et les outils pour les explorer. 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 : l'application installée, surnommée cosmographe, est un simple outil de création et d'affichage qui accueille un fichier HTML surnommé cosmoscope ; c'est ce dernier qui constitue la véritable interface de visualisation, avec un graphe interactif, des outils de navigation interne (index, moteur de recherche, filtres) et le texte intégral des fiches. Or il s'agit d'un fichier autonome, qui inclut aussi les données sources au format JSON et peut être utilisé hors connexion. Ainsi dans Cosma, l'export est aussi puissant que l'application : en partageant un cosmoscope vous ne transmettez pas seulement des données mais des capacités heuristiques.

Un degré élevé de contrôle utilisateur

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.

Quatrièmement, Cosma est un logiciel modulaire, interopérable et portable mais surtout, c'est un logiciel 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.

Un logiciel expérimental

Enfin, Cosma est un logiciel expérimental, développé dans le cadre d'une démarche de recherche-conception.

L'idée de Cosma est née dans le cadre d'une recherche doctorale conduite par Arthur Perret sous la direction d'Olivier Le Deuff. Ce logiciel reste donc un travail expérimental, son utilisation est soumise à caution et aucune garantie de suivi ou de maintenance ne peut être donnée à ce jour.

Néanmoins, des efforts importants ont été entrepris dès le prototype pour concevoir soigneusement les différents aspects de l'outil, qu'il s'agisse de la visualisation de données ou de l'interaction humain-machine, notamment grâce à la participation de chercheurs spécialistes de ces domaines. Et Cosma est au cœur d'une dynamique de recherche que nous espérons inscrire dans la durée.

Cosma peut être cité dans une bibliographie de la manière suivante :

Arthur Perret, Guillaume Brioudes, Clément Borel, & Olivier Le Deuff. (2021). Cosma. Zenodo. https://doi.org/10.5281/zenodo.5920615

Cosma intègre une fonctionnalité de traitement des citations. Elle repose sur le même écosystème que Zettlr : les données et styles bibliographiques utilisent la norme Citation Style Language (CSL), tandis que l'insertion des citations dans le texte se fait avec la syntaxe de citation de Pandoc.

Fichiers requis

Pour traiter automatiquement les citations, Cosma requiert trois fichiers :

• Données bibliographiques : fichier contenant les métadonnées décrivant des références bibliographiques. Le format requis est CSL JSON (extension .json).
• Style bibliographique : fichier contenant les règles de mise en forme des citations et bibliographies. Le format requis est CSL (extension .csl). Vous pouvez télécharger des fichiers de style depuis le répertoire de styles CSL de Zotero.
• Localisation bibliographique : fichier contenant les traductions dans une certaine langue des termes employés en bibliographie (ex : éditeur, numéro…). Le format requis est XML (extension .xml). Vous pouvez télécharger des fichiers de localisation depuis le dépôt GitHub du projet CSL.

Dans le fichier de données, chaque référence doit posséder un identifiant unique (id) qui sert de clé de citation. Exemple :

[
  {
    "id":"goody1979",
    "author":[{"family":"Goody","given":"Jack"}],
    "citation-key":"goody1979",
    "event-place":"Paris",
    "ISBN":"978-2-7073-0240-3",
    "issued":{"date-parts":[[1979]]},
    "language":"fr",
    "publisher":"Les Editions de Minuit",
    "publisher-place":"Paris",
    "title":"La Raison graphique : la domestication de la pensée sauvage",
    "title-short":"La Raison graphique",
    "type":"book"
  }
]

Vous pouvez utiliser le gestionnaire de références bibliographiques Zotero avec l'extension Better BibTeX afin de créer des clés de citation uniques pour chaque référence ainsi que des exports automatiquement mis à jour.

Syntaxe de citation

Pour citer une référence dans une fiche, intégrez la clé de citation de cette référence en utilisant la syntaxe de citation de Pandoc.

Exemple :

À propos de raison graphique [@goody1979, 46-52]…

Créer un cosmoscope avec citations

Cliquez sur Fichier › Nouveau cosmoscope avec citations (Cmd/Ctrl + Maj + R) pour générer un cosmoscope avec le traitement des citations activé. Le traitement des citations est également disponible lors de l'export (voir → Partager un cosmoscope). Chaque clé de citation est alors remplacée par du texte formaté et une bibliographie est générée en-dessous du corps de chaque fiche contenant des références.

Exemple :

À propos de raison graphique (Goody 1979, 46-52)…

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

GOODY, Jack, 1979. La Raison graphique : la domestication de la pensée sauvage.
  Paris : Les Editions de Minuit. ISBN 978-2-7073-0240-3.

Les données CSL JSON correspondant aux références citées sont enregistrées dans le cosmoscope au format JSON. Vous pouvez consulter et télécharger ces données dans le cosmoscope en cliquant sur le bouton « Données » en bas du menu latéral gauche. Vous pouvez également y accéder en consultant le code source du cosmoscope au niveau de la balise <article id="citation-references">.

Le fonctionnement de Cosma peut être modifié via la configuration.

La configuration de la version CLI s'effectue dans un fichier YAML config.yml. Ce fichier est généré par l'application lors de la première exécution, à la racine du répertoire de l'application :

• Windows : %USERPROFILE%\AppData\Roaming\npm\node_modules\@graphlab-fr\cosma\config.yml
• macOS, Linux : /usr/local/lib/node_modules/@graphlab-fr/cosma/config.yml

Le fichier config.yml généré par Cosma contient les valeurs par défaut des différents paramètres. Ces paramètres sont identiques à la version GUI. Si vous retirez un paramètre du fichier, Cosma considère qu'il a sa valeur par défaut.

La configuration de la version CLI s'effectue depuis la fenêtre Préférences de l'application.

La majorité des options de configuration ne fonctionnent que si un répertoire de fiches est renseigné.

Général

Langue d'affichage

Permet de choisir la langue que vous souhaitez appliquer à l'interface de l'application ainsi qu'aux cosmoscopes générés et exportés.

Un redémarrage de l'application est nécessaire pour que le changement de langue prenne effet dans l'interface. De plus, Cosma ne re-génère pas automatiquement un cosmoscope suite au changement de langue : il faut donc re-générer manuellement un cosmoscope pour voir le changement prendre effet.

Répertoire des fiches

Chemin du répertoire contenant les fichiers Markdown. Les nouvelles fiches créées via Cosma sont ajoutées dans ce répertoire.

Enregistrer automatiquement les cosmoscopes dans l’historique

Par défaut, Cosma exporte automatiquement chaque cosmoscope dans un répertoire cosma-history situé dans les répertoires temporaires du système d'exploitation. Décochez cette option pour désactiver cet export automatique.

Le cosmocope actif est toujours enregistré dans l'historique comme dernière entrée. C'est cette dernière entrée qui est ouverte lors du lancement de l'application. Si l'enregistrement automatique des cosmoscopes est désactivé, cette dernière entrée sera simplement écrasée à chaque nouvelle génération de cosmoscope.

Symbole de lien

Saisissez ici une chaîne de caractères Unicode arbitraire. Elle remplacera les identifiants entre les crochets dans le rendu HTML des fiches. Ceci permet d'alléger visuellement le texte de vos fiches en remplaçant les longs identifiants numériques par une convention personnelle (par exemple une petite manicule : ☞).

Types de fiches

Cette section permet de définir différents types de fiches. Pour chaque type de fiche, renseignez un nom et une couleur.

Ajoutez type: nom à l'en-tête en YAML d'une fiche pour lui attribuer ce type. Un seul type peut être assigné à une fiche. 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, Cosma interprètera le type de la fiche comme non défini (undefined).

Note : le type undefined (couleur par défaut des nœuds) peut être modifié, mais ne peut être retiré.

Types de liens

Cette section permet de définir différent types de liens. Pour chaque type de lien, renseignez un nom, une couleur et un tracé. Les tracés disponibles sont :

• continu (simple)
• double (double)
• tirets (dash)
• pointillés (dotted)

Pour qualifier un lien dans une fiche, préfixez l'identifiant par le nom d'un type de lien suivi d'un deux-points.

Note : le type undefined (couleur et type de trait par défaut des liens) peut être modifié, mais ne peut être retiré.

Astuce : le paramétrage visuel des liens a une incidence sur leur lisibilité au sein du graphe. Par exemple, si vous définissez les liens non qualifiés (undefined) en pointillés (dotted) gris (grey) et un type de lien spécial en trait continu (simple) noir (black), les liens spéciaux seront plus visibles dans le graphe.

Graphe

Les paramètres du graphe peuvent être modifiés en direct dans le cosmoscope. Vous pouvez ainsi tester différentes valeurs avant de les reporter dans la configuration. Ce sont les valeurs définies dans la configuration qui sont rétablies à chaque rechargement du cosmoscope, et chaque nouvelle génération d'un cosmoscope.

Couleur de fond

La couleur de fond du graphe.

Couleur de surbrillance

La couleur qui s'applique aux nœuds ainsi qu'aux liens lors du survol et de la sélection.

Note : les deux paramètres de couleur ci-dessus sont accessibles via l'interface car ils sont susceptibles d'être modifiés par de nombreux utilisateurs. Mais toutes les couleurs de l'interface peuvent être modifiées en utilisant une feuille de style CSS personnalisée (voir Configuration › Avancé).

Taille du texte des étiquettes

Définit la taille du texte des étiquettes des nœuds du graphe, c'est-à-dire la place que prend le titre de chaque fiche sous le nœud correspondant. L'unité implicite est le pixel. Les valeurs possibles sont comprises entre 5 et 15.

Niveau maximum de focus

Le mode focus restreint l'affichage au nœud sélectionné et à ses connexions directes (1 nœud de distance).

Il est possible de faire varier la distance d'affichage du mode focus : passer à 2 affiche les connexions jusqu'à 2 nœuds de distance ; passer à 3 étend l'affichage à 3 nœuds de distance ; etc. La valeur indiquée dans Niveau maximum de focus définit le seuil maximum pour cette fonctionnalité. Une valeur élevée consomme plus de ressources à l'affichage.

Afficher des flèches sur les liens

Permet d'obtenir un graphe orienté ou non orienté.

Spatialisation

• Force d'attraction : correspond à la puissance globale de l'attraction simulée. Plus la valeur est faible, plus les liens entre les nœuds sont relâchés.
• Distance maximum entre les nœuds : correspond au seuil maximal de répulsion entre les nœuds, quelle que soit la force. Au-delà d'une valeur de 1000, ce paramètre n'a pas d'effet mesurable.
• Attraction verticale/horizontale : force d'attraction vers l'axe vertical/horizontal, de 0 à 1. Une valeur de 0 signifie que le paramètre est désactivé. Appliquer une force verticale/horizontale resserre le graphe et permet de ramener plus près du centre les nœuds isolés.

Métadonnées

Vous pouvez définir des métadonnées globales pour le cosmoscope :

• titre
• auteur
• mots-clés
• description

Les cosmoscopes exportés via le menu Partager intègrent ces métadonnées si elles sont renseignées. Le titre vient remplacer les boutons situés en haut à gauche du menu, et qui ne s'affichent que dans l'application. Les métadonnées sont affichées dans le panneau « À propos ». Elles sont également incluses dans le code source du cosmoscope sous la forme de balises meta.

Bibliographie

Indiquez ici les chemins des fichiers de données, style et localisation bibliographique. Les trois fichiers sont requis pour le → traitement des citations.

Données bibliographiques

Fichier contenant les métadonnées décrivant des références bibliographiques. Le format requis est CSL JSON (extension .json).

Style bibliographique

Fichier contenant les règles de mise en forme des citations et bibliographies. Le format requis est CSL (extension .csl). Vous pouvez télécharger des fichiers de style depuis le répertoire de styles CSL de Zotero.

Localisation bibliographique

Fichier contenant les traductions dans une certaine langue des termes employés en bibliographie (ex : éditeur, numéro…). Le format requis est XML (extension .xml). Vous pouvez télécharger des fichiers de localisation depuis le dépôt GitHub du projet CSL.

Vues

Gérez ici les vues enregistrées dans le cosmoscope.

Avancé

Afficher les outils de développement

Cette option permet d'afficher les outils de développement du logiciel depuis Affichage › Outils de développement. Cliquez sur Afficher l'inspecteur web pour inspecter le code de l'interface de Cosma.

CSS personnalisée

Indiquez ici le chemin d'un fichier CSS pour personnaliser l'interface du cosmocope. Il est nécessaire de re-générer un cosmoscope pour que la CSS personnalisée soit prise en compte.

Astuce : pour connaître les sélecteurs à utiliser pour telle ou telle déclaration, vous pouvez :

• cliquer sur Affichage › Outils de développement (nécessite d'avoir activé Afficher les outils de développement) ;
• ouvrir le cosmoscope dans un navigateur web et utiliser les outils de développement du navigateur ;
• consulter le code source de Cosma, spécifiquement /cosma-core/template.njk (pour connaître la structure HTML du cosmoscope), /cosma-core/styles.css et /cosma-core/print.css (pour les styles d'impression activés lors de l'impression d'une fiche).

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 Sans", sans-serif;
  --serif: "IBM Plex Serif", serif;
  --mono: "IBM Plex Mono", monospace;
  --condensed: 'Avenir Next Condensed', sans-serif;
}

Cosma interprète les fichiers comme étant rédigés en CommonMark, une version strictement définie du langage de balisage léger Markdown.

Astuce : le tutoriel CommonMark traduit en français permet d'apprendre les bases de Markdown en 10 minutes. Si vous souhaitez découvrir l'utilisation conjointe de Markdown et Pandoc, vous pouvez consulter le cours en ligne Markdown et vous.

Cosma génère un rendu des fichiers Markdown en HTML. Par conséquent, les fichiers Markdown peuvent également inclure du code HTML, ainsi que des images vectorielles en SVG. Des images bitmap peuvent être incluses dans le rendu via la syntaxe Markdown. Cependant, les fichiers images ne sont pas intégrés à l'export. Pour que les images s'affichent à l'export, privilégiez donc les images hébergées sur le Web et incluses via une URL. Exemple :

![Texte alternatif](http://domaine.fr/image.jpg)

Cosma est un logiciel de visualisation et de partage pour les travailleurs de la connaissance [@perret2021].

Cosma existe en deux versions différentes qui peuvent être téléchargées et utilisées séparément : une application de bureau avec interface graphique (version GUI) et un outil en ligne de commande (version CLI).

L'application Cosma se divise en deux parties : un → cosmographe et un → cosmoscope. À partir d’un répertoire de fichiers rédigés en Markdown, le cosmographe génère une collection de fiches au format HTML, rassemblées dans un fichier qui peut être consulté dans l'application mais aussi de manière autonome : le cosmoscope.

Vous parcourez actuellement un cosmoscope qui constitue à la fois une aide au démarrage et une démonstration du fonctionnement de Cosma. La documentation complète est en ligne.

Le cosmographe est la partie de Cosma qui sert à configurer le fonctionnement de l'application et à faciliter la création de contenus. C'est une application pour ordinateur de bureau, à interface graphique, qui consiste en un ensemble de formulaires, de menus et de panneaux.

Le cosmographe permet de → créer des fiches ainsi que de → créer des cosmoscopes et → partager des cosmoscopes.

Le cosmoscope est la partie centrale de Cosma. C'est un fichier HTML qui contient à la fois les fiches (mises en forme pour la lecture), une visualisation interactive des relations entre les fiches, et des outils d'exploration. Il peut être utilisé aussi bien dans l'application Cosma qu'en dehors.

Contenu

La zone centrale du cosmoscope affiche le → graphe et les contrôles associés (zoom, → mode focus).

Le panneau latéral droit du cosmoscope affiche les → fiches, avec leurs métadonnées, leur contenu et une liste des liens sortants et entrants (rétroliens).

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

• Le panneau latéral gauche (Menu) regroupe les fonctionnalités permettant de chercher de l'information et de modifier l'affichage de manière globale : → index, → moteur de recherche, filtres → par types et → par mots-clés, → vues.
• La zone centrale (Graphe) affiche le → graphe et les contrôles associés (zoom, → mode focus).
• Le panneau latéral droit (Fiche) affiche les → fiches, avec leurs métadonnées, leur contenu et une liste des liens sortants (Liens) et entrants (Rétroliens).

Vous retrouverez la même interface, les mêmes raccourcis et outils de visualisation dans un cosmoscope ouvert dans l'application Cosma que dans un export ouvert dans un navigateur web, à une différence près : les boutons permettant d'interagir avec l'application Cosma (Nouvelle fiche, Nouveau cosmoscope, etc.) ne s'affichent que dans l'application, pas dans les exports.

Utilisation hors de Cosma

Le cosmoscope peut être ouvert indépendammant de l'application Cosma, via un navigateur web. C'est un fichier qui peut être partagé comme n'importe quel autre fichier informatique : email, transfert de fichiers, messagerie, mise en ligne sur un serveur…

Lorsqu'un cosmoscope est mis en ligne, vous pouvez envoyer un lien vers une fiche en particulier en ajoutant son identifiant précédé d'un croisillon # en fin d'URL. Exemple :

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

La principale fonctionnalité du cosmographe est de créer des → cosmoscopes. Après avoir été généré, le cosmoscope le plus récent est affiché dans la fenêtre principale de l'application Cosma.

Cosmoscope simple

Cliquez sur Nouveau cosmoscope (raccourci : Cmd/Ctrl + R) pour lancer la génération d'un nouveau cosmoscope.

Cosmoscope avec traitement des citations

Cliquez sur Nouveau cosmoscope avec citations (raccourci : Maj + Cmd/Ctrl + R) pour lancer la génération d'un nouveau cosmoscope en activant le traitement des citations.

Gestion des erreurs

Cosma crée automatiquement un rapport d'erreurs qui décrit les problèmes éventuellement rencontrés durant la génération d'un cosmoscope. Cliquez sur Fichier › Historique (Cmd/Ctrl + H) et sélectionnez une entrée pour consulter le rapport d'erreurs associé.

Cliquez sur Fichier › Nouvelle fiche (Ctrl/Cmd + N) pour ouvrir le formulaire de création de fiche de Cosma.

Le titre est obligatoire. Les autres champs sont facultatifs.

Vous pouvez assigner un type à la fiche. Le type doit être défini préalablement dans la configuration (Préférences › Types de fiche).

Vous pouvez également ajouter des mots-clés à la fiche. Les mots-clés doivent être séparés par des virgules. Exemple : mots-clé 1, mot-clé 2.

Cliquez sur OK pour créer la fiche.

Note : le nom de fichier est généré à partir du titre. Pour une meilleure interopérabilité entre les différents systèmes d'exploitation, le nom de fichier ne contient que des caractères alphanumériques non accentués et des tirets. Exemple : une fiche intitulée « Métadonnées web sémantique » sera enregistrée comme metadonnees-web-semantique.md.

Créer une fiche de cette manière génère un fichier conforme au → format de données requis par Cosma.

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 ou le pied d'une fiche. Ouvrir une fiche affiche son contenu dans le panneau latéral droit.

Dans l'application Cosma, vous pouvez naviguer dans l'historique d'ouverture des fiches avec les boutons Précédent / Suivant situés dans le panneau latéral gauche.

Dans un navigateur web où est ouvert un cosmoscope, ouvrir une fiche met à 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 du navigateur ou encore d'obtenir un lien direct vers la fiche à partager.

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

Les liens présents dans les fiches sont cliquables. Dans un navigateur où est ouvert un cosmoscope, 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.

Astuce : pour améliorer la lisibilité des fiches dans le cosmoscope, Cosma inclut une option pour personnaliser le texte des liens. Dans Préférences › Symbole de lien, saisissez un ou plusieurs caractères Unicode (lettres, chiffres, symboles…). Exemple : ☞. Cette chaîne de caractères remplace l'identifiant entre crochets dans le rendu HTML des fiches.

En bas de chaque fiche se trouve une liste des liens sortants et des liens entrants (ou rétroliens). Les liens et rétroliens sont contextualisés : au survol, une infobulle s'affiche, montrant le paragraphe qui entoure ce lien dans la fiche correspondante.

Note : les liens et rétroliens contextualisés font partie des fonctionnalités les plus utiles des systèmes hypertextuels. C'est une fonctionnalité notoirement absente du Web. En revanche, de nombreuses applications de prise de notes interreliées traitent les liens comme un élément de première importance, et cela inclut les rétroliens contextualisés. Cependant, lorsque ces notes sont partagées sur le Web, cette fonctionnalité n'est pas toujours incluse, ou alors elle fait partie d'un service de publication payant. Avec Cosma, les rétroliens contextualisés font partie du logiciel, que vous soyez l'auteur d'un cosmoscope travaillant sur sa machine, ou quelqu'un qui explore un cosmoscope sur le Web.

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 indiqué dans Préférences › Niveau maximum de focus. Une valeur de 1 signifie que seules les connexions immédiates seront affichées en mode Focus. Une valeur de 2 signifie que vous pouvez étendre le focus aux connexions des connexions, et ainsi de suite.

Astuce : 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.

Cosma ne prescrit pas l'utilisation d'un logiciel d'écriture particulier. En revanche, il interprète uniquement les fichiers respectant les règles suivantes :

• → contenu rédigé en Markdown, extension de fichier .md ;
• → métadonnées exprimées en YAML, dans un en-tête présent en début de fichier ;
• → liens internes exprimés avec une syntaxe de type wiki (doubles crochets [[ ]]) et basés sur des → identifiants uniques.

Note : cette combinaison de normes d'écriture correspond au croisement de plusieurs cultures textuelles : la documentation (enrichir et indexer le contenu avec des métadonnées) ; les wikis (interrelier des connaissances) ; la méthode Zettelkasten (organiser ses notes) ; l'écriture académique avec Pandoc (utiliser le format texte comme source pour plusieurs autres formats).

Cosma fonctionne donc particulièrement bien lorsqu'il est utilisé en tandem avec des environnements d'écriture qui adoptent également cette approche, comme Zettlr ou l'extension Foam pour Visual Studio Code et VSCodium.

Vous pouvez créer un fichier conforme pour Cosma via le formulaire de l'application (cliquez sur Fichier › Nouvelle fiche ou tapez Ctrl + N) ou bien en passant directement par votre éditeur de texte préféré. Certains éditeurs de texte peuvent vous faire gagner du temps en vous permettant d'enregistrer des modèles de documents, ce que vous pouvez utiliser pour créer rapidement des fiches à destination de Cosma.

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.

Survoler un nœud le met temporairement en surbrillance lui et ses connexions. Cliquer sur un nœud le met en surbrillance, ainsi que ses connexions, et ouvre la fiche correspondante.

Vous pouvez zoomer librement 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. Appuyez sur la touche C pour zoomer sur un nœud sélectionné. 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.

Astuce : 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 dans la configuration.

Astuce : modifiez la force et la distance maximale entre les nœuds pour adapter l'affichage à la résolution et la taille de votre écran. Ajoutez une force d'attraction vers l'axe vertical/horizontal pour resserrer le graphe et ramener les 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.

Pour être correctement interprétée par Cosma, chaque fiche doit avoir un identifiant unique. Cet identifiant sert de cible aux liens internes.

Par défaut, Cosma génère des identifiants à 14 chiffres par horodatage (année, mois, jour, heures, minutes et secondes). Nous nous inspirons ici du fonctionnement de logiciels de prise de notes type Zettelkasten comme The Archive et Zettlr.

Note : de nombreux logiciels de prise de notes interreliées proposent d'établir les liens entre fichiers via leurs noms, et de gérer automatiquement la maintenance des liens lorsque les noms de fichiers sont modifiés. En choisissant plutôt d'utiliser des identifiants uniques, nous avons donné à Cosma un fonctionnement plus classique, plus strict, proche de celui du Web. Nous pensons qu'il s'agit de la manière la plus simple d'éviter les liens morts de façon pérenne. Le fait de ne pas recourir à une maintenance automatique des liens notamment rend les données moins dépendantes d'une solution logicielle en particulier.

Astuce : l'inconvénient d'un lien basé sur un identifiant unique, c'est qu'il peut gêner la lecture du contenu, notamment lorsque l'identifiant est une longue série de chiffres. Dans Préférences › Symbole de lien, vous pouvez définir une convention personnelle, comme par exemple une petite manicule (☞), qui allège visuellement le rendu HTML des fiches en remplaçant les identifiants par une chaîne de caractères arbitraire.

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.

→ Cosma est disponible en deux versions : une application à interface graphique (graphical user interface, GUI) et une application exécutable en ligne de commande (command line interface, CLI).

Version GUI

La version GUI de Cosma est disponible pour macOS et Windows. Visitez la page Releases pour obtenir la dernière version du logiciel. L'application n'est pas signée avec un certificat de sécurité, vous devez disposer des privilèges administrateurs sur votre session pour pouvoir l'exécuter.

Sur macOS, téléchargez puis décompressez le fichier Cosma.app.zip et placez le le fichier Cosma.app dans ~/Applications. Au premier lancement, faites clic droit › Ouvrir sur l'application pour l'exécuter.

Sur Windows, téléchargez puis décompressez le fichier Cosma-win32-x64.zip, renommez le dossier « Cosma » et placez-le dans C:\Programmes ou C:\Programmes (86).

Version CLI

La version CLI de Cosma est disponible sur macOS, Windows et Linux.

L'installation de NodeJS version 15 minimum est requise.

Entrez la commande suivante dans votre terminal pour installer Cosma CLI :

npm i @graphlab-fr/cosma -g

À l'intérieur des fiches, vous pouvez créer des liens avec l'identifiant de la fiche cible entre double crochets.

Exemple :

Un lien vers [[20201209111625]] une fiche.

Cosma permet de définir des types de liens. Chaque type de lien est caractérisé par un nom, une couleur et un tracé. Pour qualifier un lien dans une fiche, préfixez l'identifiant par le nom d'un type de lien suivi d'un deux-points.

Exemple :

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

La personne D a écrit contre [[opposant:20201209111625]] la personne C.

Astuce : pour améliorer la lisibilité des fiches dans le cosmoscope, Cosma inclut une option pour personnaliser le texte des liens. Dans Préférences › Symbole de lien, saisissez un ou plusieurs caractères Unicode (lettres, chiffres, symboles…). Exemple : ☞. Cette chaîne de caractères remplace l'identifiant entre crochets dans le rendu HTML des fiches.

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

Cet en-tête est créé automatiquement lorsque vous créez une fiche via Cosma. Vous pouvez le modifier ou le reproduire avec un autre logiciel ou manuellement.

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 (---).

Un champ en YAML est composé d'un nom et d'une valeur séparés par un double-points. Cosma reconnaît et utilise les quatre champs suivants.

Titre

title (obligatoire) : titre de la fiche.

Identifiant

id (obligatoire) : identifiant unique de la fiche. 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 : type de la fiche. Facultatif. Un seul type peut être assigné à une fiche. 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, Cosma interprètera le type de la fiche comme non défini (undefined).

Mots-clés

tags (ou keywords) : 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. Vous pouvez utiliser keywords au lieu de tags, dans une logique de compatibilité avec Pandoc. Si une fiche comporte un champ tags et un champ keywords, seuls les mots-clés déclarés dans le champ tags sont interprétés par Cosma.

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]

Autres champs

Vous pouvez ajouter des champs supplémentaires de manière arbitraire, par exemple ceux reconnus par Pandoc.

Pourquoi un en-tête en YAML ?

Certains logiciels identifier les métadonnées d'un fichier de manière heuristique. Par exemple, si la première ligne du fichier est un titre de niveau 1, alors il sera interprété comme le titre du fichier ; si la seconde ligne contient des mots préfixés par un croisillon #, alors ils seront interprétés comme des mots-clés.

L'inconvénient de ce fonctionnement est qu'il n'est pas interopérable : chaque logiciel a ses propres conventions, ce qui limite la capacité de l'utilisateur à changer d'outil.

Utiliser un en-tête en YAML permet de déclarer des métadonnées comme le titre et l'identifiant unique d'une fiche de manière explicite. Ceci présente l'avantage de rendre triviale la détection et la manipulation de ces métadonnées, aussi bien par une machine que par un humain. L'utilisation d'un format commun (comme YAML) augmente le nombre d'outils compatibles avec un même ensemble de fichiers. Et des outils informatiques très répandus comme les expressions régulières et les scripts shell permettent aux utilisateurs de convertir eux-mêmes leurs données de manière relativement simple si besoin.

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. Vous pouvez utiliser keywords au lieu de tags, dans une logique de compatibilité avec Pandoc. Si une fiche comporte un champ tags et un champ keywords, seuls les mots-clés déclarés dans le champ tags sont interprétés par Cosma.

Cliquez sur Fichier › Partager (Cmd/Ctrl + E) pour lancer la génération d'un → cosmoscope destiné à être partagé.

Deux options sont disponibles :

• Traiter les citations : traite les clés de citation et ajoute la bibliographie aux fiches.
• CSS personnalisée : applique la CSS personnalisée renseignée dans la configuration de Cosma.

Note : si les options sont grisées, c'est que les paramètres correspondants dans Préférences ne sont pas renseignés.

Les cosmoscopes exportés via le menu Partager intègrent les métadonnées (titre, auteur, description, mots-clés) éventuellement renseignées dans Préférences › Métadonnées. Elles sont affichées dans le panneau « À propos ». Elles sont également incluses dans le code source du cosmoscope sous la forme de balises meta, afin d'améliorer la description d'un cosmoscope destiné à être publié sur le Web.

La barre d'outils présente au sommet du menu latéral gauche ne fonctionne que dans l'application Cosma. Elle est donc masquée dans les cosmoscopes exportés via Partager. Si un titre a été renseigné dans Préférences › Métadonnées, il s'affiche à l'emplacement qu'occupe habituellement la barre d'outils.

Le fichier cosmoscope.html exporté peut être partagé comme n'importe quel fichier informatique : email, transfert de fichiers, messagerie, mise en ligne sur un serveur…

Dans le cas d'un cosmoscope publié sur le Web, il est possible de créer un lien directement vers une fiche en ajoutant son identifiant précédé d'un croisillon # en fin d'URL. Exemple :

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

Le champ de texte situé en haut du panneau latéral gauche est un moteur de recherche qui fonctionne sur les titres de fiches. Il suggère une liste de fiches dont le titre est le plus proche de ce que vous saisissez dans la barre de recherche (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 ou l'autre de ces fonctionnalités ne sera pas accessible via le moteur de recherche. Lorsque vous voulez repartir de zéro pour une nouvelle requête, vous pouvez cliquer sur Réinitialiser l'affichage (raccourci : Alt + R).

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é dans Préférences › Types de fiches et être attribué à au moins une fiche.

Les fiches listées dans l’→ index ainsi que les suggestions affichées par le → moteur de recherche sont affectées par les filtres → par types et → par mots-clés, ainsi que par 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 et ne sera pas visible dans l'index.

Lorsque vous voulez commencer une nouvelle exploration, vous pouvez cliquer sur Réinitialiser l'affichage (raccourci : Alt + R). Toutes les fiches seront à nouveau listées dans l'index et accessible via le moteur de recherche.

À tout moment, l'état du graphe (fiche sélectionnée, filtres actifs, mode focus) peut être sauvegardé pour un accès rapide. Ceci fonctionne comme un marque-page. Cliquez sur le bouton Sauvegarder la vue et indiquez un nom. 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.

Les vues sont conservées à l'export. En revanche, il n'est pas possible de créer de nouvelle vue depuis un export. Ceci n'est possible que dans l'application.