Writing an ODD for the EHRI Online Editions — Specifications and Documentation
In my previous post, I described my method to prepare the writing of the ODD for the EHRI Online Editions. Now that the overview table is complete, the results are ready to be transformed into the final ODD. As a reminder, ODD stands for “One Document Does-it-all” and contains the encoding specifications of the project, as well as its documentation.
Helping the editors with documented encoding guidelines
My first and only experience with writing an ODD prior to the internship was when I wrote one for a school project a few months ago. At the time, I did not know the TEI Guidelines as well as I do now, so this ODD was not exhaustive. But writing the ODD for the EHRI Online Editions means that it should take into account the variety of documents included in the editions and the fact that several encoders have worked and will work on the project.
Establishing ground rules
As I commented the overview table, I realized that many comments I made were pointing out the same issues, which allowed me to consider dedicating a section of the documentation to ground rules.
English as the metadata encoding language
The main ground rule was establishing English as the metadata encoding language. A striking observation was the inconsistency of attributes’ values throughout the editions: sometimes in English, sometimes in German. However, English being considered a universal language, it seemed a better idea to use it as the language for encoding the values of attributes and the metadata (when they are available in English).
Standardization
Standardization is a big part of the documentation. The values for the language attributes, such as @xml:lang, @mainLang or @otherLangs, were inconsistent: for example, the code for German could either be "de", "deu" or "ger". The standardized nomenclature for languages is the ISO 639, but after a discussion with Laurent Romary about which standard should be applied (ISO 639-1 or ISO 639-2), we opted for the Iana Language Subtag Registry, which consists of two-letter codes. Therefore, the standard value for German would be "de".
I also introduced a distinction between the @when and @when-iso attributes. With their current encoding, the EHRI Online Editions only use the @when attribute in the <date> element. The suggested improvement is to use @when-iso if there is a full date (YYYY-MM-DD, e.g. @when-iso="1939-09-01"), and @when in any other case. Indeed, once the transformation of the XML file in TEI Publisher is complete, the date given with @when-iso will be displayed correctly (e.g. "September 1st, 1939"), whereas a full date given with @when will remain in the YYYY-MM-DD format. In addition, using @when-iso with an incomplete date will result in a bug in the application and the inability to display the file.
Reproducing the structure of the facsimile
The purpose of the encoding of archival documents in the context of a digital edition is to be as close as possible to the structure of the facsimile. A very good practice is to systematically have a <div> element in the <body>, corresponding to the transcription or the translation of the document. Inside every <div>, the pages are marked by a <pb/> element, even if there is only one page, and the @facs attribute contains the name of the file for the facsimile page. I also mentioned the encoding of line beginnings with the <lb/> element, which can be completed by the @break attribute to signal whether the line beginning occurs within a word or not.
Structuring the encoding of the metadata
According to the TEI Guidelines’ chapter on the <teiHeader>, the “descriptions and declarations [in the <teiHeader>] provide an electronic analogue to the title page attached to a printed work.” As the information contained in the <teiHeader> do not vary that much from one collection to another, I created a template for encoding the <teiHeader>. In order to do so, I thoroughly consulted the Guidelines to make sure that the template would be as complete as possible.
<teiHeader> templateDealing with different types of documents: encoding the <body>
Openers and closers
If the encoding of the metadata can be summarized in a template, it is far more complicated for the <body> insofar as the different types of documents cannot be encoded in the same way. For example, a testimony will not necessarily require an <opener> and/or a <closer>, whereas it will almost be systematic for a letter or a report:
<opener> elementThe elements of the header can be regrouped in an <opener> element. Institutional stationery has the name of the institution at the top of the page, which corresponds to the <byline> (“primary statement of responsibility given for a work on its title page or at the head or end of the work” in the TEI Guidelines). The <dateline> contains the place and date of writing.
Named entities
As of now, the encoding of the named entities in the EHRI Online Editions consisted of <orgName>, <persName> or <placeName> only. However, in some cases, a place, person or structure is referred to by a noun phrase, which cannot be encoded in the same way:
The TEI Guidelines provide the <rs> element for reference strings. For the reference to be as precise as possible, it should be completed by two attributes:
@typewith a value of either"org","person"or"place";@refwith the identifier of the named entity.
Facilitating the encoding: creation of the schema specifications
Ordering the specifications
A good practice when writing the specifications of an ODD is to order said specifications. The conventional order is the following:
- Mandatory modules (
tei,header,core,textstructure); - Additional modules (any other module used);
- Elements specifications (changes made to the use of elements);
- Attributes classes included in the schema.
Declaring the modules
There are four mandatory modules common to all TEI encodings: tei, header, core and textstructure. The modules are declared in a <moduleRef> element with a @key attribute. Every module contains an important amount of elements, but not all of them are required for an edition, and using a TEI All schema could lead to confusion and inconsistency. In the ODD, it is possible to declare which elements of the module are included or excluded, and a good practice is to not overload the attribute with values. However, I thought it would be more relevant for the editors reading the ODD to see exactly which elements are included.
Establishing the rules: <elementSpec> and Schematron syntax
The modifications made to the use of an element must be declared in the <elementSpec> element. @ident refers to the name of the element, and @mode="change" declares that the element has been modified.
<elementSpec> for the <distinct> elementIn the example above, I have modified the <distinct> element to add a list of suggested values for the @type attribute. First, I defined @type as "required" which means that the encoding will not be valid until the <distinct> element has a @type attribute. Then, I added a semi-open list of values for @type as the only values present in the EHRI collections for now are "camp_language" and "nazi_language". The advantage of using a semi-open list is that the editors can continue to add values as necessary.
It is also possible to determine in which context a specification applies, to declare a pattern or even the type of content for an element with Schematron rules thanks to the <constraintSpec> element.
For example, I have created a rule to make sure that all <pb/> in the <body> take an @n attribute whose value is a positive integer. Schematron requires the use of its own namespace, which needs to be declared in the root element <TEI>. Therefore, the Schematron rules are prefixed by "s:" and the TEI elements within the Schematron rules are prefixed by "tei:".
Schematron relies on the creation of tests to verify the rules. There are two ways of testing a rule: <s:assert> and <s:report>. <s:assert> returns an error message if the tested requirement is not met, whereas <s:report> returns an error message if the tested requirement is met. Thus, with my example, <s:assert> will return an error message if the value for @n is "A".
Testing the schema
Once all the specifications were defined, I generated the RelaxNG validation schema from the ODD. The last step was to test the schema to make sure that all rules were taken into account. To this end I copied an EHRI file, applied the schema and modified the file to make it compliant. Once this was done, I intentionally modified the encoding to invalidate the rules I had created in order to confirm that the schema was functioning properly. Since it does, the schema is now ready to be applied to EHRI files.
Conclusion
I wrote the documentation and specifications contained in the ODD to help the work of the current and future EHRI editors. The ODD is completed by encoding templates, and encoding scripts (to be developed) to facilitate the creation of new editions. As this work is part of the development of a semi-automated editing process for digital scholarly editions, it might also be completed later on by further steps, such as a publication interface.
OpenEdition suggests that you cite this post as follows:
Sarah Bénière (July 28, 2023). Writing an ODD for the EHRI Online Editions — Specifications and Documentation. Digital Intellectuals. Retrieved October 6, 2024 from https://doi.org/10.58079/nmzm
Recent Comments