-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathguidelines.html
More file actions
409 lines (397 loc) · 20.3 KB
/
Copy pathguidelines.html
File metadata and controls
409 lines (397 loc) · 20.3 KB
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
<!DOCTYPE html>
<html style="font-size: 16px;">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta charset="utf-8" />
<meta name="keywords" content="" />
<meta name="description" content="" />
<meta name="page_type" content="np-template-header-footer-from-plugin" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Open Stemmata</title>
<link rel="stylesheet" href="static/css/style.css" media="screen" />
<!--<link rel="stylesheet" href="Page-1.css" media="screen">-->
<script class="u-script" type="text/javascript" src="static/js/jquery.js" defer=""></script>
<script class="u-script" type="text/javascript" src="static/js/nicepage.js" defer=""></script>
<meta name="generator" content="Nicepage 2.29.0, nicepage.com" />
<link id="u-theme-google-font" rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Roboto:100,100i,300,300i,400,400i,500,500i,700,700i,900,900i|Open+Sans:300,300i,400,400i,600,600i,700,700i,800,800i" />
<link id="u-page-google-font" rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Lato:100,100i,300,300i,400,400i,700,700i,900,900i" />
<link rel="icon" href="static/images/favicon.ico" />
<script type="application/ld+json">{
"@context": "http://schema.org",
"@type": "Organization",
"name": "",
"url": "index.html",
"logo": "static/images/logo_partial.png"
}</script>
<meta property="og:title" content="Welcome to Open Stemmata!" />
<meta property="og:type" content="website" />
<meta name="theme-color" content="#478ac9" />
<link rel="canonical" href="index.html" />
<meta property="og:url" content="index.html" />
</head>
<body class="u-body">
<header class="u-clearfix u-header u-header" id="sec-ffda">
<div class="u-clearfix u-sheet u-sheet-1">
<a href="index.html" class="u-align-center u-image u-logo u-image-1" data-image-width="827"
data-image-height="827">
<img src="static/images/logo_header.png" class="u-logo-image u-logo-image-1"
data-image-width="86" alt="logo for Open Stemmata" />
</a>
</div>
</header>
<section id="sidebar">
<div>
<ol>
<li><a class="sidebar" href="#step1">Prepare your record</a></li>
<li><a class="sidebar" href="#step2">Prepare the metadata</a></li>
<li><a class="sidebar" href="#step3">Prepare your stemma</a></li>
<li><a class="sidebar" href="#step4">Pull your work</a></li>
</ol>
</div>
</section>
<section id="page-wrap">
<div>
<div class="u-clearfix u-expanded-width-sm u-expanded-width-xs u-gutter-14 u-layout-wrap u-layout-wrap-1">
<h1>Guidelines</h1>
<div>
<h2>In a nutshell</h2>
<p>Our idea is to create an open source collection of <b>historical text genealogies</b>, in
forms of tree-like graphs (also called <i>stemma</i>), for <b>any <!--european--> language</b>.</p>
<p>N.B.: only directed stemmata are considered, and undirected graphs are left out of the scope of our database (at least for now).</p>
<p>Trees are encoded with the<a href="https://en.wikipedia.org/wiki/DOT_(graph_description_language)" target="_blank">
DOT graph description language</a>: the image on the right is created out of the code on the left.</p>
<pre><code>
<img src="static/images/guidelines_basicGraph.png"
alt="basic graph" width="300" class="u-image-1 u-image" style="float:right;"/>
digraph {
omega ->A;
omega ->B;
A -> C;
A -> D;
B -> E;
B -> F;
}
</code></pre>
<p>Working with images generated out of the code allows us, on the long term, to query the code and conduct
quantitative research on <!--(artificial)--> textual traditions.</p>
</div>
<div>
<h2>Contribute</h2>
<p>You want to contribute? It is easy. To do so you need:</p>
<ol>
<li>To prepare your data according to our guidelines (detailed <a href="#step1">infra</a>).</li>
<li>To share these data via email or (better) with a pull request (explained <a href="#step4">infra</a>).</li>
</ol>
<div>
<h3 id="step0">0. Preliminary remarks</h3>
<ul>
<li>We do not ask you to <i>produce</i> a stemma, but to <i>reproduce</i> a stemma found in a scientific work.</li>
<li>If stemma are relatively static for classical texts (Virgil, Homer…), it is not always the case for other
languages (<i>e.g.</i> the <i>Devisement dou monde</i> of Marco Polo). If several stemmata are available,
we trust you to choose the best or reproduce all relevant stemmata when necessary. Metadata are here to document this choice</li>
</ul>
</div>
<div>
<h3 id="step1">1. Prepare your record</h3>
<p>An example folder <a href="https://github.com/OpenStemmata/database/tree/main/examples/Segre_1971_Roland" target="_blank">is available
online</a>. You can also have a look at <a href="https://github.com/OpenStemmata/database" target="_blank">the
actual data</a>, which are organised according to linguistic traditions (we follow the
<a href="https://en.wikipedia.org/wiki/List_of_ISO_639-3_codes" target="_blank">tist of ISO 639-3 codes</a>:
<i>fro</i> for medieval French, <i>gmh</i> for medieval German…).</p>
<p>Each record is contained in a dedicated folder, named with the structure: <i>scholar_year_text</i> (see examples). It is made of up to three files (with the exact same name than those given <i>infra</i>). </p>
<ul>
<li>Two are mandatory:
<ul>
<li><code>metadata.txt</code> is metadata file about the stemma (author of the text, writing date, name of the
philologist who made the stemma, scientific publication in which the stemma was found…). You can find an
example <a href="https://github.com/OpenStemmata/database/blob/main/examples/Segre_1971_Roland/metadata.txt" target="_blank">here</a>.</li>
<li><code>stemma.gv</code> is DOT format file (extension <i>.gv</i>) for the stemma. You can find an example
<a href="https://github.com/OpenStemmata/database/blob/main/examples/Segre_1971_Roland/stemma.dot" target="_blank">here</a>.</li>
</ul>
</li>
<li>One is optional:
<ul>
<li><code>stemma.png</code> is an image scan (in black and white, as a png file) found in the source (article, edition…). You can find an
example <a href="https://github.com/OpenStemmata/database/blob/main/examples/Segre_1971_Roland/stemma.png" target="_blank">here</a>.</li>
</ul>
</li>
</ul>
</div>
<div>
<h3 id="step2">2. Prepare the metadata.</h3>
<p>This is an important step! You need to explain what are your sources (traceability) and who you are
(to receive credit for your work!). You need to prepare four types of metadata.</p>
<ul>
<li>Three are (at least partially) mandatory:
<ul>
<li>From which secondary source is the stemma from (an article, a critical edition…)</li>
<li>Basic information about the text: author, title, date, location.</li>
<li>Basic information about the informer (you!)</li>
</ul>
</li>
<li>One is optional
<ul>
<li>Description of the witnesses, starting with their siglum (e.g. O or A2), and the identification of the material document(s), preferably
under the form City, Repository, Shelfmark (e.g. Oxford, Bodleian Library, Digby 23).
</li>
</ul>
</li>
</ul>
<p>An <a href="https://openstemmata.github.io/document-your-stemma.html" target="_blank">online form</a> is
available to help you create the <code>metadata.txt</code> file you need to attach to your stemma.</p>
<p><b>Dates</b> should be encoded as:
</p>
<ul>
<li>a single year (e.g., 1252)</li>
<li>a date range (e.g., 1300-1350, if something is datable to the first half of the 14th century).</li>
</ul>
<p><b>Places</b> should be indicated with their modern names preferably with an indication of the superior regional unit <i>when relevant</i>,
especially for city,
e.g., <i>Thionville (Moselle, France)</i>. </p>
<p><b>Regions</b> especially cultural/linguistic or traditional regions can still be indicated when relevant, e.g.
<i>Lorraine</i> or <i>Burgundy</i>.</p>
<p>Question marks can be used to mark uncertainty (e.g., 1252?; Burgundy?)</p>
<p>Finally, for normalisation purposes, English names should be used when they exist.</p>
</div>
<div>
<h3 id="step3">3. Prepare your stemma</h3>
<p>
To encode the graph, we use the <a href="https://en.wikipedia.org/wiki/DOT_(graph_description_language)" target="_blank">
DOT graph description language.</a> and write it in a file with the extension <i>.gv</i>.
</p>
<p>To make it easier, you can find a free editor, <i>Edotor</i>, at <a href="https://edotor.net/?engine=dot?engine=dot#%23%20Place%20the%20cursor%20inside%20%22graph%22%20to%20get%20some%20refactoring%20options%0A%0Adigraph%20%7B%0A%0A%20%20%20%20%23%20To%20refactor%20nodes%2C%20place%20the%20cursor%20left%20to%20a%20node%20name%0A%20%20%20%20omega%20-%3E%20b%3B%0A%20%20%20%20omega%20-%3E%20c%3B%0A%20%20%20%20c%20-%3E%20d%3B%0A%20%20%20%20c%20-%3E%20e%3B%0A%20%20%20%20omega%20-%3E%201%3B%20%0A%20%20%20%201%20-%3E%20a%20%23%20use%20numbers%20for%20unlabelled%20nodes%20in%20the%20source%20stemma%0A%20%20%20%201%20-%3E%20aprime%0A%0A%20%20%20%20%23%20Hover%20over%20color%20names%20to%20get%20a%20color%20picker%0A%20%20%20%20b%20-%3E%20e%20%5Bstyle%3D%22dashed%22%5D%0A%20%20%20%20b%20-%3E%20c%20%5Bdir%3Dnone%2C%20style%3D%22dashed%22%5D%3B%20%23%20for%20the%20exception%20where%20an%20undirected%20link%20is%20existant.%0A%0A%20%20%20%20%23%20Grey%20color%20is%20used%20for%20hypothetical%20nodes%3B%20labels%20can%20be%20redefined%20if%20needed%0A%20%20%20%20omega%20%5Bcolor%3D%22grey%22%5D%3B%0A%20%20%20%201%20%5Bcolor%3D%22grey%22%2C%20label%3D%22%22%5D%3B%20%0A%20%20%20%20aprime%5Blabel%3D%22a'%22%5D%0A%0A%7D%0A" target="_blank">this adress</a>.</p>
<p>Here are a few rules one need to follow:</p>
<table style="width:100%">
<tr>
<td>Simple graph</td>
<td>
<pre><code>
digraph {
omega ->A;
omega ->B;
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule1.png" alt="rule 1" width="150"/></td>
</tr>
<tr>
<td>Greek letter</td>
<td>
<pre><code>
digraph {
omega[label="Ω"];
omega ->A;
omega ->B;
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule4.png" alt="rule 4" width="150"/></td>
</tr>
<tr>
<td>Hypothetical node<br/> (e.g., archetype, subarchetype…)<br/> in grey</td>
<td>
<pre><code>
digraph {
omega[label="Ω", color="grey"];
omega ->A;
omega ->B;
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule5.png" alt="rule 5" width="150"/></td>
</tr>
<tr>
<td>Unnamed (hypothetical) node</td>
<td>
<pre><code>
digraph {
omega[label="Ω", color="grey"];
omega ->A;
omega -> 1;
1 -> B;
1 -> C;
1[label="", color="grey"];
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule6.png" alt="rule 6" width="150"/></td>
</tr>
<tr>
<td>Contamination</td>
<td>
<pre><code>
digraph {
omega[label="Ω", color="grey"];
omega ->A;
omega -> 1;
1 -> B;
1 -> C;
1[label="", color="grey"];
A -> B [style="dashed"];
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule2.png" alt="rule 2" width="150"/></td>
</tr>
<tr>
<td>Unidrected <br/>contamination</td>
<td>
<pre><code>
digraph {
omega[label="Ω", color="grey"];
omega ->A;
omega -> 1;
1 -> B;
1 -> C;
1[label="", color="grey"];
A -> B [style="dashed", dir=none];
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule3.png" alt="rule 3" width="150"/></td>
</tr>
<tr>
<td>Uncertainty<br/> (usually expressed with ?<br/> or --- dashed lines <br/> by editors, <br/> not to be confused<br/> with contamination)</td>
<td>
<pre><code>
digraph {
omega[label="Ω", color="grey"];
omega ->A[color="grey"];
omega -> 1;
1 -> B;
1 -> C;
1[label="", color="grey"];
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule7.png" alt="rule 3" width="150"/></td>
</tr>
</table>
<p>When encoding the stemma, you should <b>always favor spirit (i.e., semantism) over letter (i.e. formatting)</b>.</p>
<div>
<h4>Rarer cases</h4>
<div>
<h5>Extra-archetypal contamination</h5>
<table style="width:100%">
<tr>
<td>
<img src="static/images/Ewert_1932_GuiWarewic.png" alt="Stemma from Ewert 1932" width="450"/>
(Ewert, 1932, Gui de Warewic)
</td>
<td>
<p>Extra-archetypal (or extra-stemmatic) contamination is the case where a witness is contaminated by a source
outside of the descendants of the archetype. Some editors indicate it with an arrow coming from the outside, while other simply
indicate it in the text.</p>
</td>
</tr>
</table>
<p>In both cases, it is encoded by added the necesseray missing node to turn the representation into the standard directed graph,
with a single root. That means: 1. adding an unnamed root, 2. adding the missing hypothetical node, outside of the archetypal tradition,
that is the source of the contamination, 3. signaling the contamination from this outside missing node to the contaminated witness.
</p>
<table style="width:100%">
<tr>
<td>Extra-archetypal <br/>contamination</td>
<td>
<pre><code>
digraph {
original[color=grey, label=""]
source[color="grey", label=""]
x[color="grey"];
original->source;
source->A[style="dashed"];
original->x;
x->A;
x->B;
}
</code></pre>
</td>
<td><img src="static/images/Guidelines_rule8.png" alt="extra-archetypal contamination encoding" width="150"/></td>
</tr>
</table>
</div>
</div>
</div>
<div>
<h3 id="step4">4. Pull your work (Optional)</h3>
<p><strong>If you can't make a pull request</strong>, drop us the files with a few words by <strong>opening an <a href="https://github.com/OpenStemmata/database/issues/new">issue</a></strong> and
appending the files!</p>
<img src="static/images/issue.png" alt="Opening an issue" width="800"/>
<p>But please, if you can do a pull request, we prefer it this way!</p>
<p>We have decided to use Github to work collaboratively. To avoid major problems while sharing data, we recommend to
share your work using a pull request. Here's how.</p>
<ol>
<li>Fork the <a href="https://github.com/OpenStemmata/database" target="_blank">official repository</a> (<i>i.e.</i> make a copy of the repository that you can modify)<br/><br/>
<img src="static/images/fork1.png" alt="Fork 1" width="500"/><br/></li>
<li>Clone your new fork locally (<code>YOUR_PSEUDO</code> has to be replaced by your GitHub username). In the terminal, write:
<pre>
<code>
git clone git@github.com:YOUR_PSEUDO/database.git
</code>
</pre>
</li>
<li>Track the original repository as a remote of the fork:
<pre>
<code>
git remote add --track master upstream git@github.com:OpenStemmata/database.git
git fetch upstream
</code>
</pre>
</li>
<li>On your computer, create your record (a folder containing the following files: <code>metadata.txt</code>,
<code>stemma.dot</code>, and (optional) <code>stemma.png</code>) in the <code>Data</code> folder. Create a branch
<pre>
<code>
git checkout -b BRANCH_NAME
</code>
</pre>
</li>
<li>Add, commit, and push the changes
<pre>
<code>
git add PATH/TO/metadata.txt PATH/TO/stemma.dot PATH/TO/stemma.png
git commit -m "NAME_OF_THE_TEXT"
git push -u origin BRANCH_NAME
</code>
</pre>
</li>
<li>Submit your pull request by going back to your repo (control that the name in the red rectangle is the
same than <code>BRANCH_NAME</code>) and clicking on "compare and pull request".
<br/><br/><img src="static/images/fork2.png" alt="Fork 2" width="500"/><br/></li>
<li>Create the pull request (the name in the red rectangle should be the same than <code>BRANCH_NAME</code>).
<br/><br/><img src="static/images/fork3.png" alt="Fork 3" width="500"/><br/></li>
</ol>
</div>
</div>
</div>
</div>
</section>
<footer class="u-align-center u-clearfix u-footer u-grey-80 u-footer" id="sec-7a6d">
<!--<div class="u-clearfix u-sheet u-sheet-1">-->
<p class="u-small-text u-text u-text-variant u-text-1">
<a href="https://github.com/OpenStemmata"
class="u-active-none u-border-none u-btn u-button-link u-button-style u-hover-none u-none u-text-body-alt-color u-btn-1"
>Open Stemmata</a> | 2020 </p>
</footer>
<script src='//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js'></script>
<script>
$(function() {
var offset = $("#sidebar").offset();
var topPadding = 15;
$(window).scroll(function() {
if ($(window).scrollTop() > offset.top) {
$("#sidebar").stop().animate({
marginTop: $(window).scrollTop() - offset.top + topPadding
});
} else {
$("#sidebar").stop().animate({
marginTop: 0
});
};
});
});
</script>
</body>
</html>