Cosma — Manuel d’utilisation (CLI)

Version : CLI v.2.0.0-beta-2

Dernière mise à jour : 24 janvier 2023

Installation et mise à jour

Installation

Cosma CLI est disponible pour macOS, Windows et Linux.

L'installation de NodeJS version 12 minimum est requise.

Le gestionnaire de paquets NPM est installé automatiquement avec NodeJS. NPM peut être utilisé pour gérer l'installation de Cosma CLI. Entrez la commande ci-dessous dans votre terminal pour installer Cosma CLI de manière globale. Le logiciel s'exécute alors en écrivant cosma.

npm install @graphlab-fr/cosma -g

Si vous souhaitez installer Cosma CLI comme dépendance d'un projet NodeJS, utilisez la commande ci-dessous. Le logiciel s'exécute alors depuis la racine du projet en écrivant ./node_modules/.bin/cosma.

npm install @graphlab-fr/cosma

Mise à jour

La commande suivante affiche la liste des paquets installés via NPM pour lesquels une mise à jour existe :

npm outdated

La commande suivante met à jour Cosma CLI si une mise à jour existe :

npm update cosma

Présentation

Cosma CLI est la version ligne de commande (command-line interface, CLI) de Cosma, un logiciel qui permet de représenter des graphes documentaires sous forme de réseaux interactifs dans une interface web.

Cosma CLI fonctionne sur la base de fichiers de configuration écrits en YAML. Chaque fichier de configuration indique une source des données à utiliser, ainsi que différents paramètres qui régissent le comportement de Cosma pour cette source de données.

Deux approches peuvent être adoptées en fonction des besoins :

La première consiste à exécuter la commande cosma dans un répertoire où se trouve un fichier de configuration. On parle dans ce cas de fichier de configuration local. Les fichiers de configuration locaux doivent toujours être nommés config.yml.

L'autre approche consiste à exécuter la commande cosma en ajoutant l'option --project <nom>, où <nom> correspond au nom d'un fichier de configuration présent dans un dossier spécial, le répertoire de données utilisateur. On parle dans ce cas de fichier de configuration global, ou projet. Celui-ci peut être nommé librement (ex : toto.yml). Cette seconde approche permet d'exécuter la commande cosma depuis n'importe quel emplacement.

La commande cosma

La commande cosma s'utilise de trois manières :

1. cosma affiche l'aide ;
2. cosma <option> exécute une option globale ;
3. cosma <commande> <options> exécute l'une des cinq commandes de Cosma (config, record, autorecord, batch et modelize), avec une ou plusieurs options facultatives.

Les cinq commandes existent en version longue et en version courte (ex : cosma config ou cosma c). Certaines options disposent également d'une version courte (ex : cosma config --global ou cosma config -g). Dans les deux cas, version longue et version courte sont fonctionnellement identiques ; la version courte sert simplement à gagner du temps lors d'une utilisation répétée et prolongée.

Les sous-sections qui suivent détaillent les options globales.

Créer le répertoire de données utilisateur

cosma --create-user-data-dir

Cette commande crée un répertoire de données utilisateur intitulé cosma-cli à un emplacement qui respecte la spécification XDG Base Directory. L'emplacement exact dépend de chaque système d'exploitation et peut varier d'une version à l'autre d'un même système.

Si le répertoire de données utilisateur existe déjà, la commande affiche simplement son emplacement.

Afficher les projets

cosma --list-projects

Cette commande liste les fichiers de configuration présents dans le répertoire de données utilisateur, aussi appelés projets.

Afficher le numéro de version

cosma --version
cosma -V

Afficher l'aide

Cosma dispose d'une aide générale :

cosma --help
cosma -h

Une aide contextuelle est également disponible pour les cinq commandes de Cosma. Ajoutez l'option -h/--help à l'une de ces commandes pour afficher l'aide contextuelle.

Exemple :

cosma config --help

Configuration

Créer un fichier de configuration

cosma config
cosma c

Cette commande crée un fichier config.yml dans le répertoire actuel.

