add help docs, especially for relationship mapper

[scpubgit/stemmaweb.git] / root / src / relatehelp.tt

[% PROCESS header.tt
	pagetitle = "Stemmaweb - Relationship mapper"
	applicationstyle = c.uri_for('/css/relationship.css')
%]

<div id="docco">
 <h2>Text relationship mapper</h2>
 <h3>An Interedition prototype interface</h3>
 
 <p>The relationship mapper is a tool born of the joint requirements of the <a href="http://byzantini.st/treeoftexts/">Tree of Texts</a> project at the KU Leuven, and the <a href="http://www.bibelwissenschaft.de/start/editionsprojekte/editio-critica-maior-ecm/">Editio Critica Maior</a> project at the Institute for New Testament Research (INTF), University of Münster. Much of the interface to the tool was contributed by the <a href="http://www.huygens.knaw.nl/">Huygens Institute</a> of the Royal Dutch Academy of Sciences.</p>
 
 <p>The premise of the tool is that, once a set of texts has been collated, there will be a need to chart the relationships between the variants—are they substantially the same word? Different words meaning the same thing? Is one an orthographic variant of the other that should be excluded from any eventual apparatus?</p>
 
 <h3>Making relationships between words</h3>
 
 <p>The tool itself is an interface for allowing these relationships to be declared.  The collation is presented as a variant graph running from left to right.  In a variant graph, each node is a reading, and each witness takes a single path through the readings from beginning to end.  When readings appear vertically aligned with each other, it is an indication that they are variant readings, occurring at the same point in the text. In the example given here, the variants include "ecclesia/que", "beata/sancta/beatam", "uirgine/uirginem", and "tres/duas". </p>
 <img src="[% c.uri_for( '/images/00_variantgraph.png' ) %]">
 
 <p>In 'select' mode, when the nodes are green, you can navigate through the graph. Scrolling up or down will zoom in and out, respectively; dragging the graph will pan it in that direction.  Use this navigation to hone in on the part of the graph to be worked with.</p>
 
 <p> When you are ready to draw relationships, click the 'pencil' icon to the top right of the screen to enter edit mode.  When you select a node (by clicking on it) you can drag it onto another node to indicate that a relationship exists between them. </p>
 <img src="[% c.uri_for( '/images/01_makerelation.png' ) %]">
 
 <p>Fill in the details of the relationship as indicated in the dialog:</p>
 <img src="[% c.uri_for( '/images/02_relationdialog.png' ) %]">
 
<p><em>Type</em> can be any one of the types that appears in the key to the right of the screen.</p>
<p><em>Scope</em> can be one of:</p>
<ul>
	<li>Local - the relationship applies only at this point in the text</li>
	<li>Document - the relationship applies throughout the text</li>
	<li>Global - the relationship applies throughout all texts of this language</li>
