feat(doc): local registries

data/doc/documentation.xml

@@ -7228,6 +7228,133 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
 </section>
 <section xml:id="registers">
   <title>Local authority registers</title>
+  <para>In TEI Publisher 9 a suggested structure for local taxonomies and registers for people, places and organizations
+     has been introduced in recognition of a common need in editorial projects to create and maintain such datasets.
+     As with virtually all other aspects, the default solution can be fully customised, extended and tailored to the 
+     specific needs of the project.
+  </para>
+  <figure>
+    <title>Default structure of the registers collection</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="register-structure.png" width="400px"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para>To keep things simple, we have extracted each type of register into a separate TEI document. By default these reside in 
+    <code>data/registers</code> collection, but location can be changed in the <code>modules/config.xqm</code>. Below is 
+    the relevant excerpt from the configuration file:</para>
+  <programlisting language="xquery">    (:~
+    : The root of the collection hierarchy containing registers data.
+    :)
+   declare variable $config:register-root := $config:data-root || "/registers";
+  </programlisting>
+  <para>
+    The people, place and organization registers have a similar structure, utilizing a <code>&lt;standOff&gt;</code> as a wrapper
+    for <code>listPerson</code>, <code>listPlace</code> and <code>listOrg</code>, respectively. Keywords register, as is more 
+    fitting for this kind of ontology, uses <code>taxonomy</code> instead.
+  </para>
+  <para>The sample below presents the general structure of the person register as well as microstructure of a sample entry. 
+    Since in TEI Publisher we are using the GND as the data source for annotating references to people, the local register entries
+    are reflecting some of the GND information, namely short biographical note, birth and death information and a list of professions.
+    Nevertheless, this structure can be adjusted as necessary within the project.
+  </para>
+  <figure>
+    <title>Default encoding structure of the person register</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="register-xml.png" width="800px"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <section>
+    <title>Maintaining authority registers</title>
+    <para>Typically, when annotating the text of the transcription we will consult an authority file, 
+      either an external resource like GND or VIAF, or one internal to the project to identify a reference to a place or an individual.
+      On the level of the TEI encoding we will be usually just adding an identifier to the dedicated element.
+    </para>
+    <para>As it is a tedious and error prone task to provide these identifiers manually, TEI Publisher offers a 
+      mechanism to query authority registers, present matching results and make a selection in a user friendly interactive component
+       (see arrow marked as 1. on the screenshot below). 
+      Thanks to its functionality a connection can be made without ever typing or copying long identifiers.</para>
+      <programlisting language="xml">... in Altenberg &lt;persName ref="gnd-136602592"&gt;Ambrosius Leibnütz&lt;/persName&gt; ...</programlisting>
+
+    <para>As a side effect of such an operation, TEI Publisher creates a local register entry for the selected entity.</para>
+    <para>Nevertheless, from time to time an entry will not yet exist in the authority register we are using, or possibly the 
+      information there is incomplete or incorrect. One could edit the local register manually in such cases, but from 
+      TEI Publisher version 9 we now offer facilities to edit or create an entry in 
+      the local register (see arrows marked 2 and 3 in the screenshot) through a form-based interface. Just click on the 
+      <emphasis>pencil</emphasis> icon to edit the entry locally (or use <emphasis>plus sign</emphasis> icon to add a completely new one.</para>
+      <figure>
+        <title>Accessing register linking and editing functions in annotation editor</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="register-edit.png" width="800px"/>
+          </imageobject>
+        </mediaobject>
+      </figure>
+      <section>
+        <title>Editing a person</title>
+        <para>Say, we would like to add a variant name for our <emphasis>Ambrosius Leibnütz</emphasis> entry, 
+          and also translate the content into English. From the annotation editor we can use the <emphasis>pencil</emphasis> icon 
+          to open the editing form. It will appear in the right hand panel and presents form controls for 
+          the information stored in the register. We can edit these fields and just press the <emphasis>save</emphasis> icon when we're done. 
+          At this point new data will be stored in the local register. NB: saving obviously only works for logged in users.</para>
+          <figure>
+            <title>Form for a person entry</title>
+            <mediaobject>
+              <imageobject>
+                <imagedata fileref="register-form.png" width="800px"/>
+              </imageobject>
+            </mediaobject>
+          </figure>
+      </section>
+      <section>
+        <title>Customizing local registers</title>
+        <para>Each project may have particular needs in terms what kinds of registers it needs and what kind of 
+          microstructure the registry entries need to have. Therefore TEI Publisher proposes a modular approach 
+          to the subject which allows for customizations. Nevertheless we have several distinct conceptual blocks 
+          which need careful orchestration to smoothly work together. Namely, we need a place to store the register, 
+          the data model for individual entry, the model and layout template for the form and the api endpoints 
+          and corresponding functions for all CRUD (create, read, update, delete) operations on the register entry.</para>
+          <para>The API endpoints for registers customization start with <code>/api/register</code> and call a set of functions from 
+            <code>modules/registers.xql</code>, which can be customized to reflect differences in the data 
+            coming from external authority and local entry structures.</para>
+          <para>As mentioned before, location of the registers is determined via <code>$config:register-root</code> variable in <code>config.xqm</code>. 
+            In the same module we will find further customization options related to registers: location of the models for the input forms 
+            (in <code>$config:register-forms</code>) and dedicated configuration for each of the editable register types.</para>
+            <para>The actual forms themselves are located in <code>templates/pagesannotations</code> as they are effectively 
+              HTML files with embedded Fore form webcomponents.</para>
+            <figure>
+              <title>Register configuration in config.xqm</title>
+              <mediaobject>
+                <imageobject>
+                  <imagedata fileref="register-config.png" width="800px"/>
+                </imageobject>
+              </mediaobject>
+            </figure>
+            <para>The <code>$config:register-map</code> allows to determine the following information for each registry:</para>
+            <orderedlist>
+              <listitem>
+                <para><code>id</code>: identifier by which the registry can be reached in the database, either to access 
+                  information about existing entry or to determine the insertion point for a new one; e.g. for 
+                  the <emphasis>person</emphasis> registry it is by default set to <code>pb-person</code> which is the @xml:id attribute of the TEI element in
+                <code>data/registers/persons.xml</code></para>
+                <programlisting>&lt;TEI xmlns="http://www.tei-c.org/ns/1.0"  xml:id="pb-persons"&gt;</programlisting>
+                <para>this identifier is always resolved in the context of the <code>$config:register-root</code> variable 
+                  to avoid potential conflicts</para>
+              </listitem>
+              <listitem>
+                <para><code>default</code>: identifier by which the default data model for an entry can be accessed; this identifier is always resolved in the context of the <code>$config:register-forms</code></para>
+              </listitem>
+              <listitem>
+                <para><code>prefix</code>: a prefix for the newly created entries, e.g. a new person will be given an id 
+                  like <code>person-00015</code> or similar, depending how many have been created locally earlier.</para>
+              </listitem>
+            </orderedlist>
+      </section>
+  </section>
+
 </section>
   <section xml:id="production">
     <title>TEI Publisher in production</title>