Créer un fichier de configuration global (projet)

cosma config --global <nom>
cosma c -g <nom>

L'option -g/--global suivie d'un nom crée un fichier nom.yml dans le répertoire de données utilisateur.

Créer un fichier de configuration par défaut

cosma config --global
cosma c -g

Lorsqu'elle n'est pas suivie d'un nom, l'option -g/--global crée un fichier defaults.yml dans le répertoire de données utilisateur. Ce fichier peut être ensuite modifié pour définir les valeur par défaut des différents paramètres de configuration de Cosma. Ces valeurs par défaut seront appliquées aux fichiers de configuration créés par la suite.

Paramètres de configuration

Vous trouverez ci-dessous la liste des paramètres utilisés par Cosma. Si un paramètre est absent d'un fichier de configuration, Cosma considère qu'il a sa valeur par défaut.

Modèle de configuration

Voici le modèle utilisé par Cosma pour générer un fichier de configuration :

select_origin: directory
files_origin: ''
nodes_origin: ''
links_origin: ''
nodes_online: ''
links_online: ''
images_origin: ''
export_target: ''
history: true
focus_max: 2
record_types:
  undefined:
    fill: '#858585'
    stroke: '#858585'
link_types:
  undefined:
    stroke: simple
    color: '#e1e1e1'
record_filters: []
graph_background_color: '#ffffff'
graph_highlight_color: '#ff6a6a'
graph_highlight_on_hover: true
graph_text_size: 10
graph_arrows: true
node_size_method: degree
node_size: 10
node_size_max: 20
node_size_min: 2
attraction_force: 200
attraction_distance_max: 250
attraction_vertical: 0
attraction_horizontal: 0
views: {}
chronological_record_meta: last_edit
record_metas: []
title: ''
author: ''
description: ''
keywords: []
link_symbol: ''
csl: ''
bibliography: ''
csl_locale: ''
css_custom: ''
devtools: false
lang: en

Créer du contenu : données tabulaires (CSV)

Lorsque la source de données est de type csv ou online (données tabulaires situées dans un fichier local ou en ligne), les données doivent respecter les règles suivantes.

Fichiers de données : nœuds et liens

Les données tabulaires destinées à Cosma doivent être contenues dans deux fichiers : un pour les nœuds et un autre pour les liens. Les noms de ces fichiers doivent être renseignés dans le fichier de configuration.

Métadonnées (en-têtes de colonnes)

Les fichiers de données doivent contenir des en-têtes de colonnes correspondant aux métadonnées utilisées par Cosma.

Métadonnées pour les nœuds

Pour les nœuds, seule la métadonnée title (titre) est requise.

Métadonnées pour les liens

Créer du contenu : fichiers texte (Markdown)

Lorsque la source de données est de type directory (répertoire de fichiers Markdown), les données doivent respecter 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 numériques (suite unique de chiffres).

Les sous-sections qui suivent expliquent ces règles en détail.

Métadonnées

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 la fiche est créée via Cosma.

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.

Conformément à la spécification YAML, les listes peuvent être inscrite en mode block :

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

Ou bien en mode flow :

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

Métadonnées reconnues

Cosma reconnaît et utilise les champs suivants :

title

Obligatoire.

Titre de la fiche.

id

Obligatoire.

Identifiant unique de la fiche (série unique de chiffres). 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

Types de la fiche. Facultatif. Une fiche peut avoir un ou plusieurs types. Si le champ n'est pas renseigné ou bien que ses valeurs ne correspondent pas à l'un des types renseignés dans la configuration, Cosma interprètera le type de la fiche comme non défini (undefined).

tags (ou keywords)

Mots-clés de la fiche. Facultatif. La valeur doit être une liste. Il est possible d'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.

thumbnail

Facultatif.

Nom de fichier d'une image à utiliser comme vignette pour cette fiche dans le cosmoscope (à l'intérieur du nœud correspondant et en haut du panneau de droite lorsque la fiche est ouverte).

begin

Facultatif.

