How to contribute

MDL welcomes proposals of collaboration from external scholars and institutions. This page describes the procedure and makes available the TEI encoding schema adopted by the library.

Who can contribute

Anyone who edits or describes a medieval or humanist Latin text: individual scholars, research groups, digital edition projects, libraries and archives. Contributions may concern a new text, an update to a record already published, or the reporting of errors in existing texts.

The procedure

Proposal. A proposal is sent to the Mirabile editorial board (redazione@mirabileweb.it) giving the author, the work, the reference edition and the state of progress. The board checks that it falls within the scope of the library and confirms that the rights to the text are available.
Encoding. The text is marked up in XML-TEI according to the MDL schema described below. The schema is deliberately restrictive: it admits only a subset of TEI P5 elements and constrains the values of several attributes.
Validation. The file must pass both levels of checking without errors — the RegoleTEI.rng grammar and the RegoleTEI.sch rules — before it is sent. These are the same checks that MDL runs at import.
Submission and review. The XML files are sent to the editorial board. The review covers both philological accuracy and conformity of the encoding; one or more rounds of correction may follow.
Publication. Once the review is complete the text is imported into MDL and linked to the corresponding Mirabile records. Authorship of the contribution is recorded in the <editor> elements of the <teiHeader>.

The encoding schema

The MDL encoding rules are defined in a TEI ODD, from which the two schemas used for validation are generated automatically. The three files say the same thing, but serve different purposes.

RegoleTEI.odd — the source document. It reads like a manual: every element admitted is accompanied by a description in Italian of its use in MDL and by the list of values allowed for its attributes. It is the reference to consult when a question arises about how to encode something.
RegoleTEI.rng — the executable grammar, generated from the ODD (TEI P5 4.7.0): it establishes which elements and attributes are admitted, and in what order. This is the file to associate with the XML editor.
RegoleTEI.sch — the ISO Schematron rules, that is the constraints on values that a grammar cannot express (for example that <publisher> always reads SISMEL. Edizioni del Galluzzo, or that <date> is a four-digit year). The same rules are embedded in the RNG, but almost no RELAX NG validator applies them: to check them properly, this file and a Schematron engine are required.

If the schema turns out to be too restrictive for the text being encoded — a necessary element is not admitted, an attribute value is missing from the controlled vocabulary — it is not to be worked around: the problem should be reported to the editorial board, which will consider amending the ODD and will regenerate the schema.

Associating the schema with the document

The most convenient way is to declare both schemas in the document itself, with two <?xml-model?> processing instructions. oXygen XML Editor recognises both and applies the two levels as you type; Visual Studio Code (with Red Hat's XML extension), Emacs (nXML) and other editors use at least the RELAX NG grammar for validation and autocompletion.

<?xml-model href="https://www.mirabileweb.it/mdl/schema/RegoleTEI.rng"
            type="application/xml"
            schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="https://www.mirabileweb.it/mdl/schema/RegoleTEI.sch"
            type="application/xml"
            schematypens="http://purl.oclc.org/dsdl/schematron"?>

Alternatively, the two files may be downloaded alongside the documents themselves and a relative path given (for example href="RegoleTEI.rng").

Validating from the command line

The two levels are checked with two separate tools. They are the same ones MDL uses, so the result obtained locally matches the one that will be obtained at import.

# 1. RELAX NG grammar — jing (requires Java)
jing RegoleTEI.rng document.xml

# 2. rules on values — Schematron (requires Node.js)
npx -p node-schematron -p slimdom-sax-parser \
    node-schematron RegoleTEI.sch document.xml

jing prints nothing when the document is valid; node-schematron prints pass or the list of violated assertions, with the message in Italian provided by the schema. The files should be sent only when both commands report no errors.

jing is installed with brew install jing-trang on macOS, apt install jing on Debian and its derivatives, or by downloading the jar from the project site (in which case the command is java -jar jing.jar … and a JVM must be installed). The second package in the npx command, slimdom-sax-parser, has to be named explicitly: node-schematron requires it but does not declare it among its own dependencies.

For the grammar, jing is to be used, not xmllint: libxml2's RELAX NG implementation handles interleave badly and on this schema rejects perfectly valid documents (166 out of 419 in the library's corpus). jing is the reference implementation and is the authoritative one.

The minimum structure of a record

The schema fixes the order of certain blocks and the value of certain editorial fields, which are constant throughout the library. This skeleton validates, and is the recommended starting point:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="https://www.mirabileweb.it/mdl/schema/RegoleTEI.rng"
            type="application/xml"
            schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="https://www.mirabileweb.it/mdl/schema/RegoleTEI.sch"
            type="application/xml"
            schematypens="http://purl.oclc.org/dsdl/schematron"?>
<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title xml:id="n1342">Title of the work</title>
        <author>
          <persName xml:id="n20689">Normalised form of the author's name</persName>
          <term>Hagiographia</term>
        </author>
      </titleStmt>
      <editionStmt>
        <edition xml:id="n645891">Editio Princeps</edition>
        <editor xml:id="n15472">Surname, Forename of the editor</editor>
        <sponsor xml:id="n206">SISMEL</sponsor>
      </editionStmt>
      <publicationStmt>
        <publisher xml:id="n10536">SISMEL. Edizioni del Galluzzo</publisher>
        <pubPlace xml:id="n70">Firenze</pubPlace>
        <date>2018</date>
      </publicationStmt>
      <sourceDesc>
        <listWit ana="descendants of α">
          <witness xml:id="n99001" ana="A" style="blue">
            <msDesc>
              <msIdentifier>
                <msName>Firenze, Biblioteca Medicea Laurenziana, Plut. 12.34</msName>
              </msIdentifier>
            </msDesc>
          </witness>
        </listWit>
        <listBibl>
          <bibl xml:id="n7001">Bibliographical reference</bibl>
        </listBibl>
      </sourceDesc>
    </fileDesc>
    <encodingDesc>
      <p>Encoding and transcription criteria adopted.</p>
    </encodingDesc>
  </teiHeader>
  <text>
    <body>
      <div>
        <head>Incipit</head>
        <p>
          <app>
            <lem wit="#n99001">reading adopted in the text</lem>
            <rdg wit="#n99002">variant</rdg>
          </app>
        </p>
      </div>
    </body>
  </text>
</TEI>

Some points on which the schema is strict:

<publicationStmt> contains exactly publisher, pubPlace, date in that order, with the fixed values SISMEL. Edizioni del Galluzzo, Firenze and a four-digit year.
<editionStmt> contains edition, one or more editor (each with an xml:id) and sponsor, whose content must be SISMEL.
<term> gives the genre and belongs inside <author>, not directly in <titleStmt>. It accepts only the values of the controlled vocabulary (Hagiographia, Carmina, Historia, Sermo…): the full list is in the ODD.
<sourceDesc> requires exactly one <listWit> at the first level: every other witness, families and extra-stemmatic witnesses included, must be nested inside it. <listWit> elements may be nested to represent the stemmatic families, and @ana describes their relationship (for example descendants of α).
The xml:id values of authors, witnesses, editors and bibliographical entries correspond to the Mirabile identifiers: they are what links the TEI record to the rest of the database. If an entity's identifier is not known, it should be requested from the editorial board rather than invented.
xml:lang and xml:space have been removed globally from the schema and must not be used.

Reporting an error

For typographical slips, encoding errors or display problems in a text already published it is enough to write to redazione@mirabileweb.it giving the URL of the record. Malfunctions of the platform should be reported to technical support.