</ul>
 <p><em>NOTE:</em> at the moment, "global" scope is treated as "document" scope, i.e. only applies throughout the individual text.</p>
 
 <p>The relationships are displayed as colored paths between readings. While in 'edit' mode, clicking on a relationship path will display the information associated with it, and give the user an option to delete it.  Deletion of a 'global' relationship will remove that relationship throughout the graph.</p>
 <img src="[% c.uri_for( '/images/03_infodelete.png' ) %]">
 
 <p>When you are ready to move elsewhere in the graph, click the 'hand' icon to return to select mode.<p>
 
 
 <h3>Correcting the collation</h3>
 
 <p>Occasionally, the collation as uploaded will contain errors, or need for some other reason to be modified. For example, in the following snippet, the witness Ba96 has a string of words "cetera. Secundo uere asserendo" that have been separated from their analogues in other witnesses through an erroneous collation of the "et" in Ba96 with a later "et" in the majority of witnesses.</p>
 <img src="[% c.uri_for( '/images/00_bad_collation.png' ) %]">
 
 <p>Within the relationship mapper, you can detach a sequence of readings and re-attach it elsewhere as a form of manual collation. To detach one or more readings, drag with the mouse to select an area of the graph that includes all the affected readings.</p>
 <img src="[% c.uri_for( '/images/01_select_decollate.png' ) %]">

 <p>A dialog will pop up to ask which witnesses should be detached from the collation at that point. At least one witness must be selected; at least one witness must also remain unselected. In the case of our example, we wish to detach the reading for Ba96.</p>
 <img src="[% c.uri_for( '/images/02_witness_select.png' ) %]">
 
 <p>The result will be one or more new readings in the graph, identical to the selected ones, with the affected witnesses using the new reading instead of the old one.</p>
 <img src="[% c.uri_for( '/images/03_detached.png' ) %]">

 <p>To attach the separated reading elsewhere, select it and drag it to the corresponding reading elsewhere in the graph, just as though you were making a relationship.</p>
 <img src="[% c.uri_for( '/images/04_rejoin_correct.png' ) %]">

 <p>There should be an option "Merge readings" to specify that the readings are identical; select it.</p>
 <img src="[% c.uri_for( '/images/05_select_merge.png' ) %]">
 
 <p>When two identical readings are merged, the relationship mapper will display a set of suggestions for other readings that might also need to be merged, in light of the change that was just made. Selecting the green button will accept the suggestion; selecting the red button will reject it. If a reading is erroneously merged, it may be detached again in the same manner described above.</p>
 <img src="[% c.uri_for( '/images/06_merged_farther.png' ) %]">

 <p>At the moment, editing the graph in this manner can quickly lead to a rather untidy and confusing-looking graph:</p>
 <img src="[% c.uri_for( '/images/07_merged_mess.png' ) %]">
 
 <p>If at any point it becomes too difficult to follow, please re-load the relationship mapper. The corrected graph will appear in its clean format.</p>
 <img src="[% c.uri_for( '/images/08_merged_reloaded.png' ) %]">

 <!-- 
[% IF language != 'NONE' %]
 <h3>Adding [% language %] morphological information to readings</h3>
 
 <p>It is also possible to add morphological information to the readings in this text (that is, lemma and morphological tagging).  Double click on any reading to bring up the morphology info.  The options therein are:</p>
 
 <ul>
	<li>Indicate if the word is a nonsense word</li>
	<li>Indicate if the word (whether sensical or not) cannot be grammatically correct here</li>
	<li>Indicate the "normal" form of the word for lemmatization purposes.  Any readings linked to this one via 'spelling' or 'orthographic' links will appear when the entry text box is clicked.</li>
	<li>Indicate the correct morphological form of this reading.  The shorthand syntax is:<br/>
		&lt;LEMMA&gt; // cat@&lt;CATEGORY&gt; (type@&lt;TYPE&gt; etc.)<br/>
		Each form must have at least a lemma and a category, and may have a number of additional features depending on the category (e.g. type, gender, number, case.) The possible options are as follows:
		<ul>
[% FOREACH stype IN tagset.structures -%]
	[% IF stype.desc != 'use_features' -%]
			<li>Category [% stype.id -%] ([% stype.desc %])
	[% END -%]
[% IF stype.use_features.size -%]
 has features [% stype.use_features.join(', ') %]
[% END -%]
			</li>
[% END -%]
		</ul>
		<ul>
[% FOREACH ftype IN tagset.features.keys.sort -%]
			<li>Feature [% ftype %] can have values:
				<ul>
[% FOREACH fval IN tagset.features.$ftype.values -%]
					<li>[% fval.short %] =&gt; [% fval.long %]</li>
[% END -%]
				</ul>
			</li>
[% END -%]
		</ul>
	</li>
  </ul>
  
  <p>If initial lemmatization has been performed on the text, a number of readings may appear in yellow rather than green; this means that there are multiple possible morphologies for the reading in question. Double click on the reading to select and save the correct morphology.</p>
[% END -%]
 -->
 
[% PROCESS footer.tt %]