Métadonnée temporelle utilisée pour le mode chronologique.

end

Facultatif.

Métadonnée temporelle utilisée pour le mode chronologique.

Ajouter d'autres métadonnées

Il est possible d'ajouter librement d'autres métadonnées dans l'en-tête YAML. Par défaut, Cosma ignore ces métadonnées au moment de créer un cosmoscope : elles ne sont pas incluses dans le rendu HTML des fiches. Pour que ces métadonnées soient prises en compte, inscrivez-les dans le fichier de configuration au niveau du champ record_metas.

Exemple :

record_metas: [author, date, lang]

Contenu

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

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. Cosma supporte également l'ajout d'attributs via des accolades, comme présenté ci-dessous.

Ce paragraphe sera en rouge{.red}

<div class="red">Ce paragraphe sera en rouge</div>

Les images au format JPG ou PNG peuvent être incluses dans le cosmoscope via la syntaxe Markdown. Exemple :

![Texte alternatif](image.jpg)

Pour réduire la taille du cosmoscope, privilégiez les images hébergées sur le Web et incluses via une URL. Exemple :

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

Liens

À 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.

À partir de la v2, vous pouvez également inclure le texte du lien entre les 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.

Identifiants uniques

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

L'identifiant doit être une suite de chiffres.

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.

À terme, nous souhaitons permettre à l'utilisateur de définir un motif d'identifiant de son choix, à la manière de Zettlr.

Créer des fiches

record : créer une fiche (mode formulaire)

cosma record
cosma r

Cette commande permet de créer une fiche à la manière d'un formulaire. Une fois la commande lancée, le logiciel demande successivement de saisir un titre, un ou plusieurs types, et un ou plusieurs mots clés. Seul le titre est obligatoire.

autorecord : créer une fiche (mode one-liner)

cosma autorecord <titre> <type> <mots-clés>
cosma a <titre> <type> <mots-clés>

Cette commande permet de créer une fiche en une seule saisie. Seul le titre est obligatoire. Si vous saisissez plusieurs types ou plusieurs mots-clés, séparez-les par des virgules (les espaces suivant la virgule sont ignorés). Exemple : type A, type B, mot-clé1, mot-clé2.

batch : créer un lot de fiches

cosma batch <chemin>
cosma b <chemin>

Cette commande permet de créer plusieurs fiches d'un coup. <chemin> correspond à l'emplacement d'un fichier au format JSON ou CSV décrivant les fiches à créer. Comme pour tous les autres modes de création de fiches, le titre (title) est obligatoire et les autres champs sont facultatifs.

Exemple de fichier JSON contenant deux fiches :

[
  {
    "title": "Titre de la fiche"
  },
  {
    "title": "Paul Otlet",
    "type" : ["Personne", "Histoire"],
    "metas": {
        "prenom" : "Paul",
        "nom" : "Otlet"
    },
    "tags" : ["documentation"],
    "begin" : "1868",
    "end" : "1944",
    "content" : "Lorem...",
    "thumbnail" : "image.jpg",
    "references" : ["otlet1934"]
  }
]

Exemple de fichier CSV contenant ces mêmes fiches :

title,content,type:nature,type:field,meta:prenom,meta:nom,tag:genre,time:begin,time:end,thumbnail,references
Titre de la fiche,,,,,,,,,,,
Paul Otlet,Lorem...,Personne,Histoire,Paul,Otlet,homme,1868,1944,image.png,otlet1934

modelize : créer un cosmoscope

cosma modelize
cosma m
cosma modelize --citeproc --custom-css

Générer un cosmoscope d'exemple

cosma modelize --sample

Cette commande permet de générer un cosmoscope d'exemple. Ceci ne requiert pas de fichier de configuration. Le cosmoscope contient un extrait du manuel d'utilisation de Cosma sous forme hypertextuelle.

Traiter les citations

cosma modelize --citeproc

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"
  }
]

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]…

Rendu des citations et bibliographies

Lors du traitement des citations, chaque clé de citation est 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, p. 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 également incluses 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">.

