Mirabile Digital Library

Come contribuire

MDL accoglie proposte di collaborazione da studiosi e istituzioni esterne. Questa pagina descrive la procedura e mette a disposizione lo schema di codifica TEI adottato dalla biblioteca.

Chi può contribuire

Chiunque curi l'edizione o la descrizione di un testo latino medievale o umanistico: singoli studiosi, gruppi di ricerca, progetti di edizione digitale, biblioteche e archivi. I contributi possono riguardare un testo nuovo, l'aggiornamento di una scheda già pubblicata oppure la segnalazione di errori nei testi esistenti.

La procedura

  1. Proposta. Si scrive alla redazione scientifica di Mirabile (redazione@mirabileweb.it) indicando autore, opera, edizione di riferimento e stato del lavoro. La redazione verifica la pertinenza rispetto al perimetro della biblioteca e conferma la disponibilità dei diritti sul testo.
  2. Codifica. Il testo viene marcato in XML-TEI secondo lo schema MDL descritto qui sotto. Lo schema è volutamente ristretto: ammette solo un sottoinsieme di elementi TEI P5 e vincola i valori di diversi attributi.
  3. Validazione. Il file deve superare senza errori entrambi i livelli di controllo — la grammatica RegoleTEI.rng e le regole RegoleTEI.sch — prima dell'invio. Sono gli stessi controlli che la MDL esegue in fase di importazione.
  4. Invio e revisione. Si inviano i file XML alla redazione. La revisione riguarda sia la correttezza filologica sia la conformità della codifica; possono seguire una o più tornate di correzione.
  5. Pubblicazione. A revisione conclusa il testo viene importato nella MDL e collegato alle schede Mirabile corrispondenti. La paternità del contributo è registrata negli elementi <editor> del <teiHeader>.

Lo schema di codifica

Le regole di codifica della MDL sono definite in un ODD TEI, dal quale sono generati automaticamente i due schemi usati per la validazione. I tre file dicono la stessa cosa, ma servono a scopi diversi.

Se lo schema risulta troppo restrittivo per il testo che si sta codificando — un elemento necessario non è ammesso, un valore di attributo manca dal vocabolario controllato — non va aggirato: si segnala alla redazione, che valuta la modifica dell'ODD e rigenera lo schema.

Associare lo schema al documento

Il modo più comodo è dichiarare entrambi gli schemi nel documento stesso, con due istruzioni di elaborazione <?xml-model?>. oXygen XML Editor le riconosce entrambe e applica i due livelli mentre si scrive; Visual Studio Code (con l'estensione XML di Red Hat), Emacs (nXML) e altri editor usano almeno la grammatica RELAX NG per validazione e completamento automatico. 

<?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"?>

In alternativa si scaricano i due file accanto ai propri documenti e si indica un percorso relativo (ad esempio href="RegoleTEI.rng").

Validare da riga di comando

I due livelli si controllano con due strumenti distinti. Sono gli stessi che usa la MDL, così il risultato in locale coincide con quello che si otterrà all'importazione. 

# 1. grammatica RELAX NG — jing (richiede Java)
jing RegoleTEI.rng documento.xml

# 2. regole sui valori — Schematron (richiede Node.js)
npx -p node-schematron -p slimdom-sax-parser \
    node-schematron RegoleTEI.sch documento.xml

jing non stampa nulla quando il documento è valido; node-schematron stampa pass oppure l'elenco delle asserzioni violate, con il messaggio in italiano previsto dallo schema. Si invia solo dopo che entrambi i comandi sono puliti.

jing si installa con brew install jing-trang su macOS, apt install jing su Debian e derivate, oppure scaricando il jar dal sito del progetto (in quel caso il comando è java -jar jing.jar … e serve una JVM installata). Il secondo pacchetto nel comando npx, slimdom-sax-parser, va indicato esplicitamente: node-schematron lo richiede ma non lo dichiara fra le proprie dipendenze.

Per la grammatica va usato jing, non xmllint: l'implementazione RELAX NG di libxml2 gestisce male interleave e su questo schema respinge documenti perfettamente validi (166 su 419 nel corpus della biblioteca). jing è l'implementazione di riferimento ed è quella che fa fede.

Struttura minima di una scheda

Lo schema impone l'ordine di alcuni blocchi e il valore di alcuni campi editoriali, che sono costanti per tutta la biblioteca. Questo scheletro valida ed è il punto di partenza consigliato: 

<?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">Titolo dell'opera</title>
        <author>
          <persName xml:id="n20689">Nome normalizzato dell'autore</persName>
          <term>Hagiographia</term>
        </author>
      </titleStmt>
      <editionStmt>
        <edition xml:id="n645891">Editio Princeps</edition>
        <editor xml:id="n15472">Cognome, Nome del curatore</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">Riferimento bibliografico</bibl>
        </listBibl>
      </sourceDesc>
    </fileDesc>
    <encodingDesc>
      <p>Criteri di codifica e di trascrizione adottati.</p>
    </encodingDesc>
  </teiHeader>
  <text>
    <body>
      <div>
        <head>Incipit</head>
        <p>
          <app>
            <lem wit="#n99001">lezione a testo</lem>
            <rdg wit="#n99002">variante</rdg>
          </app>
        </p>
      </div>
    </body>
  </text>
</TEI>

Alcuni punti su cui lo schema è severo:

Segnalare un errore

Per refusi, errori di codifica o problemi di visualizzazione in un testo già pubblicato è sufficiente scrivere a redazione@mirabileweb.it indicando l'URL della scheda. Per malfunzionamenti della piattaforma si scrive al supporto tecnico.