add input help / info

diff --git a/lib/stemmaweb/Controller/Root.pm b/lib/stemmaweb/Controller/Root.pm
index aa6329c..59fa097 100644 (file)
--- a/lib/stemmaweb/Controller/Root.pm
+++ b/lib/stemmaweb/Controller/Root.pm
@@ -51,6 +51,17 @@ sub about :Local :Args(0) {
        $c->stash->{template} = 'about.tt';
 }
 
+=head2 help/*
+
+A dispatcher for documentation of various aspects of the application.
+
+=cut
+
+sub help :Local :Args(1) {
+       my( $self, $c, $topic ) = @_;
+       $c->stash->{template} = "$topic.tt";
+}
+
 =head1 Elements of index page
 
 =head2 directory

diff --git a/root/src/about.tt b/root/src/about.tt
index e09124f..292829a 100644 (file)
--- a/root/src/about.tt
+++ b/root/src/about.tt
@@ -16,13 +16,8 @@
  <p>Any logged-in user may upload a text collation in one of several forms:</p>
        <ul>
                <li>Spreadsheet collation (Excel file, CSV file, or tab-separated values). Witness sigla should appear in the first row, one per column; the text of each witness should occur in sequence in the appropriate column, with collated words/readings lined up according to row. CSV and tab-separated value files are assumed to be Unicode, in the UTF-8 encoding.</li>
-               <li>TEI XML, parallel segmentation format. See the documentation <a href="TODO">here</a> for the expected format of the TEI file.</li>
-               <li>TEI XML, as exported from the <a href="http://www.oeaw.ac.at/kvk/cte/">Classical Text Editor</a> tool via the following steps:
-                       <ol>
-                               <li>In the menu Options -&gt; Preferences, under the 'XML' tab, the Apparatus export mode should be set to "&lt;app&gt; tags".</li>
-                               <li>In the menu Format -&gt; Notes/Apparatus settings, the apparatus criticus (and apparatus siglorum, if applicable) should be marked as such.</li>
-                               <li>Run the menu option File -&gt; Export -&gt; XML/TEI to perform the export.</li>
-                       </ol>
+               <li>TEI XML, parallel segmentation format. Please see the documentation <a href="[% c.uri_for( 'help/input' ) %]">here</a> for the expected format of the TEI file.</li>
+               <li>TEI XML, as exported from the <a href="http://www.oeaw.ac.at/kvk/cte/">Classical Text Editor</a> tool. Please see the documentation <a href="[% c.uri_for( 'help/input#cte' ) %]">here</a> for some guidelines on how to prepare your CTE file for upload.</li>
                </li>
                <li>GraphML, as exported from the <a href="http://collatex.huygens.knaw.nl/service/">CollateX</a> tool.</li>
        </ul>

diff --git a/root/src/input.tt b/root/src/input.tt
new file mode 100644 (file)
index 0000000..0fa1b45
--- /dev/null
+++ b/root/src/input.tt
@@ -0,0 +1,55 @@
+[% PROCESS header.tt
+       pagetitle = "Guidelines for XML file uploads to Stemmaweb"
+%]
+<h1>Stemmaweb Help - XML upload guidelines</h2>
+<div id="docco">
+  <h3>Guidelines for TEI parallel segmentation input</h3>
+  <div id="tei">
+    <p>The Stemmaweb uploader can accept a collated text tradition in TEI parallel-segmentation format that adheres to the following guidelines:</p>
+    <ul>
+       <li>The file must have an &lt;msDesc&gt; element in its header which contains a list of all witnesses used in the text in the &lt;listWit&gt; element. Each &lt;witness&gt; element within &lt;listWit&gt; must have an xml:id attribute; this is taken to be the witness sigil, and is expected to appear in the "wit" attribute of the relevant apparatus readings within the text.</li>
+       <li>Individual reading words may be wrapped in &lt;w&gt; tags; if the tag has an xml:id it will be preserved as the reading ID.</li>
+       <li>All text within the main &lt;text&gt; element of the TEI file will be taken to be part of the collation. Paragraph and line divisions are not currently preserved.</li>
+       <li>At the point where any witness appears in the collation, this should be signified with a &lt;witStart&gt; tag within its own apparatus. The first of these will therefore be the first element in any collated text, for example:
+       <pre>
+       &lt;body&gt;
+          &lt;p xml:id="am_1_1"&gt;
+            &lt;app xml:id="AppStart"&gt;
+              &lt;rdg wit="#Jer #K #A #F #B #I #D #J #O #V #X #Y #Z #W"&gt;&lt;witStart/&gt;&lt;/rdg&gt;
+            &lt;/app&gt;
+          [...]
+          &lt;/p&gt;
+       &lt;/body&gt;
+       </pre> Likewise, when a witness text ends this should be noted with a &lt;witEnd&gt; tag. Lacunae within the text may be indicated through successive uses of the &lt;witEnd&gt; and &lt;witStart&gt; tags.</li>
+       <li>Readings as they appeared before scribal corrections may be indicated using the "type" attribute on the &lt;rdg&gt; element, as shown here:
+               <pre>
+            &lt;app xml:id="App530"&gt;
+              &lt;lem wit="#Jer #K #F #B #I #A #D #J #O #V #X #Y #Z #W"&gt;
+                &lt;w xml:id="L414"&gt;զոր&lt;/w&gt;
+              &lt;/lem&gt;
+              &lt;rdg type="a.c." wit="#B"&gt;&lt;w&gt;զո&lt;/w&gt;&lt;/rdg&gt;
+            &lt;/app&gt;
+            </pre></li>
+        <li>An apparatus entry may contain the &lt;lem&gt; tag as well as the &lt;rdg&gt; tag; these are treated as equivalent for the purpose of creating the graph.</li>
+    </ul>
+  </div>
+  
+  <h3>Guidelines for Classical Text Editor export</h3>
+  <div id="cte">
+    <p>The Stemmaweb uploader can accept a collated text tradition exported from CTE, provided that certain guidelines are observed:</p>
+    <ul>
+       <li>Common abbreviations (e.g. 'om.', 'add.', and the like) should be set correctly via the Format -&gt; Document... menu under the General tab. Any other abbreviations or notes are likely to be interpreted as literal readings by the uploader.</li>
+       <li>Avoid notations such as "<em>tr. post</em> word"; this is difficult to parse even for a human and almost impossible for a computer.</li>
+       <li>Be extremely careful with overlapping apparatus entries; if, for example, a pair of entries reads:
+               <pre>
+               dominus deus] tr. A
+               deus] deo A
+               </pre>
+               then you are simultaneously telling CTE that A reads "deus dominus" and "deo dominus", and the export will become confused. Ensure that there is no scope for confusion.</li>
+       <li>Ensure that the critical apparatus (and the apparatus siglorum, if any) is marked as such via the Format -&gt; Notes/Apparatus settings menu.</li>
+       <li>Ensure (via the menu item Options -&gt; Preferences, under the 'XML' tab) that the 'Apparatus export' option is set to "&lt;app&gt; tags".</li>
+    </ul>
+  </div>
+</div>
+  
+[% PROCESS footer.tt %]
\ No newline at end of file