Appliquer une CSS personnalisée

cosma modelize --custom-css

Il est possible de personnaliser l'apparence d'un cosmoscope via une feuille de styles CSS. Pour cela, renseignez son emplacement au niveau du paramètre css_custom dans le fichier de configuration et appliquez l'option --custom-css au moment de générer le cosmoscope.

Pour élaborer votre CSS, ouvrez le cosmoscope dans un navigateur web et utiliser les outils de développement du navigateur pour inspecter le code, ou bien consultez 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). Ceci vous permettra de connaître les sélecteurs à utiliser pour telle ou telle déclaration CSS.

Les feuilles de style du cosmoscope utilisent 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;
}

Utiliser un fichier de configuration global

cosma modelize --project <nom>
cosma m -p <nom>

L'option -p/--project applique les paramètres du projet nom.

Exclure certaines fiches du cosmoscope

Il est possible d'exclure certaines fiches du cosmoscope sur la base du paramètre record_filters. Celui-ci prend pour valeur une liste dont les éléments peuvent être des types, des mots-clés ou des valeurs prises par les métadonnées déclarées dans record_metas. Les fiches dont l'en-tête contient au moins un élément de la liste sont exclues au moment de générer le cosmoscope.

record_filters:
  - meta: <type/tag/nom de métadonnée>
    value: <valeur du type/tag/de la métadonnée>

Pour chaque filtre, le paramètre meta prend pour valeur soit type (type de fiche), soit tag (mot-clé), soit le nom d'une métadonnée déclarée dans record_metas. Le paramètre value prend pour valeur le type, le mot-clé ou la valeur de métadonnée sur laquelle exclure les fiches.

Voici un exemple. Considérez la fiche suivante :

---
title: Paul Otlet
type: personne
groupe: auteurs
tags: [documentation, pacifisme]
---

Paul Otlet (1868-1944) est un avocat, bibliographe
et militant pacifiste belge considéré comme le
fondateur de la documentation moderne…

La métadonnée groupe peut être déclarée via record_metas dans le fichier de configuration :

record_metas: [groupe]

Ceci permet d'utiliser la métadonnée groupe (en plus du titre et des mots-clés) comme critère pour exclure certaines fiches via record_filters. Dans l'exemple ci-dessous, toutes les fiches contenant groupe: auteurs et/ou le mot-clé pacifisme sont exclues :

record_filters:
  - meta: groupe
    value: auteurs
  - meta: tag
    value: pacifisme

Historique

Par défaut, Cosma exporte automatiquement une copie de chaque cosmoscope dans un répertoire history. Ceci peut être désactivé en renseignant history: false dans le fichier de configuration.

Rapport d'erreurs

Si Cosma rencontre des problèmes durant la génération d'un cosmoscope, il crée un rapport d'erreurs dans un sous-répertoire logs du répertoire de données utilisateur. Si ce dernier n'existe pas, logs est placé dans le répertoire d'installation de Cosma.

Utilisation du cosmoscope

Le cosmoscope est un fichier HTML. Pour l'utiliser, ouvrez-le dans un navigateur web.

Le cosmoscope est organisé 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).

Graphe

Le graphe situé 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.

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é (dont la fiche est ouverte). 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 située au sommet du panneau latéral gauche témoigne de l'état de la simulation (en cours ou bien terminée). Cliquez sur cette barre (raccourci : touche Espace) pour lancer un cycle de simulation supplémentaire.

Le graphe n'est pas figé, les nœuds peuvent donc être déplacés par cliquer-glisser. Cependant, les nœuds et liens restent soumis en permanence à la simulation, donc il n'est pas possible de les disposer manuellement de manière arbitraire. Chaque modification du cosmoscope est susceptible de modifier la disposition des nœuds dans l'espace.

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 le fichier de configuration.

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.

Fiches

Les fiches peuvent être 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.

Ouvrir une fiche met à jour l'URL de la page dans le navigateur. 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 de lecture 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.

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.

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

