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
/
Copy pathuser-manual-cli.html
1333 lines (1280 loc) · 63.7 KB
/
user-manual-cli.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
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en">
<head>
<meta charset=utf-8 />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="generator" content="Eleventy v1.0.2">
<title>User Manual (CLI) | Cosma</title>
<meta name="description" content="User manual for Cosma CLI." />
<meta name="author" content="Arthur Perret,Guillaume Brioudes" />
<meta name="copyright" content="GPL-3.0-or-later"/>
<meta name="last_edit" content="2023-04-27" />
<meta property="og:type" content="website" />
<meta property="og:title" content="User Manual (CLI)" />
<meta property="og:description" content="User manual for Cosma CLI." />
<meta property="og:site_name" content="cosma-docs" />
<meta itemprop="name" content="cosma-docs" />
<meta itemprop="description" content="User manual for Cosma CLI." />
<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="User Manual (CLI)" />
<meta property="DC.contributor" content="Arthur Perret,Guillaume Brioudes" />
<meta property="DC.date" content="2023-04-27" />
<meta property="DC.language" content="en" />
<meta property="DC.description" lang="en" content="User manual for Cosma CLI." />
<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="User Manual (CLI)" />
<meta name="twitter:description" content="User manual for Cosma CLI." />
<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;
font-size: 1.2em;
}
h2 {
border-bottom: 2px solid black;
}
h3 {
border-bottom: 1px solid #111;
}
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 — User Manual (CLI)</h1>
</article>
</header>
<aside id="toc">
<nav class="toc" >
<ul><li><a href="#installing-and-updating">Installing and updating</a><ul><li><a href="#installing">Installing</a></li><li><a href="#upgrading">Upgrading</a></li></ul></li><li><a href="#description">Description</a></li><li><a href="#the-cosma-command">The cosma command</a><ul><li><a href="#create-the-user-data-directory">Create the user data directory</a></li><li><a href="#show-projects">Show projects</a></li><li><a href="#show-version-number">Show version number</a></li><li><a href="#show-help">Show help</a></li></ul></li><li><a href="#configuration">Configuration</a><ul><li><a href="#create-a-configuration-file">Create a configuration file</a></li><li><a href="#create-a-global-configuration-file-(project)">Create a global configuration file (project)</a></li><li><a href="#create-a-default-configuration-file">Create a default configuration file</a></li><li><a href="#configuration-parameters">Configuration parameters</a></li><li><a href="#configuration-template">Configuration template</a></li></ul></li><li><a href="#creating-content-text-files-(markdown)">Creating content: text files (Markdown)</a><ul><li><a href="#metadata">Metadata</a></li><li><a href="#content">Content</a></li><li><a href="#links">Links</a></li><li><a href="#unique-identifiers">Unique identifiers</a></li><li><a href="#creating-records-with-cosma">Creating records with Cosma</a></li><li><a href="#record-create-a-record-(form-mode)">record : create a record (“form” mode)</a></li><li><a href="#autorecord-create-a-record-(one-liner-mode)">autorecord : create a record (“one-liner” mode)</a></li><li><a href="#batch-create-a-batch-of-records">batch : create a batch of records</a></li></ul></li><li><a href="#creating-content-tabular-data-(csv)">Creating content: tabular data (CSV)</a><ul><li><a href="#metadata-for-nodes">Metadata for nodes</a></li><li><a href="#metadata-for-links">Metadata for links</a></li></ul></li><li><a href="#modelize-creating-a-cosmoscope">modelize: creating a cosmoscope</a><ul><li><a href="#generating-a-sample-cosmoscope">Generating a sample cosmoscope</a></li><li><a href="#processing-citations">Processing citations</a></li><li><a href="#citation-syntax">Citation syntax</a></li><li><a href="#applying-custom-css">Applying custom CSS</a></li><li><a href="#using-a-global-configuration-file">Using a global configuration file</a></li><li><a href="#excluding-records-from-the-cosmoscope">Excluding records from the cosmoscope</a></li><li><a href="#history">History</a></li><li><a href="#errors-and-warnings">Errors and warnings</a></li></ul></li><li><a href="#using-the-cosmoscope">Using the cosmoscope</a><ul><li><a href="#layout">Layout</a></li><li><a href="#graph">Graph</a></li><li><a href="#records">Records</a></li><li><a href="#focus-mode">Focus mode</a></li><li><a href="#search-bar">Search bar</a></li><li><a href="#filtering-by-record-type">Filtering by record type</a></li><li><a href="#filtering-by-keywords">Filtering by keywords</a></li><li><a href="#index">Index</a></li><li><a href="#views">Views</a></li></ul></li><li><a href="#sharing-and-publishing-a-cosmoscope">Sharing and publishing a cosmoscope</a></li><li><a href="#credits">Credits</a><ul><li><a href="#team">Team</a></li><li><a href="#dependencies">Dependencies</a></li></ul></li><li><a href="#changelog">Changelog</a><ul><li><a href="#v200">v2.0.0</a></li></ul></li></ul>
</nav>
</aside>
<main>
<p><strong>Version:</strong> CLI v2.0.0</p>
<p>Last updated: April 27, 2023</p>
<h2 id="installing-and-updating" tabindex="-1">Installing and updating</h2>
<h3 id="installing" tabindex="-1">Installing</h3>
<p>Cosma is available in two versions: a graphical user interface (GUI) application and a command line interface (CLI) application. Information about the CLI version is detailed <a href="https://cosma.graphlab.fr/en/docs/cli/user-manual/">on a dedicated page</a>.</p>
<p>From v2 onwards, both versions of Cosma are available for macOS, Windows and Linux.</p>
<p>For Cosma CLI, the installation of <a href="https://nodejs.org/">NodeJS</a> version 12 or higher is required.</p>
<p>NPM (the NodeJS package manager) is installed automatically with NodeJS. NPM can be used to manage the installation of Cosma CLI. Enter the command below in your terminal to install Cosma CLI globally. The software can then be used by running <code>cosma</code>.</p>
<pre><code>npm install @graphlab-fr/cosma -g
</code></pre>
<p>If you want to install Cosma CLI as a dependency of a NodeJS project, use the command below. The software can then be used by running <code>./node_modules/.bin/cosma</code> from the root of the project.</p>
<pre><code>npm install @graphlab-fr/cosma
</code></pre>
<h3 id="upgrading" tabindex="-1">Upgrading</h3>
<p>The following command displays the list of packages installed via NPM for which an update exists:</p>
<pre><code>npm outdated
</code></pre>
<p>The following command updates Cosma CLI if an update exists:</p>
<pre><code>npm update cosma
</code></pre>
<h2 id="description" tabindex="-1">Description</h2>
<p>Cosma CLI is the command-line interface (CLI) version of Cosma, a visualization tool that can represent document graphs as interactive networks in a web interface.</p>
<p>Cosma CLI works with configuration files written in YAML. Each configuration file specifies a data source to be used, as well as various parameters that govern the behavior of Cosma for this data source.</p>
<p>Two approaches can be taken regarding configuration files:</p>
<p>The first approach is to run <code>cosma</code> in a directory where a configuration file is located. This is called a local configuration file. Local configuration files must always be named <code>config.yml</code>.</p>
<p>The other approach is to run <code>cosma</code> with the <code>--project <name></code> option, where <code><name></code> is the name of a configuration file found in a special folder, the user data directory. This is called a global configuration file, or <strong>project</strong>. This file can be named freely (e.g. <code>foo.yml</code>). With this second approach, the <code>cosma</code> command can be run from any location.</p>
<div class="tip">
<p>The local approach is useful for automation and reproducibility in a context of shared or distributed work on several machines. It allows the simultaneous transmission of data, configuration and operating instructions (commands), bundled and useable as is, without any additional parameterization required from the recipient (human or machine).</p>
<p>Conversely, the global approach is useful for prolonged use of the software by an individual on a single machine.</p>
</div>
<h2 id="the-cosma-command" tabindex="-1">The <code>cosma</code> command</h2>
<p>The <code>cosma</code> command can be used in three ways:</p>
<ol>
<li><code>cosma</code> displays general help ;</li>
<li><code>cosma <option></code> executes a general option;</li>
<li><code>cosma <command> <options></code> executes one of Cosma's five commands (<code>config</code>, <code>record</code>, <code>autorecord</code>, <code>batch</code> and <code>modelize</code>), with one or more specific options.</li>
</ol>
<p>The five commands exist in long and short versions (e.g. <code>cosma config</code> or <code>cosma c</code>). Some options also have a short version (e.g. <code>cosma config --global</code> or <code>cosma config -g</code>). In both cases, the long and short versions are functionally identical; the short version is simply used to save time when used repeatedly over short periods of time.</p>
<p>The following subsections present the general options.</p>
<h3 id="create-the-user-data-directory" tabindex="-1">Create the user data directory</h3>
<pre><code>cosma --create-user-data-dir
</code></pre>
<p>This command creates a user data directory named <code>cosma-cli</code> at a location that complies with the <a href="https://xdgbasedirectoryspecification.com">XDG Base Directory specification</a>. The exact location depends on each operating system and may vary from version to version of the same system.</p>
<p>If the user data directory already exists, the command simply displays its location.</p>
<h3 id="show-projects" tabindex="-1">Show projects</h3>
<pre><code>cosma --list-projects
</code></pre>
<p>This command lists the configuration files in the user data directory (projects).</p>
<h3 id="show-version-number" tabindex="-1">Show version number</h3>
<pre><code>cosma --version
cosma -V
</code></pre>
<p><strong>NB:</strong> this is the only option for which the short form uses a capital letter. This is a default setting from the library we use to define commands.</p>
<h3 id="show-help" tabindex="-1">Show help</h3>
<p>Cosma has a general help:</p>
<pre><code>cosma --help
cosma -h
</code></pre>
<p>Context-sensitive help is also available for the five Cosma commands. Add the <code>-h/--help</code> flag to any of these commands to display the contextual help.</p>
<p>Example:</p>
<pre><code>cosma config --help
</code></pre>
<h2 id="configuration" tabindex="-1">Configuration</h2>
<h3 id="create-a-configuration-file" tabindex="-1">Create a configuration file</h3>
<pre><code>cosma config
cosma c
</code></pre>
<p>This command creates a <code>config.yml</code> file in the current directory.</p>
<h3 id="create-a-global-configuration-file-(project)" tabindex="-1">Create a global configuration file (project)</h3>
<pre><code>cosma config --global <name>
cosma c -g <name>
</code></pre>
<p>The <code>-g/--global</code> option followed by a name creates a <code>name.yml</code> file in the user data directory.</p>
<h3 id="create-a-default-configuration-file" tabindex="-1">Create a default configuration file</h3>
<pre><code>cosma config --global
cosma c -g
</code></pre>
<p>When not followed by a name, the <code>-g/--global</code> option creates a <code>defaults.yml</code> file in the user data directory. This file can then be modified to set the default values for the various Cosma configuration parameters. These default values will be applied to configuration files created afterwards.</p>
<h3 id="configuration-parameters" tabindex="-1">Configuration parameters</h3>
<p>Below is a list of the parameters used by Cosma. If a parameter is missing from a configuration file, Cosma considers it to have its default value.</p>
<div class="important">
<p>The “undefined” record and link types are required for the program to work. If you delete them from a configuration file, Cosma will automatically reinsert them the next time you use the file.</p>
</div>
<table>
<thead>
<tr>
<th>name</th>
<th>description</th>
<th>possible values</th>
<th>default value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>select_origin</code></td>
<td>Data source type</td>
<td><code>directory</code> (directory of text files), <code>csv</code> (tabular data, local files) or <code>online</code> (tabular data, online files)</td>
<td><code>directory</code></td>
</tr>
<tr>
<td><code>files_origin</code></td>
<td>Location of files for data source type <code>directory</code></td>
<td>path (directory)</td>
<td></td>
</tr>
<tr>
<td><code>nodes_origin</code></td>
<td>Location of nodes for data source type <code>csv</code></td>
<td>path (CSV file)</td>
<td></td>
</tr>
<tr>
<td><code>links_origin</code></td>
<td>Location of links for data source type <code>csv</code></td>
<td>path (CSV file)</td>
<td></td>
</tr>
<tr>
<td><code>nodes_online</code></td>
<td>Location of nodes for data source type <code>online</code></td>
<td>URL (CSV file)</td>
<td></td>
</tr>
<tr>
<td><code>links_online</code></td>
<td>Location of links for data source type <code>online</code></td>
<td>URL (CSV file)</td>
<td></td>
</tr>
<tr>
<td><code>images_origin</code></td>
<td>Location of images used in the cosmoscope</td>
<td>path (directory)</td>
<td></td>
</tr>
<tr>
<td><code>export_target</code></td>
<td>Location to be used for exports</td>
<td>path (directory)</td>
<td></td>
</tr>
<tr>
<td><code>history</code></td>
<td>Copy each cosmoscope generated via Cosma to a <code>history</code> folder</td>
<td><code>true</code> or <code>false</code></td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>focus_max</code></td>
<td>Maximum distance to selected node in focus mode</td>
<td>integer</td>
<td>2</td>
</tr>
<tr>
<td><code>record_types</code></td>
<td>List of entity types</td>
<td>list</td>
<td></td>
</tr>
<tr>
<td>entity type</td>
<td></td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>fill</code></td>
<td>Node type fill color</td>
<td>HTML color</td>
<td></td>
</tr>
<tr>
<td><code>stroke</code></td>
<td>Node type outline color (used when the node is filled with an image)</td>
<td>HTML color</td>
<td></td>
</tr>
<tr>
<td><code>link_types</code></td>
<td>List of link types</td>
<td>list</td>
<td></td>
</tr>
<tr>
<td>link type</td>
<td></td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>stroke</code></td>
<td>Link type stroke style</td>
<td><code>single</code> (solid line), <code>dash</code> (dashed line), <code>dash</code> (dotted line), <code>double</code> (two parallel lines)</td>
<td></td>
</tr>
<tr>
<td><code>color</code></td>
<td>Link type color</td>
<td>HTML color</td>
<td></td>
</tr>
<tr>
<td><code>record_filters</code></td>
<td>List of metadata filters</td>
<td></td>
<td></td>
</tr>
<tr>
<td>metadata filter</td>
<td>Entities for which this metadata is present will be excluded when creating a cosmoscope</td>
<td>type, keyword, metadata declared in <code>record_metas</code></td>
<td></td>
</tr>
<tr>
<td><code>graph_background_color</code></td>
<td>Color used in the background of the graph</td>
<td>HTML color</td>
<td></td>
</tr>
<tr>
<td><code>graph_highlight_color</code></td>
<td>Color used when hovering and selecting nodes</td>
<td>HTML color</td>
<td></td>
</tr>
<tr>
<td><code>graph_highlight_on_hover</code></td>
<td>Apply highlighting when hovering and selecting nodes</td>
<td><code>true</code> or <code>false</code></td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>graph_text_size</code></td>
<td>Node label size</td>
<td>Integer betwen 2-15</td>
<td>10</td>
</tr>
<tr>
<td><code>graph_arrows</code></td>
<td>Show directional arrows on links</td>
<td><code>true</code> or <code>false</code></td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>node_size_method</code></td>
<td>Node sizing method</td>
<td><code>degree</code> (size proportional to degree) or <code>unique</code> (fixed size)</td>
<td><code>degree</code></td>
</tr>
<tr>
<td><code>node_size</code></td>
<td>Node size (when using fixed size)</td>
<td>Integer between 2 and 20</td>
<td>10</td>
</tr>
<tr>
<td><code>node_size_max</code></td>
<td>Maximum node size (when using proportional size)</td>
<td>Integer from 2 to 20</td>
<td>20</td>
</tr>
<tr>
<td><code>node_size_min</code></td>
<td>Minimum node size (when using proportional size)</td>
<td>Integer between 2 and 20</td>
<td>2</td>
</tr>
<tr>
<td><code>attraction_force</code></td>
<td>Force of attraction</td>
<td>Number between 50 and 600</td>
<td>200</td>
</tr>
<tr>
<td><code>attraction_distance_max</code></td>
<td>Maximum distance between nodes</td>
<td>Number between 200 and 800</td>
<td>250</td>
</tr>
<tr>
<td><code>attraction_vertical</code></td>
<td>Additional attraction towards the vertical axis</td>
<td>Number between 0 (disabled) and 1</td>
<td>0</td>
</tr>
<tr>
<td><code>attraction_horizontal</code></td>
<td>Additional attraction towards the horizontal axis</td>
<td>Number between 0 (disabled) and 1</td>
<td>0</td>
</tr>
<tr>
<td><code>views</code></td>
<td>List of registered views (which can only be created with the GUI version)</td>
<td>list</td>
<td></td>
</tr>
<tr>
<td><code>chronological_record_meta</code></td>
<td>Metadata to be used for chronological mode</td>
<td><code>created</code>, <code>last_edit</code>, <code>last_open</code>, <code>timestamp</code>, metadata declared in <code>record_metas</code></td>
<td><code>created</code></td>
</tr>
<tr>
<td><code>record_metas</code></td>
<td>List of metadata (present in the data source) to be included in the cosmoscope</td>
<td>list</td>
<td></td>
</tr>
<tr>
<td><code>title</code></td>
<td>Cosmoscope title</td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>author</code></td>
<td>Cosmoscope author</td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>description</code></td>
<td>Cosmoscope description</td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>keywords</code></td>
<td>Cosmoscope keywords</td>
<td>list</td>
<td></td>
</tr>
<tr>
<td>keyword</td>
<td></td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>link_symbol</code></td>
<td>String to be displayed in place of identifiers as link text for rendered internal links in cosmoscope</td>
<td>string</td>
<td></td>
</tr>
<tr>
<td><code>csl</code></td>
<td>Bibliographic style</td>
<td>path (XML file)</td>
<td></td>
</tr>
<tr>
<td><code>bibliography</code></td>
<td>Bibliographic data</td>
<td>path (JSON file)</td>
<td></td>
</tr>
<tr>
<td><code>csl_locale</code></td>
<td>Bibliographic location</td>
<td>path (XML file)</td>
<td></td>
</tr>
<tr>
<td><code>css_custom</code></td>
<td>CSS file for cosmoscope customization</td>
<td>path (CSS file)</td>
<td></td>
</tr>
<tr>
<td><code>devtools</code></td>
<td>Show development tools (only in GUI)</td>
<td><code>true</code> or <code>false</code></td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>lang</code></td>
<td>Cosmoscope language</td>
<td><code>en</code> (English) or <code>fr</code> (French)</td>
<td><code>en</code></td>
</tr>
</tbody>
</table>
<div class="tip">
<p>The background and highlight colors can be changed directly via the configuration file, but all colors and all interface elements can be changed using a custom CSS style sheet.</p>
<p>Applying a vertical/horizontal force tightens the graph. A value of 0.1 is enough to bring back isolated nodes closer to the center.</p>
</div>
<h3 id="configuration-template" tabindex="-1">Configuration template</h3>
<p>Here is the template used by Cosma to generate a configuration file:</p>
<pre><code>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
</code></pre>
<h2 id="creating-content-text-files-(markdown)" tabindex="-1">Creating content: text files (Markdown)</h2>
<p>When the data source is set on <code>directory</code> (Markdown file directory), the data must comply with the following rules:</p>
<ul>
<li>content is written in Markdown, file extension is <code>.md</code>;</li>
<li>metadata is expressed in YAML, in a header at the beginning of the file;</li>
<li>internal links are expressed with a wiki-like syntax (double brackets <code>[[ ]]</code>) and based on unique identifiers.</li>
</ul>
<p>The following subsections explain these rules in detail.</p>
<div class="note">
<p>This combination of writing standards combines several textual cultures: documentation (enriching and indexing content with metadata); wikis (interrelating documents); index cards, Zettelkasten (organising one's notes); academic writing with Pandoc (using plain text as a source for exporting in various formats).</p>
<p>Therefore, Cosma works particularly well when used in tandem with writing environments that also adopt this approach, such as <a href="https://zettlr.com">Zettlr</a> or the <a href="https://foambubble.github.io/foam/">Foam</a> extension for Visual Studio Code and VSCodium.</p>
</div>
<h3 id="metadata" tabindex="-1">Metadata</h3>
<p>In order to be correctly interpreted by Cosma, Markdown files (<code>.md</code>) must include a <a href="http://yaml.org">YAML</a> header at the beginning of the file. This header is created automatically when you create a file via Cosma.</p>
<p>Example:</p>
<pre><code>---
title: Title of the record
id: 20201209111625
types:
- undefined
tags:
- mot-clé 1
- mot-clé 2
---
</code></pre>
<p>The YAML header is delimited by two sets of three single dashes on a line (<code>---</code>). In YAML, a field consists of a name and a value separated by a colon.</p>
<p>In accordance with the YAML specification, the list of keywords can be written in <em>block</em> mode:</p>
<pre><code class="language-yaml">tags:
- keyword 1
- keyword 2
</code></pre>
<p>Or in <em>flow</em> mode:</p>
<pre><code class="language-yaml">tags: [keyword 1, keyword 2]
</code></pre>
<div class="note">
<p><strong>Why a YAML header?</strong></p>
<p>Some applications opt to recognize file metadata heuristically. For example, if the first line of the file is a level 1 heading, then it will be interpreted as the title of the file; if the second line contains words prefixed with a <code>#</code> pound sign, then they will be interpreted as keywords.</p>
<p>This method is not interoperable: each program has its own conventions, which limits the user's ability to change tools.</p>
<p>Using a YAML header allows writers to declare different metadata explicitly and separately. This has the advantage of making the detection and manipulation of this metadata trivial, both by machines and humans. The use of a common format (such as YAML) increases the number of tools that can be used seamlessly with the same set of files. And widely used computer tools such as regular expressions and shell scripts allow people to convert their data themselves in a relatively simple way if needed.</p>
</div>
<h4 id="predefined-metadata" tabindex="-1">Predefined metadata</h4>
<p>Cosma recognises and uses the following four fields:</p>
<dl>
<dt><code>title</code></dt>
<dd>Mandatory.</dd>
<dd>Title of the record.</dd>
<dt><code>id</code></dt>
<dd>Mandatory.</dd>
<dd>Unique identifier of the record. Must be a unique number. By default, Cosma generates 14-digit identifiers in the form of a timestamp (year, month, day, hours, minutes and seconds). This is inspired by Zettelkasten note-taking applications such as <a href="https://zettelkasten.de/the-archive/">The Archive</a> and <a href="https://www.zettlr.com">Zettlr</a>.</dd>
<dt><code>type</code> or <code>types</code></dt>
<dd>Optional.</dd>
<dd>Record types. A record can have more than one type. If the <code>type</code> field is not specified or its value does not match one of the types declared in the configuration, Cosma will interpret the type of the record as <code>undefined</code>.</dd>
<dt><code>tags</code></dt>
<dd>Optional.</dd>
<dd>Keywords assigned to the record. The value must be a list. A record can have as many keywords as you wish. You can use <code>keywords</code> instead of <code>tags</code>, for compatibility with Pandoc. If a record has a <code>tags</code> field and a <code>keywords</code> field, only the keywords declared in the <code>tags</code> field are interpreted by Cosma.</dd>
<dt><code>thumbnail</code></dt>
<dd>Optional.</dd>
<dd>File name of an image to be used as thumbnail for this record in the cosmoscope (inside the corresponding node and at the top of the record pane).</dd>
<dt><code>begin</code></dt>
<dd>Optional.</dd>
<dd>Time metadata used for chronological mode.</dd>
<dt><code>end</code></dt>
<dd>Optional.</dd>
<dd>Time metadata used for chronological mode.</dd>
</dl>
<h4 id="user-defined-metadata" tabindex="-1">User-defined metadata</h4>
<p>Other metadata can be added freely in the YAML header. By default, Cosma ignores this metadata when creating a cosmoscope: it is not included in the HTML rendering of the records. In order for this metadata to be taken into account, it must be declared in the <code>record_metas</code> field of the configuration file.</p>
<p>Example:</p>
<pre><code>record_metas: [author, date, lang]
</code></pre>
<h3 id="content" tabindex="-1">Content</h3>
<p>Cosma interprets files as being written in <a href="https://spec.commonmark.org/0.30/">CommonMark</a>, a strictly defined version of Markdown, a popular lightweight markup language.</p>
<div class="tip">
<p>The <a href="https://commonmark.org/help/">CommonMark tutorial</a> teaches you the basics of Markdown in 10 minutes.</p>
<p>If you want to learn how to use Markdown and Pandoc together, check out this online lesson: <a href="https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown">Sustainable Authorship in Plain Text using Pandoc and Markdown</a>.</p>
</div>
<p>Cosma renders Markdown files into HTML. Therefore, Markdown files can also include HTML code. Cosma also supports <a href="https://www.npmjs.com/package/markdown-it-attrs">adding attributes by brackets</a>, as shown below.</p>
<pre><code class="language-markdown"><div class="red">This paragraph will be red</div>
This paragraph will be red{.red}
</code></pre>
<p>Bitmap images can also be rendered using the Markdown syntax. Example:</p>
<pre><code class="language-markdown">
</code></pre>
<p>To reduce the size of the cosmoscope, use images hosted on the web and included via a URL. Example:</p>
<pre><code class="language-markdown">
</code></pre>
<h3 id="links" tabindex="-1">Links</h3>
<p>Within a record, you link to another record by writing its identifier between double brackets.</p>
<p>Example:</p>
<pre><code>A link to [[20201209111625]] record B.
</code></pre>
<p>From v2 onwards, you can also include link text within the brackets.</p>
<p>Example:</p>
<pre><code>A link to [[20201209111625|record B]]
</code></pre>
<p>Cosma allows you to define link types. Each link type is defined by a name, a colour and a stroke pattern. To apply a type to a link, add the name of the type followed by a colon before the identifier.</p>
<p>Example:</p>
<pre><code>Concept B is derived from [[generic:20201209111625]] concept A.
Person D wrote against [[opponent:20201209111625]] person C.
</code></pre>
<div class="astuce">
<p>If you do not use the alternative syntax, you can still improve the readability of records in the cosmoscope by using the <code>link_symbol</code> parameter. It accepts as value an arbitrary Unicode string, which will replace the identifier and square brackets in the HTML rendering of the records. This visually lightens the text by replacing numeric identifiers with a shorter, personal convention. This can be, for example, a single symbol such as a manicle ☞, an arrow →, a star ⟡, etc.</p>
</div>
<h3 id="unique-identifiers" tabindex="-1">Unique identifiers</h3>
<p>To be correctly interpreted by Cosma, each record must have a unique identifier. This identifier serves as a target for links between records.</p>
<p><strong>The identifier must be a unique string.</strong></p>
<p>By default, Cosma generates 14-digit identifiers in the form of a timestamp (year, month, day, hours, minutes and seconds). This is inspired by Zettelkasten note-taking applications such as <a href="https://zettelkasten.de/the-archive/">The Archive</a> and <a href="https://www.zettlr.com">Zettlr</a>.</p>
<p>We plan to eventually allow the user to define an identifier pattern of their choice, like in Zettlr.</p>
<div class="note">
<p>Many interrelated note-taking applications use file names as targets for links between files. They maintain links automatically when file names are changed. By choosing to use unique identifiers instead, we have designed Cosma with a more traditional, stricter, WWW-like approach. We believe this is the easiest way to avoid <a href="https://en.wikipedia.org/wiki/Link_rot">link rot</a> in a sustainable way. Avoiding the reliance on automatic link maintenance is especially important if you wish to make your data less dependent on specific applications.</p>
</div>
<h3 id="creating-records-with-cosma" tabindex="-1">Creating records with Cosma</h3>
<p>Cosma includes several commands that allow you to quickly create records with automatically generated YAML headers.</p>
<div class="important">
<p>These commands only work when <code>select_origin</code> is set to <code>directory</code> (i.e. for Markdown files).</p>
<p>Creating files requires a configuration file with <code>files_origin</code> set to a valid path. This can either be a <code>config.yml</code> file in the current working directory, or a project indicated by adding the <code>-p/--projects</code> option.</p>
</div>
<h3 id="record-create-a-record-(form-mode)" tabindex="-1"><code>record</code> : create a record (“form” mode)</h3>
<pre><code>cosma record
cosma r
cosma record --project <name>
</code></pre>
<p>This command allows you to create a record in the manner of a form. Once the command is launched, the software prompts you for a title, one or several types, and one or several keywords. Only the title is required.</p>
<h3 id="autorecord-create-a-record-(one-liner-mode)" tabindex="-1"><code>autorecord</code> : create a record (“one-liner” mode)</h3>
<pre><code>cosma autorecord <title> <type> <keywords>
cosma a <title> <type> <keywords>
cosma autorecord <title> <type> <keywords> --project <name>
</code></pre>
<p>This command allows you to create a record with a single input. Only the title is required. If you enter multiple types or multiple keywords, separate them with commas (spaces after the comma are ignored). Example: <code>type A, type B</code>, <code>keyword1, keyword2</code>.</p>
<h3 id="batch-create-a-batch-of-records" tabindex="-1"><code>batch</code> : create a batch of records</h3>
<pre><code>cosma batch <path>
cosma b <path>
cosma batch <path> --project <name>
</code></pre>
<p>This command allows you to create several records at once. <code><path></code> corresponds to the location of a file in JSON or CSV format describing the records to be created. As with all other record creation modes, the title is mandatory and the other fields are optional.</p>
<p>Example of a JSON file containing two records:</p>
<pre><code class="language-json">[
{
"title": "Title of the record"
},
{
"title": "Paul Otlet",
"type": ["Person", "History"],
"metas": {
"first name" : "Paul",
"family name": "Otlet"
},
"tags": ["documentation"],
"begin" : "1868",
"end" : "1944",
"content": "Lorem...",
"thumbnail" : "image.jpg",
"references" : ["otlet1934"]
}
]
</code></pre>
<p>Example of a CSV file containing these same records:</p>
<pre><code class="language-csv">title,content,type:nature,type:field,meta:firstname,meta:lastname,tag:gender,time:begin,time:end,thumbnail,references
Title of the file,,,,,,,,,,,
Paul Otlet,Lorem...,Person,History,Paul,Otlet,man,1868,1944,image.png,otlet1934
</code></pre>
<div class="note">
<p><strong>Batch record creation and identifiers</strong></p>
<p>Cosma generates 14-digit identifiers in the form of a timestamp (year, month, day, hours, minutes and seconds). This means you can manually create one record per second, or 86,400 records per day. Another way to phrase it is to say there is a range of 86,400 identifiers reserved for manual record creation each day. For example, on 15 January 2022, these identifiers range from 20220115000000 to 20220115235959.</p>
<p>To prevent generating duplicate identifiers, the batch creation mode generates identifiers by pseudo-timestamp. The first 8 digits, corresponding to the date (year, month, day), are real. Example: 20220115 (15 January 2022). On the other hand, those corresponding to the hours, minutes and seconds are false, generated outside of real time ranges. Example: 256495. As it is impossible to create a record manually at 25h 64min and 95s, there is no risk of generating duplicate identifiers by using both methods simultaneously.</p>
<p>Because of this operation, it is possible to create up to 913,599 records per day and per directory in batch mode before running out of identifiers.</p>
</div>
<h2 id="creating-content-tabular-data-(csv)" tabindex="-1">Creating content: tabular data (CSV)</h2>
<p>Cosma can interpret tabular data contained in local or online CSV files. This is an alternative to using Markdown files.</p>
<p>Tabular data for Cosma must be contained in two files: one for nodes and one for links. The locations of these files must be specified in the configuration file.</p>
<div class="note">
<p>You can generate CSV files with a spreadsheet program. In fact, it is precisely because online collaborative spreadsheet programs such as Google Sheets exist that we have added CSV support to Cosma: they provide a cheap and efficient way to set up collective knowledge work.</p>
<p>We offer <a href="https://docs.google.com/spreadsheets/d/1Wxm3lxgSnHaqsIVQVyuMR4TmiJwjDSr-KJWaKqNjz_o/">a Google Sheets template</a> for you to use as a guide. One sheet should be dedicated to nodes and another to links. Click on File › Share › Publish to Web. Select the sheet containing the nodes, then change the format from "Web Page" to "Comma Separated Values (.csv)". Click "Publish" and copy the share link. Repeat the operation for the sheet containing the links (in our template, this is the "Extraction" sheet and not the "Links" sheet). Paste each link in the corresponding field of the project configuration.</p>
</div>
<p>The column headers of the CSV files must comply with the following rules.</p>
<h3 id="metadata-for-nodes" tabindex="-1">Metadata for nodes</h3>
<p>For nodes, only the <code>title</code> metadata is required.</p>
<table>
<thead>
<tr>
<th>name</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>title</code></td>
<td>Title (required)</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Unique identifier</td>
</tr>
<tr>
<td><code>type:<name></code></td>
<td>Record typology. Each typology contains one or more types. For example, one column may be called <code>type:primary</code> and contain types like <code>person</code>, <code>work</code>, <code>institution</code>; another column may be called <code>type:secondary</code>, with other types.</td>
</tr>
<tr>
<td><code>tag:<name></code></td>
<td>Keyword list</td>
</tr>
<tr>
<td><code>meta:<name></code></td>
<td>User-defined metadata</td>
</tr>
<tr>
<td><code>time:begin</code>, <code>time:end</code></td>
<td>Metadata used by the chronological mode</td>
</tr>
<tr>
<td><code>content</code></td>