forked from majlis-erc/manuForma
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdocs.html
503 lines (503 loc) · 29.1 KB
/
docs.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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>manuForma User Handbook</title>
<link rel="stylesheet" href="handbook/styles.css"/>
<link
href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap"
rel="stylesheet"/>
</head>
<body>
<!-- Sidebar Navigation -->
<div class="sidebar">
<a href="index.html" class="logo" target="_blank">
<img width="200" height="40" src="resources/images/hn/logo_manuforma.svg"
alt="resources/images/hn/logo_manuforma.svg"/>
</a>
<h1>manuForma Handbook Version 1.0.0</h1>
<a href="#introduction" class="nav-h1">Introduction</a>
<a href="#what-manuforma-does" class="nav-h2">What manuForma does</a>
<a href="#what-this-handbook-does" class="nav-h2">What this Handbook does</a>
<a href="#creating-an-account" class="nav-h1">Creating an Account</a>
<a href="#logging-in" class="nav-h1">Logging in</a>
<a href="#managing-records" class="nav-h1">Managing Records</a>
<a href="#opening-records-from-the-database" class="nav-h2">Opening Records</a>
<a href="#creating-new-records" class="nav-h2">Creating New Records</a>
<a href="#uploading-records-from-your-computer" class="nav-h2">Uploading Records</a>
<a href="#saving-records" class="nav-h1">Saving Records</a>
<a href="#edit-records" class="nav-h1">Edit Records</a>
<a href="#subsections" class="nav-h2">Subsections</a>
<a href="#fields" class="nav-h2">Fields</a>
<a href="#features" class="nav-h2">Features</a>
<a href="#add-references-to-other-records" class="nav-h1">Add References</a>
<a href="#create-relationships-between-records" class="nav-h1">Create Relationships</a>
<a href="#edit-transcriptions" class="nav-h1">Edit Transcriptions</a>
<a href="#paragraphs" class="nav-h2">Paragraphs</a>
<a href="#linebreaks" class="nav-h2">Linebreaks</a>
<a href="#italic-text" class="nav-h2">Italic Text</a>
<a href="#extending-an-existing-record-for-another-project" class="nav-h1">Extending
Records</a>
</div>
<!-- Main Content -->
<div class="content">
<h1 id="introduction">Introduction</h1>
<h2 id="what-manuforma-does">What manuForma does</h2>
<p>manuForma is a tool that allows you to create TEI-XML files of manuscripts and other
related entities inside your browser without the need of external programs like
OxygenXML. You can submit the files to a GitHub repository or save them on your
local hard drive. Whenever you want to continue working on your records, you can
again load them into manuForma. It also allows you to reference different records to
model dependencies between them, such as persons who are referenced as authors in
work records. And you can even express complex relationships between your
records.</p>
<h2 id="what-this-handbook-does">What this Handbook does</h2>
<p>This handbook will introduce you to the functionalities of <em>manuForma</em>. You
will learn how to create records, how to load existing records, how you can edit
them and how to create references between them. In other words, this handbook is
concerned with the technical side of TEI records. You will not learn how to describe
manuscripts from a paleographic point of view. We assume that you already know these
things. manuForma provides explanations about the intended usage of the fields when
you hover your mouse over the “?” button next to the field’s name.</p>
<h1 id="creating-an-account">Creating an Account</h1>
<ol type="1">
<li>On the start page, click the button in the upper right corner. The login screen
will open.<br />
</li>
<li>Click on “Create New User”.<br />
</li>
<li>Your user name should consist of the first letter of your firstname and your
lastname. No caps, no spaces. E.g., the user name for “Max Mustermann” is
“mmustermann”.<br />
</li>
<li>Fill in the remaining fields and click “Create Account”.<br />
</li>
<li>You can now log in to manuForma.<a href="#fn1" class="footnote-ref" id="fnref1"
role="doc-noteref"><sup>1</sup></a></li>
</ol>
<figure>
<img src="handbook/images/image17.png" alt="handbook/images/image17.png" />
</figure>
<h1 id="logging-in">Logging in</h1>
<ol type="1">
<li>On the start page, click the button in the upper right corner. The login screen
will open.<br />
</li>
<li>Enter your user name and password.<br />
</li>
<li>Click “Login”.</li>
</ol>
<figure>
<img src="handbook/images/image7.png" alt="handbook/images/image7.png" />
</figure>
<h1 id="managing-records">Managing Records</h1>
<p>On the entry page select the kind of entity for you want to work with. As of now,
manuForma supports manuscripts, persons, places, works, and relationships. Creating,
opening, and submitting records works the same for all entities.</p>
<figure>
<img src="handbook/images/image16.png" alt="handbook/images/image16.png" />
</figure>
<ol type="1">
<li>
<h2 id="opening-records-from-the-database">Opening Records from the
Database</h2>
</li>
<li>manuForma will open the main page view where you can search for previously
created records and create new records.<br />
</li>
<li>Click on the collapsible titled “Continue with existing record”. <ol type="1">
<li>You can browse the list of records available in the database by clicking
“Browse”.<br />
</li>
<li>Enter a filename under the header “Search” and click “Search” to look
for a specific record.<br />
<figure><img src="handbook/images/image8.png" alt="handbook/images/image8.png"
/></figure></li>
</ol></li>
<li>If you the internal identifier for the record, you can search for it by entering
it into the field “Search by ID” and clicking it.</li>
</ol>
<figure>
<img src="handbook/images/image12.png" alt="handbook/images/image12.png" />
</figure>
<ol start="3" type="1">
<li>Click “Load selected record” and the record will be loaded into manuForma.</li>
</ol>
<h2 id="creating-new-records">B. Creating New Records</h2>
<ol type="1">
<li>manuForma will open the main page view where you can create new records and
search for previously created records.<br />
</li>
<li>Open the list under the header “New Record” and select the “Manuscript template”
from the selection pane. Click the button “Load Template File”. <figure><img
src="handbook/images/image4.png" alt="handbook/images/image4.png" /></figure></li>
<li>On the top of the screen, click on the option “Admin Metadata”.<br />
</li>
<li>In the upper right corner click the button “Submit to GitHub” to save the record
to your GitHub repository.<br />
</li>
<li>You can also send the record directly to your application by clicking “Submit to
Github”. Enter a one-sentence description of your work. In this case, we suggest
“Created record from own observations.” or “ “Created record from catalog
description.”<br />
</li>
<li>Click “Save”.<br />
</li>
<li>Congratulations! You created your first record with manuForma.</li>
</ol>
<h2 id="uploading-records-from-your-computer">C. Uploading Records from your
Computer</h2>
<ol type="1">
<li>On the entry page select the kind of entity for which you want to open. As of
now, manuForma supports manuscripts, persons, places, and titles.<br />
</li>
<li>manuForma will open the main page view where you can search for previously
created records and create new records.<br />
</li>
<li>Under the header “Upload”, click “Browse”.<br />
</li>
<li>You can then select a file from your computer.<br />
</li>
<li>Click “Load” to upload the file to manuForma.<br />
</li>
<li>If the file is compatible with the schema, you can edit it with this
configuration of manuForma.<br />
</li>
<li>In order to save the file to GitHub or your database, proceed from step 4 in
“Creating New Records”.</li>
</ol>
<h1 id="saving-records">Saving Records</h1>
<p>Once you have completed your work on the record, you need to <em>submit</em> it to
the Github repository, which is the equivalent to saving it. <strong>Changes are not
automatically saved in manuForma!</strong></p>
<ol type="1">
<li>
<p>Click on “Submit to Github”.<br />
</p>
<figure>
<img src="handbook/images/image6.png" alt="handbook/images/image6.png" />
</figure>
</li>
<li>
<p>Write short summary of the changes you made to the record. Here are some
suggestions:</p>
<p>“Linked to work/person records.”</p>
<p>“Added incoded document/heritage data.”</p>
<p>“Added bibliographic items.”</p>
<p>“Added codicological observations from the original manuscript.” / “Added
codicological observations from a catalog.”</p>
</li>
<li>
<p>Click “Save”.<br />
</p>
</li>
<li>
<p>Go the Github repository and select “Pull requests” from the horizontal menu
at the top of the page.</p>
<p>
<br />
</p>
<figure>
<img src="handbook/images/image10.png" alt="handbook/images/image10.png" />
</figure>
</li>
<li>
<p>Select the pull request whose ID matches the record you just submitted to
Github.<br />
</p>
</li>
<li>
<p>You can examine the TEI code by clicking on “Files changed”.<br />
</p>
</li>
<li>
<p>If everything is in order and Github indicates that there are no problems
with the record, click “Merge pull request”.<br />
</p>
</li>
<li>
<p>Your record is now saved to the repository.<br />
</p>
<figure>
<img src="handbook/images/image1.png" alt="handbook/images/image1.png" />
</figure>
</li>
</ol>
<p>
<strong>⁉️ Sometimes GitHub will display a Merge Error when the newly made changes
are in conflict with another submission. Only try to solve these kinds of errors
if you know what you are doing! Otherwise contact the project’s DH
specialist!</strong>
</p>
<h1 id="edit-records">Edit Records</h1>
<h2 id="subsections">Subsections</h2>
<p>To enter data, select one of the subsections on the left side of the application.
Each subsection is subdivided into collapsibles that aggregate the data into smaller
parts. The headlines of collapsibles summarize the kinds of data that can be
entered. Sometimes these headlines change when data have already been entered,
summarizing the main points.</p>
<p>The largest units you can edit in manuForma are collapsibles–units containing several
fields and features. Together they often comprise complex items such as
bibliographic entries.</p>
<h3 id="create-collapsibles">Create collapsibles</h3>
<p>To create a new collapsible, open one of the existing collapsibles in the document
and select the first grey button starting with a plus sign and then a description of
its contents. For example:</p>
<figure>
<img src="handbook/images/image5.png" alt="handbook/images/image5.png" />
</figure>
<h3 id="move-collapsibles">Move collapsibles</h3>
<p>To reorder a sequence of collapsibles, open the collapsible in question and select
the down or up arrow of the top most field.</p>
<figure>
<img src="handbook/images/image11.png" alt="handbook/images/image11.png" />
</figure>
<h3 id="delete-collapsibles">Delete collapsibles</h3>
<p>To delete a collapsible, open the collapsible in question and select the X button of
the top most field.</p>
<figure>
<img src="handbook/images/image15.png" alt="handbook/images/image15.png" />
</figure>
<h2 id="fields">Fields</h2>
<p>Fields are the main components that you will interact with in manuForma. They are
usually blank fields into which you enter text. Others offer dropdown menus with
options to choose from, allowing us to maintain consistent in our terminology. And
some fields are filled out automatically when linking records like persons, works,
etc.</p>
<p><strong>💡</strong> Because there can be dozens of different fields in large records
like manuscripts, manuForma offers concise help texts. They may be found to the
right of the field name, mouse over the question mark to activate it.</p>
<p><strong>💡</strong> The MAJLIS team is using domain-specific vocabulary to describe
bibliographic, codicological, paleographic and other phenomena. This allows our team
to use manuForma more efficiently without the need to learn how they are called in
TEI. In case you do want to know the field’s original name in TEI, mouse over the
TEI symbol to the right of the field name.</p>
<p>The templates for the different entity types are equipped with many fields for you to
fill in. However, it may be necessary to create, delete, or move fields to fit the
needs of your entry.</p>
<h3 id="create-fields">Create Fields</h3>
<p>To create a new field, go the field containing (it may take little while to find the
correct field) and open the dropdown list. Select the desired field. Click “Add
field”.</p>
<figure>
<img src="handbook/images/image9.png" alt="handbook/images/image9.png" />
</figure>
<h3 id="move-fields">Move Fields</h3>
<p>To reorder a sequence of fields, select the down or up arrow of the field.<br />
</p>
<figure>
<img src="handbook/images/image3.png" alt="handbook/images/image3.png" />
</figure>
<h3 id="delete-fields">Delete Fields</h3>
<p>To delete a field, click the X button of the field.</p>
<figure>
<img src="handbook/images/image2.png" alt="handbook/images/image2.png" />
</figure>
<h2 id="features">Features</h2>
<p>Features provide additional information to fields. You never have to enter text into
features, as they usually offer dropdown menus with options to choose from. Other
features are filled out automatically when linking records like persons, works,
etc.</p>
<h3 id="create-features">Create Features</h3>
<p>To create a new feature, go the field containing (it may take little while to find
the correct field) and open the dropdown list. Select the desired feature. Click
“Add feature”.<br />
</p>
<figure>
<img src="handbook/images/image14.png" alt="handbook/images/image14.png" />
</figure>
<h3 id="delete-features">Delete Features</h3>
<p>To delete a feature, click on the X next to the feature’s name.</p>
<figure>
<img src="handbook/images/image13.png" alt="handbook/images/image13.png" />
</figure>
<h2 id="add-references-to-other-records">Add References to Other Records</h2>
<p>At the moment you can add references to the following elements: placeName, author,
personName, and title. The process of referencing them is the same for all of
them:<br /> 1. Go to an element that supports references or create one.<br /> 2. In
the same row as the element name, click the option “Look up”.<br /> 3. A small
window opens. Write the name of the record into the search bar and press the
magnifying glass button.<br /> 4. Choose an entry from the list of results and click
“Add to Record”. Then close the window.<br /> 5. The name of the record has been
copied into the element and the URI has been added to the ref attribute.</p>
<p><strong>💡</strong> If the record you want to reference does not exist yet, you can
create one on the spot. Click the “New person name” / “New place name” / “New title
name” button. And you will be directed to the correct form. <strong>Note that you
have to submit and merge the new record before you can find it in
manuForma.</strong></p>
<h2 id="create-relationships-between-records">Create Relationships between Records</h2>
<p>We use the same basic principles for creating relationships that we already know from
the section on references–the main difference is that several records are looked
up.</p>
<ol type="1">
<li>Create a Relation element. It should contain most of the fields you need–but
when dealing with groups of people or items you may need to create additional
fields.<br />
</li>
<li>In the field “Description of relation” select an option from “Choose the type”.
If the relationship contains in its description [Subject] and [Object], proceed
with a). If it contains [Mutual], proceed with b). <ol type="1">
<li>In the relation “Abraham is the father of Yahya” the person entry of
Abraham is the subject and the entry of Yahya is the object of the
statement. The relationship is calling for the fields “Subject of
relation” for Abraham and “Object of relation” for Yahya. Look up the
identifier for both fields as described above in the section “Add
References to Other Records”.<br />
</li>
<li>In the relation “Yefet and David corresponded with each other” both
persons are mutuals of the statement. The relationship is therefore
calling for the field “Mutual relation” for both Yefet and David. Look
up the identifier for both fields as described above in the section “Add
References to Other Records”.</li>
</ol></li>
</ol>
<h2 id="edit-transcriptions">Edit Transcriptions, Translations and Descriptive
Texts</h2>
<p><strong>manuForma does not offer a fully fledged text editor!</strong> Instead, users
can enter markup like italic text in selected fields using a number of special
characters, or <em>Markdown</em>.<a href="#fn2" class="footnote-ref" id="fnref2"
role="doc-noteref"><sup>2</sup></a></p>
<p><strong>💡</strong> The technology behind manuForma, XForms, does not allow us to
create rich text fields that we know from other software. For this reason we had to
come up with this workaround. manuForma will convert the markdown characters into
the proper TEI tags when submitting the file to GitHub, creating valid TEI. Whenever
a record is loaded into manuForma, the TEI commands are replaced with markdown and
you can continue to edit the texts.</p>
<p>So far, users can add the following text markup:</p>
<h3 id="paragraphs">Paragraphs</h3>
<p>To create paragraphs, use a blank line to separate one or more lines of text.</p>
<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="header">
<th>Markdown</th>
<th>TEI</th>
<th>Rendered Output</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<code>I really like using Markdown. I think I'll use it to format all of
my documents from now on.</code>
</td>
<td>
<code><p>I really like using Markdown.</p> <p>I think
I'll use it to format all of my documents from now
on.</p></code>
</td>
<td>I really like using Markdown. I think I’ll use it to format all of my
documents from now on.</td>
</tr>
</tbody>
</table>
<h3 id="linebreaks">Linebreaks</h3>
<p>To create a line break or new line, end a line with two or more spaces, and then type
return.</p>
<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="header">
<th>Markdown</th>
<th>TEI</th>
<th>Rendered Output</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<code>This is the first line. And this is the second line.</code>
</td>
<td>
<code><p>This is the first line.<lb/> And this is the second
line.</p></code>
</td>
<td>This is the first line.<br /> And this is the second line.</td>
</tr>
</tbody>
</table>
<h3 id="italic-text">Italic text</h3>
<p>To italicize text, add one asterisk before and after a word or phrase.<a href="#fn3"
class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a></p>
<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="header">
<th>Markdown</th>
<th>TEI</th>
<th>Rendered Output</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>
<code>Italicized text is the *cat's meow*.</code>
</td>
<td>
<code>Italicized text is the <emph>cat's meow</emph>.</code>
</td>
<td>Italicized text is the <em>cat’s meow</em>.</td>
</tr>
</tbody>
</table>
<h1 id="extending-an-existing-record-for-another-project">Extending an existing record
for another project</h1>
<p>Reusing TEI records from other projects is a complex process that cannot only be
performed in manuForma. The most important prerequisite is to align the legacy data
with the TEI schema used in manuForma – otherwise fields may not be displayed and
new additions may not be reliably saved.</p>
<p><strong>💡</strong> If you are dealing with a large number of records you may want to
add the project metadata of your research project to all files in Oxygen XML or
another XML processor for convenience.</p>
<p>In manuForma you can add the project metadata of your research project to individual
records in the main menu:</p>
<ol type="1">
<li>Select the collapsible “Assign project metadata”.<br />
</li>
<li>Choose the project from the list.<br />
</li>
<li>Click “Load Project Metadata”.<br />
</li>
<li>Proceed with editing or submitting the modified record, as described in other
sections.</li>
</ol>
<aside id="footnotes" class="footnotes footnotes-end-of-document">
<hr />
<ol>
<li id="fn1">
<p>Your full name will only be displayed in JALit if it has been added to
the list of editors in every record, otherwise only the the abbreviated
form will be shown. Contact the project’s DH specialist if this
happens.<a href="#fnref1" class="footnote-back" role="doc-backlink"
>↩︎</a></p>
</li>
<li id="fn2">
<p>See the documentation <a
href="https://www.markdownguide.org/basic-syntax/"
>https://www.markdownguide.org/basic-syntax/</a>. Note that only a
fraction of these commands is available in manuForma!<a href="#fnref2"
class="footnote-back" role="doc-backlink">↩︎</a></p>
</li>
<li id="fn3">
<p>If you want to write an asterisk as part of the text, add a backlash
before it (\*).<a href="#fnref3" class="footnote-back"
role="doc-backlink">↩︎</a></p>
</li>
</ol>
</aside>
</div>
</body>
</html>