Moteur de recherche

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.

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é dans le fichier de configuration et être attribué à au moins une fiche.

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électionné. 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 l'en-tête YAML d'au moins une fiche avec le champ tags (ou keywords).

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.

Vues

Les Vues sont une fonctionnalité de la version GUI de Cosma, qui consiste à sauvegarder l'état du graphe (fiche sélectionnée, filtres actifs, mode focus) pour un accès ultérieur, via l'ajout d'un bouton 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. Il n'est pas possible de créer de vue depuis un cosmoscope en dehors de la version GUI.

Partage et publication d'un cosmoscope

Les cosmoscopes intègrent les métadonnées titre, auteur, description et mots-clés si elles ont été renseignées dans le fichier de configuration. Ces 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, afin d'améliorer la description d'un cosmoscope destiné à être publié sur le Web.

Un cosmoscope 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

Crédits

Équipe

• Arthur Perret (porteur du projet)
• Guillaume Brioudes (développeur)
• Clément Borel (chercheur)
• Olivier Le Deuff (chercheur)

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 :

• D3.js v4.13.0 (BSD 3-Clause) : Génération du graphe
• Nunjucks v3.2.3 (BSD 2-Clause) : Génération du template du cosmoscope
• Js-yaml v4.1.0 (MIT License) : Lecture du fichier de configuration et écriture de l'en-tête YAML
• Js-yaml-front-matter v4.1.1 (MIT License) : Lecture de l'en-tête YAML des fichiers Markdown
• Markdown-it v12.3.0 (MIT License) : Conversion Markdown → HTML
• Markdown-it-attrs v4.0.0 (MIT License) : Traitement des hyperliens Markdown au sein des fiches
• Citeproc-js v2.4.62 (CPAL et AGPL) : Conversion des clés de citation
• Fuse.js v6.4.6 (Apache License 2.0) : Moteur de recherche

Changelog

v2-beta-2

Améliorations

• L'enregistrement automatique des cosmoscopes se fait dans un sous-répertoire history, soit dans le répertoire de données utilisateur pour les configurations globales, soit dans le même répertoire que la configuration locale pour cette dernière.

Bugs résolus

• Le chemin d'exécution sur Windows est correctement trouvé, ce qui permet la bonne exécution de l'application.
• Le répertoire de données utilisateur se crée correctement sur Windows.
• Le dossier logs contenant les rapports d'erreurs se crée correctement.
• Les titres de fiches contenant seulement une date au format YYYY-MM-DD sont interprétés correctement.

v2-beta-1

Ajouts

• Gérer plusieurs configurations (globales et locales)
• Utiliser une syntaxe alternative pour les liens
• Inclure des métadonnées supplémentaires lors de la création par lots (batch)
• Afficher des métadonnées supplémentaires dans les fiches dans le cosmoscope
• Exclure certaines fiches lors de la génération du cosmoscope, sur la base des types, mots-clés et métadonnées supplémentaires
• Afficher les nœuds en mode chronologique
• Embarquer des images dans le cosmoscope (en base64). Formats pris en charge : JPG, PNG
• Associer une image à un type de fiche
• Associer une image à une fiche (affichée sur le nœud et dans la fiche)
• Définir une couleur de contour pour les types de nœuds
• Choisir entre nœuds de taille fixe et de taille proportionnelle à leur degré

Améliorations

• Les liens en bibliographie sont désormais cliquables
• Les messages affichés à l'exécution des commandes sont plus informatifs
• Le rapport d'erreurs et d'avertissements est plus informatif
• Les mots-clés au sommet des fiches dans le cosmoscope ne débordent plus de la mise en page
• Cosma lit désormais les répertoires de fiches de manière récursive (ticket #4)

Bugs résolus

• Les infobulles de contexte des liens/rétroliens mettent correctement en évidence la fiche cible (ticket #23)
• Les espaces dans les noms de fichiers générés par Cosma sont correctement remplacés par des tirets

Bugs connus

• Le traitement des citations échoue parfois dans les infobulles de contexte des rétroliens