diff --git a/data/doc/documentation.xml b/data/doc/documentation.xml index 07cf8c5e..8ca268a9 100644 --- a/data/doc/documentation.xml +++ b/data/doc/documentation.xml @@ -7228,6 +7228,133 @@ import module namespace docbook-nav="http://www.tei-c.org/tei-simple/navigation/
Local authority registers + 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. + +
+ Default structure of the registers collection + + + + + +
+ To keep things simple, we have extracted each type of register into a separate TEI document. By default these reside in + data/registers collection, but location can be changed in the modules/config.xqm. Below is + the relevant excerpt from the configuration file: + (:~ + : The root of the collection hierarchy containing registers data. + :) + declare variable $config:register-root := $config:data-root || "/registers"; + + + The people, place and organization registers have a similar structure, utilizing a <standOff> as a wrapper + for listPerson, listPlace and listOrg, respectively. Keywords register, as is more + fitting for this kind of ontology, uses taxonomy instead. + + 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. + +
+ Default encoding structure of the person register + + + + + +
+
+ Maintaining authority registers + 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. + + 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. + ... in Altenberg <persName ref="gnd-136602592">Ambrosius Leibnütz</persName> ... + + As a side effect of such an operation, TEI Publisher creates a local register entry for the selected entity. + 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 + pencil icon to edit the entry locally (or use plus sign icon to add a completely new one. +
+ Accessing register linking and editing functions in annotation editor + + + + + +
+
+ Editing a person + Say, we would like to add a variant name for our Ambrosius Leibnütz entry, + and also translate the content into English. From the annotation editor we can use the pencil 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 save 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. +
+ Form for a person entry + + + + + +
+
+
+ Customizing local registers + 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. + The API endpoints for registers customization start with /api/register and call a set of functions from + modules/registers.xql, which can be customized to reflect differences in the data + coming from external authority and local entry structures. + As mentioned before, location of the registers is determined via $config:register-root variable in config.xqm. + In the same module we will find further customization options related to registers: location of the models for the input forms + (in $config:register-forms) and dedicated configuration for each of the editable register types. + The actual forms themselves are located in templates/pagesannotations as they are effectively + HTML files with embedded Fore form webcomponents. +
+ Register configuration in config.xqm + + + + + +
+ The $config:register-map allows to determine the following information for each registry: + + + id: 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 person registry it is by default set to pb-person which is the @xml:id attribute of the TEI element in + data/registers/persons.xml + <TEI xmlns="http://www.tei-c.org/ns/1.0" xml:id="pb-persons"> + this identifier is always resolved in the context of the $config:register-root variable + to avoid potential conflicts + + + default: identifier by which the default data model for an entry can be accessed; this identifier is always resolved in the context of the $config:register-forms + + + prefix: a prefix for the newly created entries, e.g. a new person will be given an id + like person-00015 or similar, depending how many have been created locally earlier. + + +
+
+
TEI Publisher in production diff --git a/data/doc/register-config.png b/data/doc/register-config.png new file mode 100644 index 00000000..0eb2811c Binary files /dev/null and b/data/doc/register-config.png differ diff --git a/data/doc/register-edit.png b/data/doc/register-edit.png new file mode 100644 index 00000000..970c30a1 Binary files /dev/null and b/data/doc/register-edit.png differ diff --git a/data/doc/register-forms.png b/data/doc/register-forms.png new file mode 100644 index 00000000..c4a584ec Binary files /dev/null and b/data/doc/register-forms.png differ diff --git a/data/doc/register-structure.png b/data/doc/register-structure.png new file mode 100644 index 00000000..4675c8a6 Binary files /dev/null and b/data/doc/register-structure.png differ diff --git a/data/doc/register-templates.png b/data/doc/register-templates.png new file mode 100644 index 00000000..61cae8c1 Binary files /dev/null and b/data/doc/register-templates.png differ diff --git a/data/doc/register-xml.png b/data/doc/register-xml.png new file mode 100644 index 00000000..89d854bf Binary files /dev/null and b/data/doc/register-xml.png differ