This repository has been archived by the owner on Jul 29, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
manuel-d-utilisation.html
903 lines (847 loc) · 61.6 KB
/
manuel-d-utilisation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
<!doctype html>
<html lang="fr">
<head>
<meta charset=utf-8 />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="generator" content="">
<title>Manuel d’utilisation | Cosma</title>
<meta name="description" content="Manuel d’utilisation de Cosma. Explique comment installer et utiliser la version à interface graphique (GUI)." />
<meta name="author" content="Arthur Perret,Guillaume Brioudes" />
<meta name="copyright" content="GPL-3.0-or-later"/>
<meta name="last_edit" content="2023-03-03" />
<meta property="og:type" content="website" />
<meta property="og:title" content="Manuel d’utilisation" />
<meta property="og:description" content="Manuel d’utilisation de Cosma. Explique comment installer et utiliser la version à interface graphique (GUI)." />
<meta property="og:site_name" content="cosma-docs" />
<meta itemprop="name" content="cosma-docs" />
<meta itemprop="description" content="Manuel d’utilisation de Cosma. Explique comment installer et utiliser la version à interface graphique (GUI)." />
<link rel="schema.DC" href="https://purl.org/dc/elements/1.1/" />
<link rel="schema.DCTERMS" href="https://purl.org/dc/terms/" />
<meta property="DC.title" content="Manuel d’utilisation" />
<meta property="DC.contributor" content="Arthur Perret,Guillaume Brioudes" />
<meta property="DC.date" content="2023-03-03" />
<meta property="DC.language" content="fr" />
<meta property="DC.description" lang="fr" content="Manuel d’utilisation de Cosma. Explique comment installer et utiliser la version à interface graphique (GUI)." />
<meta property="DC.rights" content="GPL-3.0-or-later" />
<meta name="twitter:site" content="@arthurperret" />
<meta name="twitter:creator" content="@arthurperret" />
<meta name="twitter:title" content="Manuel d’utilisation" />
<meta name="twitter:description" content="Manuel d’utilisation de Cosma. Explique comment installer et utiliser la version à interface graphique (GUI)." />
<meta name="twitter:card" content="summary" />
<meta name="twitter:image" content="https://cosma.graphlab.fr/img/cosma-icone.png" />
<style>
:root {
--sans: "Helvetica Neue", Helvetica, sans-serif;
--serif: "Georgia", 'Garamond', 'Time New Roman', 'Times', serif;
--mono: Menlo, Monaco, Consolas, "Courier New", monospace;
--code-background-color: #f5f5f5;
--code-border-color: #ccc;
}
/* LAYOUT */
* {
box-sizing: border-box;
}
body {
margin: 0;
padding: 0 1em;
line-height: 1.5;
max-width: 1000px;
margin: 0 auto;
font-family: var(--serif);
display: grid;
grid-template-columns: 70% 30%;
grid-gap: 0 1%;
grid-template-areas: "header header"
"main aside"
"footer footer";
}
header {
grid-area: header;
}
nav.nav-lang {
grid-area: headernav;
font-family: var(--sans);
}
.nav-lang ul {
display: flex;
justify-content: space-between;
list-style:none;
padding: 0;
margin-top: 1.8em;
}
main {
grid-area: main;
padding-bottom: 5vh;
}
/* HEADINGS */
header, h1, h2, h3, h4 {
font-family: var(--sans);
}
h2, h3, h4 {
line-height: 1.2;
padding-bottom: 0.2em;
border-bottom: 1px solid black;
font-size: 1.2em;
}
main h2 {
font-size: 1.3em;
margin: 3.5rem 0 0.5rem 0;
}
main > h2:first-child {
margin-top: 0;
}
main h3 {
font-size: 1.2em;
margin: 3rem 0 0.3rem 0;
}
main h4 {
font-size: 1em;
margin: 2rem 0 0 0;
}
/* LINKS */
a {
color: #0056b3;
text-decoration: none;
}
a:hover {
color: #00448f;
text-decoration: underline;
}
:target { animation: highlight 3s ease; }
@keyframes highlight {
0% { background-color: #ffa; }
100% { background-color: #ffffff; }
}
/* TABLES */
table {
border-collapse: collapse;
margin: 2rem 0;
text-align: left;
width: 100%;
}
tr { border: 1px solid gray; }
th, td { border: 1px solid gray; padding: 0.5rem; }
/* LISTS */
ul, ol {
padding-left: 1rem;
}
dt {
font-family: var(--sans);
font-weight: bold;
float: left;
padding: 0 0.5rem 0 0;
line-height: 1.4;
}
dd {
padding: 0;
margin: 1rem 0 1rem 2rem;
}
/* MEDIA */
img {
max-width: 100%;
}
figure {
display: flex;
flex-direction: column;
align-items: center;
border: var(--accent-color) 1px solid;
padding: 15px 10px;
}
figcaption {
font-size: 0.8rem;
font-style: italic;
padding: 1rem 0 0 0;
}
/* ADMONITIONS */
.astuce, .tip, .note, .important {
position: relative;
background: rgb(225, 225, 225);
padding: 30px 10px 3px 10px;
border-radius: 5px;
margin: 1.5rem 0;
font-size: 0.9rem;
}
.astuce::before,
.tip::before,
.note::before,
.important::before {
content: attr(class);
position: absolute;
top: 5px;
left: 5px;
font-size: 12px;
font-family: var(--mono);
}
.astuce, .tip, .note {
background: rgb(225, 225, 225);
}
.important {
background: rgb(239,178,178);
}
/* CODE */
code, pre {
font-family: var(--mono);
}
code {
display: inline-block;
font-size: 90%;
}
p code,
ul code,
ol code,
dl code,
table code {
background-color: var(--code-background-color);
border-radius: 4px;
padding: 0 0.2em;
}
pre {
background-color: var(--code-background-color);
border: 1px solid var(--code-border-color);
border-radius: 4px;
padding-left: 0.5em;
margin: 1em 0;
overflow-x: auto;
}
/* ASIDE (TOC) */
aside {
grid-area: aside;
position: sticky;
height: 80vh;
top: 2em;
padding-left: 3em;
font-size: 0.875em;
font-family: var(--sans);
}
aside ul {
list-style-type: none;
}
aside > nav > ul > li {
position: relative;
padding-bottom: 0.75em;
}
aside .toggle {
cursor: pointer;
position: absolute;
left: -28px;
top: -2px;
padding: 2px 10px;
color: #0056b3;
}
/* FOOTER */
footer {
grid-area: footer;
}
/* DARK MODE */
/* Inspiré par Bradley Taunt */
/* https://tdarb.org/lazy-dev-dark-mode/ */
@media (prefers-color-scheme: dark) {
body {
background: #2d2d2d;
filter:invert(1);
}
a,
img,
pre,
*:not(pre) > code {
filter:invert(1);
}
aside .toggle {
color: #5e421b;
}
a {
color: #B2CCE8;
}
.astuce, .tip, .note {
background: #b4b4b4;
}
.important {
background: #67f3f4;
}
}
@media screen and (max-width: 1000px) {
body {
display: block;
max-width: 700px;
margin: 0 auto;
}
header > *,
main {
margin-right: auto;
margin-left: auto;
width: 100%;
}
main {
padding-bottom: 3vh;
}
aside {
position: relative;
height: auto;
padding-left: 5vw;
top: 0;
}
aside h1 {
display: block
}
.nav-lang ul {
justify-content: flex-end;
}
.nav-lang ul li {
padding-left: 1em;
}
}
</style>
</head>
<body>
<header>
<article>
<h1 class="title-site">Cosma — Manuel d’utilisation</h1>
</article>
</header>
<aside id="toc">
<nav class="toc" >
<ul><li><a href="#installation-et-mise-a-jour">Installation et mise à jour</a><ul><li><a href="#installation">Installation</a></li><li><a href="#mise-a-jour">Mise à jour</a></li></ul></li><li><a href="#parametrer-le-logiciel">Paramétrer le logiciel</a></li><li><a href="#creer-un-projet">Créer un projet</a></li><li><a href="#creer-du-contenu-fichiers-texte-(markdown)">Créer du contenu : fichiers texte (Markdown)</a><ul><li><a href="#metadonnees">Métadonnées</a></li><li><a href="#contenu">Contenu</a></li><li><a href="#liens">Liens</a></li><li><a href="#identifiants-uniques">Identifiants uniques</a></li><li><a href="#creer-une-fiche-via-cosma">Créer une fiche via Cosma</a></li></ul></li><li><a href="#creer-du-contenu-donnees-tabulaires-(csv)">Créer du contenu : données tabulaires (CSV)</a></li><li><a href="#creer-un-cosmoscope">Créer un cosmoscope</a><ul><li><a href="#traiter-les-citations">Traiter les citations</a></li><li><a href="#appliquer-une-css-personnalisee">Appliquer une CSS personnalisée</a></li><li><a href="#exclure-certaines-fiches-du-cosmoscope">Exclure certaines fiches du cosmoscope</a></li><li><a href="#rapport-derreurs">Rapport d'erreurs</a></li></ul></li><li><a href="#historique">Historique</a></li><li><a href="#utilisation-du-cosmoscope">Utilisation du cosmoscope</a><ul><li><a href="#description-generale-de-linterface">Description générale de l'interface</a></li><li><a href="#graphe">Graphe</a></li><li><a href="#fiches">Fiches</a></li><li><a href="#mode-focus">Mode focus</a></li><li><a href="#moteur-de-recherche">Moteur de recherche</a></li><li><a href="#filtrer-laffichage-par-types">Filtrer l'affichage par types</a></li><li><a href="#mots-cles">Mots-clés</a></li><li><a href="#index">Index</a></li><li><a href="#vues">Vues</a></li></ul></li><li><a href="#partager-un-cosmoscope">Partager un cosmoscope</a></li><li><a href="#configuration">Configuration</a><ul><li><a href="#general">Général</a></li><li><a href="#types-de-fiches">Types de fiches</a></li><li><a href="#types-de-liens">Types de liens</a></li><li><a href="#graphe-1">Graphe</a></li><li><a href="#metadonnees-1">Métadonnées</a></li><li><a href="#bibliographie">Bibliographie</a></li><li><a href="#vues-1">Vues</a></li><li><a href="#avance">Avancé</a></li></ul></li><li><a href="#credits">Crédits</a><ul><li><a href="#equipe">Équipe</a></li><li><a href="#bibliotheques-utilisees">Bibliothèques utilisées</a></li></ul></li><li><a href="#changelog">Changelog</a><ul><li><a href="#v20">v2.0</a></li><li><a href="#v12">v1.2</a></li><li><a href="#v11">v1.1</a></li></ul></li></ul>
</nav>
</aside>
<main>
<p><strong>Dernière mise à jour :</strong> 3 mars 2023</p>
<h2 id="installation-et-mise-a-jour" tabindex="-1">Installation et mise à jour</h2>
<h3 id="installation" tabindex="-1">Installation</h3>
<p>Cosma est disponible en deux versions : une application à interface graphique (<em>graphical user interface</em>, GUI) et une application exécutable en ligne de commande (<em>command line interface</em>, CLI). Les informations concernant la version CLI sont détaillées <a href="https://cosma.graphlab.fr/docs/cli/manuel-utilisation/">sur une page dédiée</a>.</p>
<p>La version GUI de Cosma est disponible pour macOS, Windows et Linux. Visitez <a href="https://cosma.graphlab.fr/telecharger/">la page Télécharger du site pour obtenir la dernière version du logiciel</a>.</p>
<div class="important">
<p>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.</p>
</div>
<dl>
<dt>Sur macOS</dt>
<dd>Téléchargez puis décompressez le fichier <code>Cosma.app.zip</code> et placez le le fichier <code>Cosma.app</code> dans <code>~/Applications</code>. Au premier lancement, faites clic droit › Ouvrir sur l'application pour l'exécuter.</dd>
<dt>Sur Windows</dt>
<dd>Téléchargez puis décompressez le fichier <code>Cosma-win32-x64.zip</code>, renommez le dossier « Cosma » et placez-le dans <code>C:\Programmes</code> ou <code>C:\Programmes (86)</code>.</dd>
<dt>Sur Linux</dt>
<dd>
<!-- À COMPLÉTER -->
</dd>
</dl>
<p>L’installation de Cosma crée automatiquement un dossier support à l’emplacement suivant (où <code>*</code> est à remplacer par le nom de l’utilisateur) :</p>
<dl>
<dt>Sur macOS</dt>
<dd><code>/Users/*/Library/Application Support/cosma</code></dd>
<dt>Sur Windows</dt>
<dd><code>C:\Utilisateurs\*\AppData\Roaming\cosma</code></dd>
<dt>Sur Linux</dt>
<dd>
<!-- À COMPLÉTER -->
</dd>
</dl>
<h3 id="mise-a-jour" tabindex="-1">Mise à jour</h3>
<!-- À COMPLÉTER -->
<p>Vous pouvez également être averti d’une mise à jour en vous abonnant à l’une ou l’autre de ces sources :</p>
<ul>
<li><a href="https://groupes.renater.fr/sympa/info/cosma-annonces">cosma-annonces</a> (liste de diffusion par email dédiée exclusivement aux annonces de mises à jour de Cosma) ;</li>
<li><a href="https://cosma.graphlab.fr/feed.xml">flux RSS du site de Cosma</a> (contient les notes de version publiées sur le site).</li>
</ul>
<div class="important">
<p><strong>Si Cosma ne fonctionne plus suite à une mise à jour :</strong> la structure du <a href="#dossier-support">dossier support</a> a probablement été modifiée et n’est plus compatible avec l’ancienne version. Supprimez le dossier support et relancez l’application. Le dossier support sera recréé automatiquement et fonctionnera de nouveau correctement. Faites éventuellement au préalable une copie du fichier <code>config.json</code> : cela vous permettra de les rétablir plus rapidement.</p>
</div>
<h2 id="parametrer-le-logiciel" tabindex="-1">Paramétrer le logiciel</h2>
<!-- À COMPLÉTER
### Langue
La langue est appliquée à 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.
-->
<h2 id="creer-un-projet" tabindex="-1">Créer un projet</h2>
<!-- À COMPLÉTER -->
<h2 id="creer-du-contenu-fichiers-texte-(markdown)" tabindex="-1">Créer du contenu : fichiers texte (Markdown)</h2>
<p>Vous pouvez créer du contenu pour Cosma de deux façons : sous forme de fichiers texte rédigés en Markdown, ou bien sous formes de données tabulaires (par exemple via Google Sheets). Cette section porte sur la première méthode.</p>
<div class="important">
<p>Quelle que soit la méthode choisie, Cosma a besoin de connaître l'emplacement des données. Cette information doit être renseignée dans la configuration du projet.</p>
<p>Pour des fichiers texte rédigés en Markdown, sélectionnez le type de source « Répertoire », puis indiquez l'emplacement du répertoire en question. Cosma interprètera les fichiers contenus dans ce répertoire ainsi que dans les sous-répertoires éventuellement présents.</p>
</div>
<p>Cosma ne prescrit pas l'utilisation d'un logiciel d'écriture particulier. En revanche, il interprète uniquement les fichiers texte respectant les quelques règles suivantes :</p>
<ul>
<li>contenu rédigé en Markdown, extension de fichier <code>.md</code> ;</li>
<li>métadonnées exprimées en YAML, dans un en-tête présent en début de fichier ;</li>
<li>liens internes exprimés avec une syntaxe de type wiki (doubles crochets <code>[[ ]]</code>) et basés sur des identifiants uniques (suite unique de chiffres).</li>
</ul>
<p>Les sous-sections qui suivent expliquent ces règles en détail.</p>
<div class="note">
<p>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 scientifique avec Pandoc (utiliser le format texte comme source pour plusieurs autres formats).</p>
<p>Cosma fonctionne donc particulièrement bien lorsqu'il est utilisé en tandem avec des environnements d'écriture qui adoptent également cette approche, comme <a href="https://zettlr.com">Zettlr</a> ou l'extension <a href="https://foambubble.github.io/foam/">Foam</a> pour Visual Studio Code et VSCodium.</p>
</div>
<p>Vous pouvez créer un fichier conforme pour Cosma via le formulaire de l'application (cliquez sur Fichier › Nouvelle fiche ou tapez <code>Ctrl + N</code>) 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 que vous pouvez ensuite utiliser pour créer rapidement des fiches à destination de Cosma.</p>
<h3 id="metadonnees" tabindex="-1">Métadonnées</h3>
<p>Pour être correctement interprétés par Cosma, les fichiers Markdown (<code>.md</code>) doivent respecter une certaine structure, et notamment la présence d'un en-tête en <a href="http://yaml.org">YAML</a> au début du fichier. Cet en-tête est créé automatiquement lorsque la fiche est créée via Cosma.</p>
<p>Exemple :</p>
<pre><code>---
title: Titre du document
id: 20201209111625
type:
- undefined
tags:
- mot-clé 1
- mot-clé 2
---
</code></pre>
<p>L'en-tête YAML est délimité par deux séries de trois tirets seuls sur une ligne (<code>---</code>).</p>
<p>Conformément à la spécification YAML, les listes peuvent être inscrite en mode <em>block</em> :</p>
<pre><code class="language-yaml">tags:
- mot-clé 1
- mot-clé 2
</code></pre>
<p>Ou bien en mode <em>flow</em> :</p>
<pre><code class="language-yaml">tags: [mot-clé 1, mot-clé 2]
</code></pre>
<div class="note">
<p><strong>Pourquoi un en-tête en YAML ?</strong></p>
<p>Certains logiciels identifient 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 celui-ci sera interprété comme le titre du fichier ; si la seconde ligne contient des mots préfixés par un croisillon <code>#</code>, alors ils seront interprétés comme des mots-clés.</p>
<p>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.</p>
<p>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 <em>shell</em> permettent aux utilisateurs de convertir eux-mêmes leurs données de manière relativement simple si besoin.</p>
</div>
<h4 id="metadonnees-reconnues" tabindex="-1">Métadonnées reconnues</h4>
<p>Cosma reconnaît et utilise les champs suivants :</p>
<dl>
<dt><code>title</code></dt>
<dd>Obligatoire.</dd>
<dd>Titre de la fiche.</dd>
<dt><code>id</code></dt>
<dd>Obligatoire.</dd>
<dd>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 <a href="https://zettelkasten.de/the-archive/">The Archive</a> ou <a href="https://www.zettlr.com">Zettlr</a>.</dd>
<dt><code>type</code></dt>
<dd>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 (<code>undefined</code>).</dd>
<dt><code>tags</code> (ou <code>keywords</code>)</dt>
<dd>Mots-clés de la fiche. Facultatif. La valeur doit être une liste. Il est possible d'utiliser <code>keywords</code> au lieu de <code>tags</code>, dans une logique de compatibilité avec Pandoc. Si une fiche comporte un champ <code>tags</code> et un champ <code>keywords</code>, seuls les mots-clés déclarés dans le champ <code>tags</code> sont interprétés par Cosma.</dd>
<dt><code>thumbnail</code></dt>
<dd>Facultatif.</dd>
<dd>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).</dd>
<dt><code>begin</code></dt>
<dd>Facultatif.</dd>
<dd>Métadonnée temporelle utilisée pour le mode chronologique.</dd>
<dt><code>end</code></dt>
<dd>Facultatif.</dd>
<dd>Métadonnée temporelle utilisée pour le mode chronologique.</dd>
</dl>
<h4 id="ajouter-dautres-metadonnees" tabindex="-1">Ajouter d'autres métadonnées</h4>
<p>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, renseignez-les dans la configuration du projet. <!-- PRÉCISER --></p>
<h3 id="contenu" tabindex="-1">Contenu</h3>
<p>Cosma interprète les fichiers comme étant rédigés en <a href="https://spec.commonmark.org/0.30/">CommonMark</a>, une version strictement définie du langage de balisage léger Markdown.</p>
<div class="astuce">
<p>Le <a href="https://www.arthurperret.fr/tutomd/">tutoriel CommonMark traduit en français</a> permet d'apprendre les bases de Markdown en 10 minutes.</p>
<p>Si vous souhaitez découvrir l'utilisation conjointe de Markdown et Pandoc, vous pouvez consulter le cours en ligne <a href="https://infolit.be/md/">Markdown et vous</a>.</p>
</div>
<p>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'<a href="https://www.npmjs.com/package/markdown-it-attrs">ajout d'attributs via des accolades</a>, comme présenté ci-dessous.</p>
<pre><code class="language-markdown">Ce paragraphe sera en rouge{.red}
</code></pre>
<pre><code class="language-html"><div class="red">Ce paragraphe sera en rouge</div>
</code></pre>
<p>Les images au format JPG ou PNG peuvent être incluses dans le cosmoscope via la syntaxe Markdown. Exemple :</p>
<pre><code class="language-markdown">
</code></pre>
<p>Pour réduire la taille du cosmoscope, privilégiez les images hébergées sur le Web et incluses via une URL. Exemple :</p>
<pre><code class="language-markdown">
</code></pre>
<h3 id="liens" tabindex="-1">Liens</h3>
<p>À l'intérieur des fiches, vous pouvez créer des liens avec l'identifiant de la fiche cible entre double crochets.</p>
<p>Exemple :</p>
<pre><code>Un lien vers [[20201209111625]] une fiche.
</code></pre>
<p>Ces liens sont rendus au format HTML avec l'identifiant comme texte cliquable :</p>
<pre><code class="language-html">Un lien vers <a href="#20201209111625">20201209111625</a> une fiche.
</code></pre>
<p>Vous pouvez utiliser l'option Symbole de lien, située dans la configuration du projet, pour définir un texte cliquable qui s'applique à tous les liens entre fiches. Il peut s'agir d'un unique caractère Unicode, comme → ou ☞.</p>
<pre><code>Un lien vers [[20201209111625]] une fiche.
</code></pre>
<pre><code class="language-html">Un lien vers <a href="#20201209111625">→</a> une fiche.
</code></pre>
<p>Vous pouvez également définir manuellement le texte cliquable de chaque lien.</p>
<pre><code>Un lien vers [[20201209111625|une fiche]].
</code></pre>
<pre><code class="language-html">Un lien vers <a href="#20201209111625">→</a> une fiche.
</code></pre>
<p>Enfin, Cosma permet de définir des <a href="#types-de-liens">types de liens</a>. 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. Ceci fonctionne également si vous définissez manuellement le texte cliquable du lien.</p>
<p>Exemple :</p>
<pre><code>Dupont a été critiqué par [[opposant:20201209111625]] Smith.
Dupont a été critiqué par [[opposant:20201209111625|Smith]].
</code></pre>
<h3 id="identifiants-uniques" tabindex="-1">Identifiants uniques</h3>
<p>Pour être correctement interprétée par Cosma, chaque fiche doit avoir un identifiant unique. Cet identifiant sert de cible aux liens internes.</p>
<p><strong>L'identifiant doit être une suite de chiffres.</strong></p>
<p>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 <a href="https://zettelkasten.de/the-archive/">The Archive</a> et <a href="https://www.zettlr.com">Zettlr</a>.</p>
<p>À terme, nous souhaitons permettre à l'utilisateur de définir un motif d'identifiant de son choix, à la manière de Zettlr.</p>
<div class="note">
<p>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 <a href="https://fr.wikipedia.org/wiki/Lien_mort">liens morts</a> 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.</p>
</div>
<h3 id="creer-une-fiche-via-cosma" tabindex="-1">Créer une fiche via Cosma</h3>
<p>Cliquez sur Fichier › Nouvelle fiche (<code>Ctrl/Cmd + N</code>) pour ouvrir le formulaire de création de fiche de Cosma.</p>
<p>Le titre est obligatoire. Les autres champs sont facultatifs.</p>
<p>Vous pouvez assigner un ou plusieurs types à la fiche. Ils doivent être définis préalablement dans la configuration du projet. <!-- PRÉCISER --></p>
<p>Vous pouvez également ajouter des mots-clés à la fiche. Les mots-clés doivent être séparés par des virgules. Exemple : <code>mots-clé 1, mot-clé 2</code>. Une aide visuelle est présente dans ce champ pour confirmer que les mots-clés sont bien saisis (surlignement des mots-clés).</p>
<p>Cliquez sur OK pour créer la fiche.</p>
<div class="note">
<p>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.</p>
<p>Exemple : une fiche intitulée « Métadonnées web sémantique » sera enregistrée comme <code>metadonnees-web-semantique.md</code>.</p>
</div>
<h2 id="creer-du-contenu-donnees-tabulaires-(csv)" tabindex="-1">Créer du contenu : données tabulaires (CSV)</h2>
<!-- À COMPLÉTER -->
<h2 id="creer-un-cosmoscope" tabindex="-1">Créer un cosmoscope</h2>
<p>Cliquez sur Nouveau cosmoscope (<code>Cmd/Ctrl + R</code>) pour lancer la génération d'un nouveau cosmoscope. Il s'affiche automatiquement dans l'interface du logiciel.</p>
<p>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 (<code>Cmd/Ctrl + H</code>) et sélectionnez une entrée pour consulter le rapport d'erreurs associé.</p>
<h3 id="traiter-les-citations" tabindex="-1">Traiter les citations</h3>
<p>Cosma intègre une fonctionnalité de traitement des citations. Elle repose sur le même écosystème que <a href="https://www.zettlr.com">Zettlr</a> : les données et styles bibliographiques utilisent la norme <a href="https://citationstyles.org">Citation Style Language (CSL)</a>, tandis que l'insertion des citations dans le texte se fait avec la <a href="https://pandoc.org/MANUAL.html#citation-syntax">syntaxe de citation de Pandoc</a>.</p>
<h4 id="fichiers-requis" tabindex="-1">Fichiers requis</h4>
<p>Pour traiter automatiquement les citations, Cosma requiert trois fichiers :</p>
<dl>
<dt>Données bibliographiques</dt>
<dd>Fichier contenant les métadonnées décrivant des références bibliographiques. Le format requis est CSL JSON (extension <code>.json</code>).</dd>
<dt>Style bibliographique</dt>
<dd>Fichier contenant les règles de mise en forme des citations et bibliographies. Le format requis est CSL (extension <code>.csl</code>). Vous pouvez télécharger des fichiers de style depuis le <a href="https://www.zotero.org/styles">répertoire de styles CSL de Zotero</a>.</dd>
<dt>Localisation bibliographique</dt>
<dd>Fichier contenant les traductions dans une certaine langue des termes employés en bibliographie (ex : éditeur, numéro…). Le format requis est XML (extension <code>.xml</code>). Vous pouvez télécharger des fichiers de localisation depuis le <a href="https://github.com/citation-style-language/locales/tree/6b0cb4689127a69852f48608b6d1a879900f418b">dépôt GitHub du projet CSL</a>.</dd>
</dl>
<p>Dans le fichier de données, chaque référence doit posséder un identifiant unique (<code>id</code>) qui sert de clé de citation. Exemple :</p>
<pre><code class="language-json">[
{
"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"
}
]
</code></pre>
<div class="astuce">
<p>Vous pouvez utiliser le gestionnaire de références bibliographiques <a href="https://www.zotero.org/">Zotero</a> avec l'extension <a href="https://retorque.re/zotero-better-bibtex/">Better BibTeX</a> afin de créer des clés de citation uniques pour chaque référence ainsi que des exports automatiquement mis à jour.</p>
</div>
<h4 id="syntaxe-de-citation" tabindex="-1">Syntaxe de citation</h4>
<p>Pour citer une référence dans une fiche, intégrez la clé de citation de cette référence en utilisant la <a href="https://pandoc.org/MANUAL.html#citation-syntax">syntaxe de citation de Pandoc</a>.</p>
<p>Exemple :</p>
<pre><code>À propos de raison graphique [@goody1979, 46-52]…
</code></pre>
<h4 id="rendu-des-citations-et-bibliographies" tabindex="-1">Rendu des citations et bibliographies</h4>
<p>Cliquez sur Fichier › Nouveau cosmoscope avec citations (<code>Cmd/Ctrl + Maj + R</code>) pour générer un cosmoscope avec le traitement des citations activé. Le traitement des citations est également disponible lors de l'<a href="#partager-un-cosmoscope">export</a>.</p>
<p>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.</p>
<p>Exemple :</p>
<pre><code>À propos de raison graphique [@goody1979, 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.
</code></pre>
<p>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 <code><article id="citation-references"></code>.</p>
<h3 id="appliquer-une-css-personnalisee" tabindex="-1">Appliquer une CSS personnalisée</h3>
<p>Il est possible de personnaliser l'apparence d'un cosmoscope via une feuille de styles CSS. Pour cela, renseignez son emplacement dans la configuration du projet et sélectionnez l'option CSS personnalisée au moment de générer le cosmoscope.</p>
<p>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 <code>/cosma-core/template.njk</code> (pour connaître la structure HTML du cosmoscope), <code>/cosma-core/styles.css</code> et <code>/cosma-core/print.css</code> (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.</p>
<p>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 <code>custom.css</code> contient des déclarations qui modifient les polices utilisées dans le cosmoscope :</p>
<pre><code class="language-css">:root {
--sans: "IBM Plex Sans", sans-serif;
--serif: "IBM Plex Serif", serif;
--mono: "IBM Plex Mono", monospace;
--condensed: 'Avenir Next Condensed', sans-serif;
}
</code></pre>
<h3 id="exclure-certaines-fiches-du-cosmoscope" tabindex="-1">Exclure certaines fiches du cosmoscope</h3>
<p>Il est possible d'exclure automatiquement certaines fiches du cosmoscope au moment de sa génération. Ceci repose sur des filtres à définir dans la configuration du projet. Un filtre peut être un type, un mot-clé ou une valeur spécifique prise par une métadonnée supplémentaire (pour rappel, celle-ci doit être déclarée dans la configuration du projet). Les fiches dont l'en-tête contient au moins un élément ciblé par un filtre sont exclues au moment de générer le cosmoscope.</p>
<p>Pour créer un filtre, sélectionnez d'abord sa nature (type de fiche, mot-clé, ou métadonnée supplémentaire) puis indiquez la valeur à filtrer.</p>
<h3 id="rapport-derreurs" tabindex="-1">Rapport d'erreurs</h3>
<p>Si Cosma rencontre des problèmes durant la génération d'un cosmoscope, il crée un rapport d'erreurs. Vous pouvez consulter celui-ci via l'historique.</p>
<h2 id="historique" tabindex="-1">Historique</h2>
<p>Par défaut, Cosma exporte automatiquement chaque cosmoscope dans un répertoire <code>cosma-history</code> situé dans les répertoires temporaires du système d'exploitation.</p>
<p>Vous pouvez activer ou désactiver l'enregistrement automatique dans la configuration du projet. <!-- PRÉCISER --></p>
<p>Le cosmocope actif est toujours enregistré dans l'historique comme dernière entrée. C'est cette dernière entrée qui est affichée lors de l'ouverture du projet. 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.</p>
<p>Cliquez sur Fichier › Historique (<code>Cmd/Ctrl + H</code>) pour consulter et gérer les entrées de l'historique à l'aide des boutons suivants :</p>
<dl>
<dt>Modifier la description</dt>
<dd>Ajouter ou modifier le texte décrivant l'entrée d'historique.</dd>
<dt>Ouvrir dans Cosma</dt>
<dd>Ouvrir le cosmoscope dans l'interface de Cosma.</dd>
<dt>Localiser le fichier</dt>
<dd>Révèler le cosmoscope dans l'explorateur de fichiers du système d'exploitation.</dd>
<dt>Rapport d'erreurs</dt>
<dd>Afficher le rapport d'erreurs créé lors de la génération du cosmoscope.</dd>
<dt>Supprimer</dt>
<dd>Supprimer une entrée d'historique.</dd>
<dt>Vider l'historique…</dt>
<dd>Supprimer toutes les entrées de l'historique du projet.</dd>
</dl>
<h2 id="utilisation-du-cosmoscope" tabindex="-1">Utilisation du cosmoscope</h2>
<h3 id="description-generale-de-linterface" tabindex="-1">Description générale de l'interface</h3>
<p>Le cosmoscope est un fichier HTML. Après avoir été généré, il est affiché dans la fenêtre principale de Cosma</p>
<p>Le cosmoscope est organisé en trois colonnes :</p>
<dl>
<dt>Panneau latéral gauche (Menu)</dt>
<dd>Regroupe les fonctionnalités permettant de chercher de l'information et de modifier l'affichage de manière globale.</dd>
<dt>Zone centrale (Graphe)</dt>
<dd>Affiche le graphe et les contrôles associés (zoom, focus).</dd>
<dt>Panneau latéral droit (Fiche)</dt>
<dd>Affiche les fiches (métadonnées et contenu) ainsi qu'une liste des liens sortants (Liens) et entrants (Rétroliens).</dd>
</dl>
<p>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.</p>
<h3 id="graphe" tabindex="-1">Graphe</h3>
<p>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.</p>
<p>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.</p>
<p>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 <code>C</code> pour zoomer sur un nœud sélectionné (dont la fiche est ouverte). Le bouton Recentrer (raccourci : touche <code>R</code>) réinitialise le zoom.</p>
<p>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 (stable ou en calcul). Cliquez sur cette barre (raccourci : touche <code>Espace</code>) pour lancer un cycle de simulation supplémentaire.</p>
<div class="astuce">
<p>Quelques pressions rapides sur la touche <code>Espace</code> permettent de « déplier » progressivement un graphe emmêlé.</p>
</div>
<p>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.</p>
<p>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 Préférences › Graphe.</p>
<div class="astuce">
<p>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.</p>
</div>
<p>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.</p>
<h3 id="fiches" tabindex="-1">Fiches</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Cliquer sur le bouton « Fermer » referme le panneau latéral droit de lecture et désélectionne le nœud correspondant dans le graphe.</p>
<p>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.</p>
<p>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.</p>
<div class="note">
<p>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.</p>
</div>
<h3 id="mode-focus" tabindex="-1">Mode focus</h3>
<p>Le bouton Activer le focus (raccourci : touche <code>F</code>) 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.</p>
<p>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.</p>
<div class="astuce">
<p>Le curseur du niveau de focus est contrôlable via les flèches du clavier. Vous pouvez enchaîner les raccourcis : <code>F</code> pour activer le focus, puis les flèches pour augmenter le niveau de focus.</p>
</div>
<h3 id="moteur-de-recherche" tabindex="-1">Moteur de recherche</h3>
<p>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 (<em>fuzzy search</em>). 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.</p>
<div class="important">
<p>Les suggestions disponibles sont contraintes par les <a href="#filtrer-laffichage-par-types">filtres</a> et le <a href="#mode-focus">mode focus</a> : 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 : <code>Alt</code> + <code>R</code>).</p>
</div>
<h3 id="filtrer-laffichage-par-types" tabindex="-1">Filtrer l'affichage par types</h3>
<p>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 <code>Alt</code> enfoncée permet de masquer et réafficher les fiches des autres types.</p>
<p>Pour qu'un type apparaisse, il doit être déclaré dans Préférences › Types de fiches et être attribué à au moins une fiche.</p>
<h3 id="mots-cles" tabindex="-1">Mots-clés</h3>
<p>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.</p>
<p>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 <code>tags</code> .</p>
<h3 id="index" tabindex="-1">Index</h3>
<p>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.</p>
<h3 id="vues" tabindex="-1">Vues</h3>
<p>Les Vues sont une fonctionnalité spécifique à 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.</p>
<div class="important">
<p>Les Vues ne fonctionnent pas actuellement aussi bien que nous le voudrions, nous travaillons donc sur une amélioration de la fonctionnalité.</p>
</div>
<h2 id="partager-un-cosmoscope" tabindex="-1">Partager un cosmoscope</h2>
<p>Cliquez sur Fichier › Partager (<code>Cmd/Ctrl + E</code>) pour lancer la génération d'un cosmoscope destiné à être partagé.</p>
<p>Deux options sont disponibles :</p>
<dl>
<dt>Traiter les citations</dt>
<dd>Traiter les clés de citation et ajouté la bibliographie aux fiches.</dd>
<dt>CSS personnalisé</dt>
<dd>Appliquer les même modifications d'interface (via CSS) de l'application au cosmoscope exporté.</dd>
</dl>
<div class="note">
<p>Si les options sont grisées, c'est que les paramètres correspondants dans Préférences ne sont pas renseignés.</p>
</div>
<p>Les cosmoscopes exportés via le menu Partager intègrent les métadonnées (titre, auteur, description, mots-clés) éventuellement renseignées dans la configuration du projet. Elles sont affichées dans le panneau « À propos ». Elles sont également incluses dans le code source du cosmoscope sous la forme de balises <code>meta</code>, afin d'améliorer la description d'un cosmoscope destiné à être publié sur le Web.</p>
<p>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.</p>
<p>Le fichier <code>cosmoscope.html</code> exporté peut être partagé comme n'importe quel fichier informatique : email, transfert de fichiers, messagerie, mise en ligne sur un serveur…</p>
<p>Si vous publiez un cosmoscope sur le Web, notez qu'il est possible de créer un lien directement vers une fiche en ajoutant son identifiant précédé d'un croisillon <code>#</code> en fin d'URL. Exemple :</p>
<p><code>https://domaine.fr/cosmoscope.html#20210427185546</code></p>
<h2 id="configuration" tabindex="-1">Configuration</h2>
<p>Cliquez sur Configuration (<code>Ctrl + o</code> ou <code>Cmd + ,</code>) pour configurer le projet actuellement ouvert.</p>
<div class="important">
<p>La majorité des options de configuration ne fonctionnent que si une source de données est renseignée au préalable.</p>
</div>
<h3 id="general" tabindex="-1">Général</h3>
<dl>
<dt>Source des données</dt>
<dd>
<!-- METTRE À JOUR --> Chemin du répertoire contenant les fichiers Markdown. Les nouvelles fiches créées via Cosma sont ajoutées dans ce répertoire.
</dd>
<dt>Enregistrer automatiquement les cosmoscopes dans l’historique</dt>
<dd>Par défaut, Cosma exporte automatiquement chaque cosmoscope dans un répertoire <code>cosma-history</code> situé dans les répertoires temporaires du système d'exploitation. Décochez cette option pour désactiver cet export automatique.</dd>
<dd>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.</dd>
<dt>Symbole de lien</dt>
<dd>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 : ☞).</dd>
</dl>
<h3 id="types-de-fiches" tabindex="-1">Types de fiches</h3>
<p>Cette section permet de définir différents types de fiches. Pour chaque type de fiche, renseignez un nom et une couleur.</p>
<p>Une fiche peut avoir un ou plusieurs types. Si le champ <code>type</code> n'est pas spécifié, ou bien que sa valeur ne correspond aux types enregistrés dans la configuration, Cosma interprètera le type de la fiche comme non défini (<code>undefined</code>).</p>
<div class="important">
<p>Le type « undefined » peut être modifié (par exemple pour en changer la couleur) mais il ne peut pas être supprimé.</p>
</div>
<h3 id="types-de-liens" tabindex="-1">Types de liens</h3>
<p>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 :</p>
<ul>
<li>continu (<em>simple</em>)</li>
<li>double (<em>double</em>)</li>
<li>tirets (<em>dash</em>)</li>
<li>pointillés (<em>dotted</em>)</li>
</ul>
<p>Pour qualifier un lien dans une fiche, préfixez l'identifiant par le nom d'un type de lien suivi d'un deux-points.</p>
<div class="important">
<p>Le type « undefined » peut être modifié (par exemple pour en changer la couleur) mais il ne peut pas être supprimé.</p>
</div>
<div class="astuce">
<p>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 (<code>undefined</code>) en pointillés (<code>dotted</code>) gris (<code>grey</code>) et un type de lien spécial en trait continu (<code>simple</code>) noir (<code>black</code>), les liens spéciaux seront plus visibles dans le graphe.</p>
</div>
<h3 id="graphe-1" tabindex="-1">Graphe</h3>
<p>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.</p>
<dl>
<dt>Couleur de fond</dt>
<dd>La couleur de fond du graphe.</dd>
<dt>Couleur de surbrillance</dt>
<dd>La couleur qui s'applique aux nœuds ainsi qu'aux liens lors du survol et de la sélection.</dd>
</dl>
<div class="note">
<p>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 via une feuille de style CSS personnalisée (voir Configuration › Avancé).</p>
</div>
<dl>
<dt>Taille du texte des étiquettes</dt>
<dd>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.</dd>
<dt>Niveau maximum de focus</dt>
<dd>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.</dd>
<dt>Afficher des flèches sur les liens</dt>
<dd>Permet d'obtenir un graphe orienté ou non orienté.</dd>
</dl>
<h4 id="spatialisation" tabindex="-1">Spatialisation</h4>
<dl>
<dt>Force d'attraction</dt>
<dd>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.</dd>
<dt>Distance maximum entre les nœuds</dt>
<dd>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.</dd>
<dt>Attraction verticale/horizontale</dt>
<dd>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.</dd>
</dl>
<h3 id="metadonnees-1" tabindex="-1">Métadonnées</h3>
<p>Vous pouvez définir des métadonnées globales pour le cosmoscope :</p>
<ul>
<li>titre</li>
<li>auteur</li>
<li>mots-clés</li>
<li>description</li>
</ul>
<p>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 <code>meta</code>.</p>
<h3 id="bibliographie" tabindex="-1">Bibliographie</h3>
<p>Indiquez ici les chemins des fichiers de données, style et localisation bibliographique. Les trois fichiers sont requis pour le traitement des citations.</p>
<dl>
<dt>Données bibliographiques</dt>
<dd>Fichier contenant les métadonnées décrivant des références bibliographiques. Le format requis est CSL JSON (extension <code>.json</code>).</dd>
<dt>Style bibliographique</dt>
<dd>Fichier contenant les règles de mise en forme des citations et bibliographies. Le format requis est CSL (extension <code>.csl</code>). Vous pouvez télécharger des fichiers de style depuis le <a href="https://www.zotero.org/styles">répertoire de styles CSL de Zotero</a>.</dd>
<dt>Localisation bibliographique</dt>
<dd>Fichier contenant les traductions dans une certaine langue des termes employés en bibliographie (ex : éditeur, numéro…). Le format requis est XML (extension <code>.xml</code>). Vous pouvez télécharger des fichiers de localisation depuis le <a href="https://github.com/citation-style-language/locales/tree/6b0cb4689127a69852f48608b6d1a879900f418b">dépôt GitHub du projet CSL</a>.</dd>
</dl>
<h3 id="vues-1" tabindex="-1">Vues</h3>
<p>Gérez ici les <a href="#vues">vues</a> enregistrées dans le cosmoscope.</p>
<h3 id="avance" tabindex="-1">Avancé</h3>
<dl>
<dt>Afficher les outils de développement</dt>
<dd>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.</dd>
<dt>CSS personnalisée</dt>
<dd>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.</dd>
</dl>
<div class="astuce">
<p>Pour connaître les sélecteurs à utiliser pour telle ou telle déclaration, vous pouvez :</p>
<ul>
<li>cliquer sur Affichage › Outils de développement (nécessite d'avoir activé Afficher les outils de développement) ;</li>
<li>ouvrir le cosmoscope dans un navigateur web et utiliser les outils de développement du navigateur ;</li>
<li>consulter le code source de Cosma, spécifiquement <code>/cosma-core/template.njk</code> (pour connaître la structure HTML du cosmoscope), <code>/cosma-core/styles.css</code> et <code>/cosma-core/print.css</code> (pour les styles d'impression activés lors de l'impression d'une fiche).</li>
</ul>
<p>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 <code>custom.css</code> contient des déclarations qui modifient les polices utilisées dans le cosmoscope :</p>
<pre><code class="language-css">:root {
--sans: "IBM Plex Sans", sans-serif;
--serif: "IBM Plex Serif", serif;
--mono: "IBM Plex Mono", monospace;
--condensed: 'Avenir Next Condensed', sans-serif;
}
</code></pre>
</div>
<h2 id="credits" tabindex="-1">Crédits</h2>
<h3 id="equipe" tabindex="-1">Équipe</h3>
<ul>
<li><a href="https://www.arthurperret.fr/">Arthur Perret</a> (porteur du projet)</li>
<li><a href="https://myllaume.fr/">Guillaume Brioudes</a> (développeur)</li>
<li><a href="https://mica.u-bordeaux-montaigne.fr/borel-clement/">Clément Borel</a> (chercheur)</li>
<li><a href="http://www.guidedesegares.info/">Olivier Le Deuff</a> (chercheur)</li>
</ul>
<p>Ont également contribué au développement de Cosma :</p>
<ul>
<li><a href="https://mica.u-bordeaux-montaigne.fr/pucheu-david/">David Pucheu</a> (chercheur)</li>
</ul>
<h3 id="bibliotheques-utilisees" tabindex="-1">Bibliothèques utilisées</h3>
<p>Pour améliorer la maintenabilité et la lisibilité du code source, l’équipe de développement a recouru aux bibliothèques suivantes :</p>
<ul>
<li><a href="https://d3js.org/">D3.js</a> v4.13.0 (BSD 3-Clause) : Génération du graphe</li>
<li><a href="https://mozilla.github.io/nunjucks/">Nunjucks</a> v3.2.3 (BSD 2-Clause) : Génération du template du cosmoscope</li>
<li><a href="https://github.com/nodeca/js-yaml">Js-yaml</a> v4.1.0 (MIT License) : Lecture du fichier de configuration et écriture de l'en-tête YAML</li>
<li><a href="https://github.com/dworthen/js-yaml-front-matter">Js-yaml-front-matter</a> v4.1.1 (MIT License) : Lecture de l'en-tête YAML des fichiers Markdown</li>
<li><a href="https://github.com/markdown-it/markdown-it">Markdown-it</a> v12.3.0 (MIT License) : Conversion Markdown → HTML</li>
<li><a href="https://www.npmjs.com/package/markdown-it-attrs">Markdown-it-attrs</a> v4.0.0 (MIT License) : Traitement des hyperliens Markdown au sein des fiches</li>
<li><a href="https://github.com/Juris-M/citeproc-js">Citeproc-js</a> v2.4.62 (CPAL et AGPL) : Conversion des clés de citation</li>
<li><a href="https://fusejs.io/">Fuse.js</a> v6.4.6 (Apache License 2.0) : Moteur de recherche</li>
</ul>
<h2 id="changelog" tabindex="-1">Changelog</h2>
<h3 id="v20" tabindex="-1">v2.0</h3>
<!-- À COMPLÉTER -->
<h3 id="v12" tabindex="-1">v1.2</h3>
<p>Cette mise à jour ajoute quelques fonctionnalités de lecture et d'écriture des fiches :</p>
<ul>
<li>Le répertoire de fiches est désormais lu de manière récursive. Ceci permet de prendre en compte toutes les fiches, quel que soit leur emplacement dans une éventuelle structure de sous-répertoires.</li>
<li>Les éléments HTML insérés dans le corps des fiches sont désormais reconnus et interprétés.</li>
</ul>
<p>Des bugs ont également été résolus :</p>
<ul>
<li>Les infobulles de contexte ne sont plus vides lorsque le lien est qualifié (ticket #15).</li>
<li>Le fonctionnement des vues enregistrées est rétabli (ticket #16).</li>
<li>Le réglage de l'attraction verticale et horizontale n'est plus inversé (ticket #18).</li>
</ul>
<h3 id="v11" tabindex="-1">v1.1</h3>
<p>Cette mise à jour ajoute la possibilité de changer de langue (anglais ou français), résout des bugs et améliore l'interface, notamment au niveau de la configuration.</p>
<ul>
<li>L'application est traduite en anglais, il est possible de changer de langue dans Préférences.</li>
<li>Créer une fiche sans spécifier de répertoire ne cause plus d'erreur mais renvoie un message informatif (ticket #6).</li>
<li>Créer une fiche avec un titre déjà utilisé n'écrase plus silencieusement la fiche existante mais demande une confirmation (ticket #5).</li>
<li>Il est possible d'utiliser <code>keywords</code> au lieu de <code>tags</code> dans l'en-tête YAML des fiches (ticket #3).</li>
<li>Il n'est plus nécessaire de déclarer un type de fiche dans la configuration avant de pouvoir l'assigner à une nouvelle fiche.</li>
<li>La fenêtre Préférences a été réorganisée en sections.</li>
<li>La lisibilité des rapports d'erreur a été améliorée.</li>
<li>L'option <code>minify</code> permettant de réduire la taille des exports, non fonctionnelle en v1.0, a été supprimée.</li>
<li>L'application est distribuée avec sa documentation, accessible via Aide › Manuel ou bien en cliquant sur le bouton Aide en bas à gauche dans le cosmoscope.</li>
<li>Le code source a été réorganisé pour permettre le développement simultané d'une version exécutable en ligne de commande (<a href="https://github.com/graphlab-fr/cosma-cli">cosma-cli</a>) à partir de la même base de code (<a href="https://github.com/graphlab-fr/cosma-core">cosma-core</a>).</li>
<li>Mise à jour de Electron v13 vers v15.</li>
</ul>
</main>
<footer>
<p>
Cosma est un logiciel libre, diffusé sous licence <a href="https://opensource.org/licenses/GPL-3.0">GPL-3.0-or-later</a>.<br/>
Cette documentation a été fabriquée avec <a href="https://www.11ty.dev/">11ty</a>.
</p>
</footer>
<script>
(function() {
document.querySelectorAll('#toc > nav > ul > li').forEach( function(li) {
if (li.children.length > 1) {
var toggle = document.createElement('span');
toggle.className = 'toggle';
toggle.innerHTML = '▸';
toggle.onclick = function() {
var sublist = li.getElementsByTagName('ul')[0];
if (sublist) {
if (sublist.style.display === 'none') {
sublist.style.display = 'block'
toggle.innerHTML = '▾';
} else {
sublist.style.display = 'none';
toggle.innerHTML = '▸';
}
}
};
li.appendChild(toggle);
toggle.click();
}
});
})();
</script>
</body>
</html>