Manualetto CDLM

Ultimo aggiornamento: 24 settembre 2005

Premessa

Il manualetto illustra in forma sintetica i criteri di base per l'organizzazione e l'allestimento delle edizioni, la redazione e la marcatura dei testi introduttivi (o di corredo alle edizioni) del Codice diplomatico della Lombardia medievale. A meno di esigenze particolari, da segnalarsi preventivamente a Michele Ansani, è opportuno che i collaboratori si attengano alle indicazioni fornite, allo scopo di produrre contenuti uniformi, facilitare la gestione e la manutenzione del sito, rendere meno dispendiosi i futuri cambiamenti.

1. Struttura del CDLM

2. Struttura delle edizioni

Ogni edizione costituisce una cartella di file, ed è, di regola, composta da cinque testi introduttivi (file HTML) + una sottocartella carte contenente i documenti di cui si fornisce l'edizione (file XML). Eventuali documenti di appendice, numerati autonomamente rispetto all'insieme principale dei documenti dell'edizione, vanno collocati in una sottocartella di pari livello denominata appendice. Ulteriori serie di documenti di appendice vanno collocate in sottocartelle denominate appendice2, appendice3, ecc.

I testi introduttivi sono:

  1. index (= copertina)
  2. introduzione
  3. carte (= indice dei documenti)
  4. archivi
  5. bibliografia

Il file carte viene generato in automatico sulla base dei documenti contenuti nella cartella omonima (ed eventualmente nelle cartelle appendice). Esso rispecchia esattamente la consistenza dell'edizione e l'ordinamento progressivo dei documenti sulla base dell'elemento <NUMERO> dichiarato all'interno di ogni singolo file XML (per ulteriori informazioni sull'elemento <NUMERO> vedi sotto il punto 3.2.2.).

2.1. Nomi di area

Le singole edizioni sono raggruppate per area, in cartelle denominate con la sigla della città 'capoluogo', in lettere minuscole:

2.2. Nomi di edizione

Il nome della cartella edizione, scritto in lettere minuscole, deve essere composto dal toponimo dell'istituzione (eventualmente abbreviato) + il nome abbreviato dell'istituzione stessa, separati da trattino. Esempi:

Nel nome dell'istituzione, "San", "Santo", "Santa" si abbreviano sempre con la s singola e "Santi" con la s doppia, senza separazione dalla parola che segue. Es.: [monastero dei Santi Cosma e Damiano di Brescia] brescia-sscosmadamiano.

In caso di omonimie dentro una cartella (attuali o prevedibili a medio termine), si dà una specificazione, accorpata nel nome se si tratta di istituzioni omogenee (ad es.: lodi-schiaranuova / lodi-schiaravecchia, entrambi monasteri), oppure separata da trattino se si tratta di istituzioni di nome uguale, ma di tipo diverso (ad es.: milano-sambrogio-can [canonica] / milano-sambrogio-mon [monastero]).

In caso di edizioni in più 'volumi', si specifica in fine il numero progressivo. Es. morimondo-smaria1 / morimondo-smaria2.

Per ulteriori esempi vedi l'elenco completo dei nomi delle edizioni pubblicate (o in lavorazione).

2.3. Nomi di file

Nei nomi di file (e nell'elemento <FILE> all'interno dei documenti XML) è tassativamente vietato l'uso di: spazi, apici (singoli ' o doppi "), segni interpuntivi (punti, virgole, ecc.), segni di uguale o parentesi.

Il nome del file è composto di norma dal prefisso letterale identificativo del fondo, seguito dalla data espressa nella forma aaaa-mm-gg ed eventualmente da una lettera maiuscola a seconda della tipologia di tradizione (A per originale, B e C per copia, F per falsificazione, I per imbreviatura, M per minuta, N per notitia, R per regesto). Esempi:

Per comodità di riferimento, si consiglia di scegliere come prefisso identificativo del fondo la forma più breve possibile: può anche essere una parte di parola (es.: morim per le carte di S. Maria di Morimondo) oppure un acronimo (es.: spca per le carte di S. Pietro in Ciel d'Oro di Pavia).

Il prefisso identificativo deve essere univoco all'interno del CDLM; perciò non è possibile scegliere prefissi già utilizzati per altre edizioni. Si veda l'elenco completo dei prefissi utilizzati nelle edizioni attualmente pubblicate (o in lavorazione).

Ad eccezione della lettera indicante la tipologia di tradizione, si consiglia altresì di scrivere il nome tutto in lettere minuscole, sebbene in alcune edizioni già concluse siano state impiegate anche lettere maiuscole (es.: Lomello per S. Maria Maggiore di Lomello).

I documenti di pari data non distinguibili sulla base della tradizione devono essere contrassegnati da una lettera minuscola alla fine del nome. Es.: morim1098-06-00a.xml [Carta venditionis, 1098 giugno, Milano - originale] / morim1098-06-00b.xml [Iudicatum pro anima, 1098 giugno, Milano - originale].

Nel caso di documento 'secondario' (secondo originale, seconda copia, ecc.), si aggiunge in fine al nome un numero, in sostituzione degli apici consueti nella tradizione diplomatistica. Es.: sgiulia1144-11-19aA1.xml [secondo originale], NON sgiulia1144-11-19aA'.xml

3. I documenti XML

All'inizio di ciascun documento XML deve essere scritto il seguente prologo:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE EDITIO SYSTEM "../../../cdlm.dtd">
<?xml-stylesheet href="../../../../stili/cdlm.xsl" type="text/xsl"?>

La prima riga contiene la dichiarazione dello standard XML e del set di caratteri impiegati; la seconda il percorso relativo della DTD; la terza il percorso relativo del foglio di stile XSL, utilizzato per la trasformazione del documento in HTML.

Se in locale si costruisce esattamente la stessa struttura delle cartelle sopra illustrata, è possibile validare il documento XML e visualizzarlo come apparirà su web.

Per la validazione e la visualizzazione si consiglia l'uso del software XMLSPY - Home Edition, di cui si può scaricare una versione gratuita all'indirizzo http://www.xmlspy.com/download_spy_home.html.

3.2. Novità della marcatura

3.2.1. Elemento <REG>

<!ELEMENT REG (#PCDATA | INT | TXT | DOC | REST)*>

Il regesto del documento non va più collocato in un file a parte, ma incorporato nel file XML del documento stesso.
L'elemento, denominato <REG>, va posto all'interno di <INFOED>, tra <DATA> e <APPARATO>.
L'elemento non ha attributi e può contenere al proprio interno gli elementi <INT>, <TXT>, <DOC>, <REST>.

3.2.2. Elemento <NUMERO>

<!ELEMENT NUMERO (#PCDATA)>
<!ATTLIST NUMERO
	lettera CDATA #IMPLIED
	inserto CDATA #IMPLIED
	fp CDATA #IMPLIED
>

L'elemento <NUMERO> contrassegna il numero d'ordine del documento all'interno dell'edizione di cui è parte. Esso identifica univocamente il documento e permette la navigazione sequenziale dentro l'edizione.
La numerazione dell'edizione comincia da 1, tranne nei casi in cui sia progressiva rispetto a un 'volume' precedente (ad es.: morimondo-smaria2).

Il contenuto dell'elemento <NUMERO> deve essere solo ed esclusivamente un numero. Non è ammesso l'uso di lettere o segni interpuntivi (apici, trattini, ecc.).

Per l'elemento sono disponibili tre nuovi attributi opzionali.

L'attributo lettera si compila solo per i documenti 'secondari', NON per il documento 'primario' di pari numero, specificando la sigla che contrassegna la versione. La sigla va digitata esattamente come si vuole che appaia in visualizzazione web (solitamente in lettera maiuscola, con eventuali apici: A', B, ecc.). Si veda, ad es., il seguente caso di una Carta concessionis, dall'edizione di lodi-vescovo:

→ originale
<FILE>vescovile1181-10-22A</FILE> - <NUMERO>147</NUMERO>
→ copia semplice
<FILE>vescovile1181-10-22B</FILE> - <NUMERO lettera="B">147</NUMERO>

I documenti 'secondari' marcati con l'attributo <lettera> non compaiono nell'indice dei documenti e nella navigazione sequenziale. Pertanto, per essere consultabili, essi devono essere linkati dall'apparato del documento 'primario' di cui sono appendice.

L'attributo inserto si compila solo per i documenti 'inserti', specificando la lettera minuscola a. Tali documenti hanno lo stesso numero del documento dopo il quale sono inseriti nel codice. Nel caso di più inserti consecutivi, si adottano lettere minuscole progressive (b, c, ecc.). Si veda, ad es., il seguente caso, dall'edizione di cremona-sicardo:

→ documento n. 62: Notitia pro securitate
<FILE>vescovosicardo0998-01-19</FILE> - <NUMERO>62</NUMERO>
→ inserto dopo il n. 62: Praeceptum Ottonis III imperatoris
<FILE>vescovosicardo0996-08-03</FILE> - <NUMERO inserto="a">62</NUMERO>

I documenti 'inserti' marcati con l'attributo <inserto> compaiono nell'indice dei documenti (e nella navigazione sequenziale), identificati dalla combinazione di numero + lettera dell'inserto.

L'attributo fp si compila per tutti i documenti facenti parte di un'edizione non 'omogenea' (ma con numerazione progressiva), specificando per esteso il fondo di provenienza. Si veda, ad es., il seguente caso ipotetico, ma che si verificherà per l'edizione di bergamo-pergamene2-1:

→ documento n. 1
<FILE>pergbg1100-06-01</FILE> - <NUMERO fp="Bergamo, Biblioteca Civica A. Mai">1</NUMERO>
→ documento n. 45
<FILE>pergbg1050-06-01</FILE> - <NUMERO fp="Bergamo, Archivio Capitolare">45</NUMERO>

In visualizzazione web il fondo di provenienza verrà presentato come intestazione sopra numero, titolo e data del documento.

3.2.3. Elementi eliminati: <DOC-PREC> e <DOC-SUC>

<!ELEMENT INFOED (FILE, AREA, FONDO, NUMERO, TIT-DOC, DATA, REG?,
APPARATO)>

Gli elementi <DOC-PREC> e <DOC-SUC>, che erano obbligatori in ultima posizione dentro l'elemento <INFOED>, sono stati eliminati perché non necessari.

Per i collegamenti tra documenti del CDLM, il percorso dei link (scritto nell'attributo href dell'elemento <DOC>) deve essere espresso sempre in modo relativo. I percorsi relativi si caratterizzano per l'utilizzo della stringa "../", che significa "(vai a) livello superiore". Esempi:

→ link da documento a testo introduttivo
href="../introduzione" (oppure href="../archivi", ecc.)
→ link da documento a altro documento della stessa edizione
href="[nome_file]"
→ link da documento a altro documento della stessa edizione in appendice
href="../appendice/[nome_file]"
→ link da documento a documento di altra edizione nella stessa area
href="../../[nome_edizione]/carte/[nome_file]"
→ link da documento a documento di altra edizione in area diversa
href="../../../[nome_area]/[nome_edizione]/carte/[nome_file]"

Si ricorda che nel percorso del link NON va specificata l'estensione .xml del file di destinazione.

3.3. Marcatura di toponimi e istituzioni ecclesiastiche

Per garantire uniformitā nella marcatura di toponimi e istituzioni ecclesiastiche, occorre attenersi alle norme seguenti, prestando particolare attenzione ai nuovi attributi (opzionali) dell'elemento <TOP>:

<!ELEMENT TOP (#PCDATA | LB | REST | ABBR | NOTA | ELONG | ORIGO |
 DOC | CED)*>
<!ATTLIST TOP
	nm CDATA #REQUIRED
	id CDATA #IMPLIED
	tipo (geografico | territorio) "geografico"
	cert (incerto | non-identificato) "incerto">
→ attributo nm
Il valore dell'attributo (obbligatorio) č la normalizzazione del toponimo a testo.
→ attributo id
Il valore dell'attributo (obbligatorio) č la stringa di identificazione del toponimo a testo.
NB: la proprietà dell'attributo nella DTD rimane per il momento #IMPLIED, per garantire la transizione alla nuova norma ed evitare problemi di validazione su numerosi documenti. Si ribadisce, però, che fin da ora la compilazione dell'attributo č obbligatoria.
→ attributo tipo
Come valore dell'attributo (opzionale) si indica la tipologia del toponimo, se diverso dai toponimi indicanti località. Valori possibili: "territorio" (per regioni o subregioni) / "geografico" (per nomi di elementi geografici, quali fiumi, laghi, monti, ecc.). Non sono ammessi altri valori.
→ attributo cert
Con l'attributo cert (opzionale) si indica il grado di certezza dell'identificazione proposta nell'attributo id. Valori possibili: "incerto" / "non-identificato". Non sono ammessi altri valori.

Per le identificazioni dei toponimi fare riferimento a Theo - Repertorio toponomastico lombardo, all'interno del portale Lombardia Storica.

Per la revisione dei toponimi indicizzati nelle edizioni pregresse fare riferimento alla cartella di tutte le tabelle toponimi (formato .zip, 268 Kb). La cartella contiene 3 tabelle .txt per ogni edizione, relative a toponimi, microtoponimi e istituzioni ecclesiastiche.

Per la migliore visualizzazione delle tabelle si consiglia di:

3.3.1. Toponimi relativi a località

a. Toponimi identificati

La stringa di identificazione da inserire nell'attributo id è composta di 3 parti:

I componenti della stringa devono tassativamente comparire nell'ordine indicato ed essere separati da virgola e spazio.

<TOP nm="Buxinate" id="Bisnate, Zelo Buon Persico, Lo">Buxinati</TOP>

<TOP nm="..." id="Grandola, Grandola ed Uniti, Co">...</TOP>
<TOP nm="..." id="Grona, Grandola ed Uniti, Co">...</TOP>

Nel caso (maggioritario) in cui la denominazione del toponimo coincide con la denominazione del comune amministrativo attuale, non si ripete il nome del comune. Inoltre, la sigla della provincia va sempre indicata anche per i capoluoghi di provincia.

<TOP nm="Roxate" id="Rosate, Mi">Roxate</TOP>
<TOP nm="Brixia" id="Brescia, Bs">Brixie</TOP>

Per le identificazioni fare riferimento a Theo - Repertorio toponomastico lombardo, all'interno del portale Lombardia Storica.

◊ località comprese entro i confini di due o più comuni attuali

All'interno della stringa di identificazione (attributo id), si indica un solo comune, quello prevalente.

<TOP nm="Luzzano" id="Luzzano, Rovescala, Pv">Luzzano</TOP>

L'indicazione degli altri comuni entro i quali il toponimo è compreso va segnalata nella tabella di raccolta dati per Theo - Repertorio toponomastico lombardo.

◊ località scomparse

Anche il nome di una località scomparsa è un toponimo. Nel caso in cui il nome non abbia altri riscontri, all'interno della stringa di identificazione si inserisce la forma normalizzata della località (quindi nella lingua della fonte); nel caso in cui non si possa stabilire con certezza entro quali confini comunali attuali si trovasse, si rientra nella casistica dei toponimi di identificazione incerta o non identificati.

<TOP nm="Murcianum" id="Murcianum, Besate, Mi">Murciano</TOP>

L'indicazione che il toponimo è una "località scomparsa" va segnalata nella tabella di raccolta dati per Theo - Repertorio toponomastico lombardo.

◊ "nucleo antico di"

Anche il nome di un nucleo antico è un toponimo: ci si comporta normalmente.

<TOP nm="Arsana" id="Arsana, Nuvolento, Bs">Arsana</TOP>

L'indicazione che il toponimo è "nucleo antico" di un altro toponimo va segnalata nella tabella di raccolta dati per Theo - Repertorio toponomastico lombardo.

◊ eterodenominazioni

Anche le eterodenominazioni sono toponimi; si utilizzano solo se il toponimo a testo o il contesto le giustifica, e per il resto ci si comporta normalmente.

<TOP nm="Goionum" id="Goglione, Prevalle, Bs">Goioni</TOP>
<TOP nm="Prevalle" id="Prevalle, Bs">Prevalle</TOP>
b. Toponimi di identificazione incerta

In caso di dubbio sull'identificazione del toponimo proposta nell'id, si utilizza l'attributo cert con valore "incerto":

<TOP nm="normalizzazione del toponimo a testo" id="identificazione
del toponimo" cert="incerto">toponimo a testo</TOP>

<TOP nm="Tertiacum" id="Terzago, Trezzano sul Naviglio, Mi"
cert="incerto">Tertiaco</TOP>

In caso di incertezza tra due identificazioni, nell'attributo id se ne dovrà comunque indicare una sola, utilizzando poi l'attributo cert con valore "incerto".

NB: Se necessario le identificazioni alternative possono essere inserite in una nota al documento (all'interno dell'elemento <NOTE>).

c. Toponimi non identificati

Nel caso non si sia in grado di identificare il toponimo, nell'attributo id si ripete la forma normalizzata (nella lingua della fonte) e si utilizza l'attributo cert con valore "non-identificato".

<TOP nm="normalizzazione del toponimo a testo" id="normalizzazione
del toponimo" cert="non-identificato"<toponimo a testo</TOP>

<TOP nm="Gerenzanum" id="Gerenzanum" cert="non-identificato">Gerenzano</TOP>

3.3.2. Toponimi indicanti regioni o sub-regioni

Esempi: Oltrepò, Lomellina, Valsassina, Siccomario, area alessandrina, ecc.

a. Toponimi noti

In questi casi la stringa di identificazione del toponimo è costituita semplicemente dalla denominazione dell'area e si utilizza l'attributo tipo con valore "territorio":

<TOP nm="normalizzazione del toponimo a testo" id="denominazione del
toponimo territoriale" tipo="territorio">toponimo a testo</TOP>

La denominazione del toponimo territoriale č da verificare nell'apposito vocabolario controllato (in corso di allestimento).

<TOP nm="super fluvium Padi" id="Oltrepò pavese" tipo="territorio">super
fluvium Padi</TOP>
b. Toponimi non noti (fuori vocabolario)

Nel caso in cui l'area menzionata non sia inclusa nel vocabolario controllato, nell'id si ripete la normalizzazione del toponimo a testo (in attesa di verifiche):

<TOP nm="normalizzazione del toponimo a testo" id="normalizzazione
del toponimo a testo" tipo="territorio">toponimo a testo</TOP>

3.3.3. Elementi geografici

Sono elementi geografici, ad es., fiumi, laghi, monti, ecc.

a. Elementi noti

In questi casi la stringa di identificazione del toponimo è costituita da "denominazione dell'elemento, tipologia" e viene introdotto l'attributo tipo con valore "geografico":

<TOP nm="normalizzazione del toponimo a testo" id="denominazione
dell'elemento geografico, tipologia" tipo="geografico">toponimo
a testo</TOP>

La denominazione dell'elemento geografico è da verificare nel vocabolario controllato di denominazioni di elementi geografici.

Al momento, le tipologie di elementi geografici consentite sono (in ordine alfabetico):

<TOP nm="Lamber" id="Lambro, fiume" tipo="geografico">Lamber</TOP>
b. Elementi non noti (fuori vocabolario)

Nel caso in cui la denominazione dell'elemento geografico non sia inclusa nel vocabolario, nell'attributo id si ripete la normalizzazione del toponimo a testo (in attesa di verifica), seguita dalla tipologia, aggiungendo sempre l'attributo tipo con valore "geografico".

<TOP nm="normalizzazione del toponimo a testo" id="normalizzazione
del toponimo a testo, tipologia" tipo="geografico">toponimo a testo</TOP>

3.3.4. Microtoponimi

<!ELEMENT MCRTOP (#PCDATA | REST | ABBR | LB | NOTA | PERSONA |
DOC | CED)*>
<!ATTLIST MCRTOP
	nm CDATA #REQUIRED
	top CDATA #REQUIRED
	cert (incerto | non-identificato) "incerto"
>

Salvo casi particolari, in cui i ricercatori riterranno indispensabile per esigenze scientifiche marcare tutti i microtoponimi, si marcheranno solo quelli urbani, indicando la città nell'attributo top.

<MCRTOP nm="normalizzazione del microtoponimo a testo" top="toponimo">
microtoponimo a testo</MCRTOP>

Il valore dell'attributo top va espresso nella forma: "città, sigla della provincia".

<MCRTOP nm="porta de Moirano" top="Vimercate, Mi">in porta de
Moirano</MCRTOP>

<MCRTOP nm="Sanctus Sirus ad Vebriam" top="Milano, Mi">Sancti Sili
ad Vebriam</MCRTOP>

In caso di dubbio sull'identificazione della cittā di riferimento proposta nel top, o di mancata identificazione, si utilizza l'attributo cert con valore "incerto" o "non-identificato".

3.3.5. Istituzioni ecclesiastiche

<!ELEMENT ECCL (#PCDATA | TOP | MCRTOP | LB | REST | ABBR | NOTA |
DOC | CED)*>
<!ATTLIST ECCL
	id CDATA #REQUIRED
	top CDATA #REQUIRED
	cert (incerto | non-identificato) "incerto"
>

La stringa identificativa dell'istituzione (attributo id) è formata dalla denominazione seguita, nel caso sia ricavabile dal testo, dalla tipologia. Nell'attributo top si indica la città.

<ECCL id="denominazione istituzione, tipologia" top="toponimo">
istituzione a testo</ECCL>

Il valore dell'attributo top va espresso nella forma "città, sigla della provincia".

<ECCL id="Ss. Gervasio e Protasio, monastero" top="Poncarale, Bs">
monasterii Sanctorum Martirum Gervasii et Protasii</ECCL>

<ECCL id="S. Maria" top="Brescia">Sanctae Mariae</ECCL>

<ECCL id="S. Pietro in Ciel d'Oro, monastero" top="Pavia, Pv">Sancti
Petri Celo Aureo</ECCL>

In caso di dubbio sull'identificazione della cittā di riferimento proposta nel top, o di mancata identificazione, si utilizza l'attributo cert con valore "incerto" o "non-identificato".

NB: Nel caso si presentassero altri casi particolari non previsti in queste norme, andrà concordata una soluzione con Michele Ansani: la stringa di identifcazione dovrà comunque essere conforme ai criteri indicati.

4. I testi introduttivi HTML

Per agevolare la pubblicazione su web, si richiede agli autori una semplice marcatura HTML dei testi introduttivi: introduzione, archivi e bibliografia. A tale scopo si consiglia di utilizzare un editor testuale (es.: NoteTab) per avere un maggiore controllo delle marcature inserite.

Lo standard di codifica adottato nel CDLM attuale (a cui ci si deve pertanto attenere) è XHTML 1.0, secondo la DTD Strict. XHTML è sostanzialmente «una riformulazione di HTML 4 in XML 1.0» (cfr. http://www.w3c.org/TR/XHTML1/).

Regole principali della sintassi XHTML:

Sarà cura della redazione verificare ed eventualmente correggere i testi marcati dagli autori, nonché provvedere all'impaginazione di elementi speciali come tabelle, elenchi di definizioni o altro, di cui qui sotto non si dà conto. Nel caso di utilizzo di elementi speciali, l'autore deve fornire alla redazione anche un file .doc o .rtf, dove appaia la formattazione desiderata di essi.

4.1. Norme redazionali

Preliminarmente si rammentano alcune basilari norme redazionali, indipendenti dalla marcatura HTML:

  1. i nomi di autori di opere citate si scrivono interamente in lettere MAIUSCOLE;
  2. ai titoli di opere, alle parole straniere e a parole da evidenziare si applica il corsivo;
  3. i titoli di rivista vanno racchiusi tra «virgolette basse»;
  4. le citazioni vanno racchiuse tra «virgolette basse»;
  5. nel rinviare alle pagine di un'opera citata, scrivere i numeri per intero (es.: pp. 112-145, NON 112-45).

In HTML le virgolette basse sono da codificare come entità:

4.2. Marcatura richiesta

Nei file HTML da approntare, NON è necessario scrivere l'intestazione del documento (elementi html e head), né l'elemento body, in quanto il file verrà incluso in un template che già li comprende.

Tuttavia, se si desidera vedere "in anteprima" il documento come apparirā su web, č possibile servirsi di un template per la visualizzazione in locale, contenuto nell'archivio zip cdlm_utils. Prima della consegna del file, ricordarsi di eliminare il codice copiato dal template.

4.2.1. Titoli e sommario

Ciascun file deve cominciare con il titolo, marcato come elemento <h2>.

Se il testo del file introduzione presenta partizioni interne (certamente consigliabili per una migliore fruizione su web, soprattutto per testi molto lunghi), allora ciascuna parte potrà avere un titolo marcato come elemento <h3>.

Nel caso di titoli di livello inferiore (titoli di sezione interna a sezione), si deve utilizzare <h4> e poi, man mano che si scende di livello, <h5> e <h6> (che è l'ultimo livello di titolo consentito).

I titoli possono essere numerati oppure no, a discrezione dei collaboratori.

<h2<Introduzione</h2>

<h3 id="p1">Prima parte</h3>
<p>Paragrafo</p>
<p>Altro paragrafo</p>

<h3 id="p2">Seconda parte</h3>
<p>Paragrafo</p>
<p>Altro paragrafo</p>

<h3 id="p3">Terza parte</h3>
<p>Paragrafo</p>
<p>Altro paragrafo</p>

A ciascun elemento <h3> utilizzato si deve associare l'attributo id, da compilare con la lettera p (= parte) + numero progressivo ("p1", "p2", "p3", ecc.). Gli elementi <h3> vengono utilizzati come voci di sommario, e gli attributi servono come àncore per i link attivati nel sommario.

Il sommario va incluso nell'elemento contenitore <div id="sommario"> e prende la forma di elenco, da marcare come elemento <ul> (= unordered list), oppure <ol> (= ordered list) nel caso di elenco numerato. Ogni voce di elenco è marcata come elemento <li> (= list item).

<div id="sommario">
<ul>
<li><a href="#p1">Prima parte</a></li>
<li><a href="#p2">Seconda parte</a></li>
<li><a href="#p3">Terza parte</a></li>
</ul>
</div>

La gerarchia di titoli illustrata per il file introduzione vale per qualsiasi altro documento HTML, compresi i file archivi e bibliografia, dove però è di impiego più sporadico.

4.2.2. Paragrafi

La maggior parte del testo di introduzione è solitamente costituita da paragrafi. Ciascun paragrafo costituisce un elemento <p>, che appartiene al tipo di elementi detti "a livello del blocco". Nella visualizzazione del file HTML, l'elemento <p> viene presentato su una riga nuova rispetto all'elemento precedente.

L'utilizzo dell'elemento vuoto <br /> per andare a capo è sconsigliato, e non è necessario adottando l'opportuna marcatura per paragrafi.

Per dare evidenza a un insieme di paragrafi, che presenti uno svolgimento del discorso relativamente autonomo rispetto ad insiemi 'limitrofi' e necessiti di uno stacco visivo maggiore, si consigliano le due soluzioni seguenti:

Come esempio cfr. il saggio di Ansani all'indirizzo https://www.lombardiabeniculturali.it/cdlm/progetto/codifica-xml.

4.2.3. Elenchi

Per marcare gli elenchi si utilizza l'elemento <ul> (= unordered list), oppure <ol> (= ordered list) nel caso di elenco numerato. Entrambi i tipi di elenchi sono composti da sequenze di voci, ciascuna marcata con l'elemento <li> (= list item).

I file archivi e bibliografia sono costituiti solitamente da elenchi non ordinati, da marcare rispettivamente come <ul class="archivi> e <ul class="bibliografia">. L'attributo class è necessario per consentire una formattazione 'personalizzata' degli elenchi (gestita tramite fogli di stile CSS) rispetto ad altri elenchi presenti nelle pagine del CDLM.

<h3>Brescia, Archivio di Stato (ASBs)</h3>

<ul class="archivi">
<li>Archivio Storico Civico, <em>Cod. Dipl. di Brescia</em>
(già in Biblioteca Queriniana).</li>
<li>Fondo Religione, Monastero di Santa Maria degli Angeli, buste 101, 102.</li>
<li>Ospedale Maggiore, Abbazia di Rodengo.</li>
</ul>

4.2.4. Elementi di frase

Si presentano qui gli elementi di frase (o "a livello del testo") di impiego più comune nei testi introduttivi:

→ elemento <em>, reso con il corsivo
Indica enfasi, e si applica di norma a parole che si vogliono evidenziare, parole latine o straniere, titoli di opere citate.
→ elemento <strong>, reso con il grassetto
Indica enfasi rafforzata, e si applica a parole o porzioni di frase contenute nel testo che si vogliono rappresentare in grassetto; è di uso sporadico.
→ elemento <sup>, reso con il carattere in apice
Indica che un carattere (solitamente un numero) o una parola debba essere scritto in apice.

Inoltre, è prevista la possibilitè di marcare mediante attributi due tipi speciali di elemento <em>:

→ <em class="spaziato">, reso con lo spaziato
È un tipo di enfasi abbastanza consueto nella tradizione diplomatistica. Si noti che gli spazi tra una lettera e l'altra della parola evidenziata non devono essere digitati: vengono applicati automaticamente con i fogli di stile CSS. Vanno perciò evitate le scritture del tipo: <em class="spaziato">t a b u l a r i u m</em>. La scrittura corretta è: <em class="spaziato">tabularium</em>.
→ <em class="colore">, reso con il colore rosso
Si utilizza quando il discorso richieda una decisa messa in rilievo di una parola o porzione di frase.

L'utilizzo di altre formattazioni speciali č da concordare con la redazione.

4.2.5. Note e link

Le note, solitamente presenti nei testi di introduzione, vanno collocate in fondo al file e numerate progressivamente, in numeri arabi; la numerazione è unica, e continua anche se il testo è suddiviso in più sezioni.

Ciascuna nota costituisce un elemento <p>. L'insieme delle note va racchiuso dentro l'elemento contenitore <div id="note">, e comincia con l'elemento <h3>Note</h3>.

<div id="note">
<h3>Note</h3>
<p>[<a id="fn1" href="#fnref1">1</a>] Testo della nota 1.</p>
<p>[<a id="fn2" href="#fnref2">2</a>] Testo della nota 2.</p>
<p>[<a id="fn3" href="#fnref3">3</a>] Testo della nota 3.</p>
</div>

Sia i rimandi di nota dentro il testo che il numero di nota sono da marcare come àncore, utilizzando l'elemento <a>. Per convenzione il numero di nota si racchiude tra parentesi quadre, esterne rispetto all'elemento <a>.

Per ciascun elemento <a> sono da definire gli attributi id (identificatore univoco dell'àncora) e href (destinazione dell'àncora).

rimando di nota nel testo
<p> ... archivio del cenobio [<a id="fnref5" href="#fn5">5</a>].</p>

nota a piè di pagina
<p>[<a id="fn5" href="#fnref5">5</a>] Testo della nota.</p>

Nel caso del rimando di nota, il valore dell'attributo id è composto dal prefisso fnref più il numero di nota, senza spazi. fnref sta per footnote reference.

Nel caso della nota, il valore dell'attributo id è composto dal prefisso fn più il numero di nota, senza spazi. fn sta per footnote.

Il valore dell'attributo href è sempre composto dal carattere cancelletto # più il nome dell'àncora collegata, senza spazi.

Per i link esterni ai documenti valgono gli stessi criteri illustrati sopra per i link dei documenti XML: percorso relativo, senza estensione, limitatamente ai collegamenti interni al CDLM.

5. Come pubblicare le edizioni

Dopo l'approvazione di Michele Ansani, i materiali di edizione (cartella contenente i file HTML introduzione, archivi, bibliografia, e una o più sottocartelle contenente i file XML) vanno spediti a Cristiano Animosi della cooperativa Codex di Pavia.

I materiali devono essere inviati in forma di un unico archivio zip denominato con il nome stabilito dell'edizione. L'autore deve fornire (anche nel corpo dell'e-mail) il titolo esatto dell'edizione da porre in copertina, completo delle informazioni sull'eventuale edizione a stampa (responsabilità dell'edizione o di singole parti di essa, luogo di pubblicazione, anno, editore, collana, numero della collana)

A riscontro della consistenza dell'edizione (numero e ordine dei documenti, cronologico salvo diversa indicazione), si consiglia di spedire anche l'indice dei documenti, che verrà comunque generato in automatico. Per questo non è richiesta la marcatura HTML (lo si può redigere in formato .doc o .rtf).

Prima dell'invio, occorre verificare:

Entro circa 10 giorni dal ricevimento dei materiali, verrà prodotta la prima bozza dell'edizione (completa dell'indice dei documenti generato in automatico) e saranno fornite tabelle di verifica di toponimi, microtoponimi e istituzioni ecclesiastiche indicizzate più un report dei link interrotti.

Sulla base dell'esame della bozza, l'autore dell'edizione apporterà tutte le correzioni opportune e rispedirà i materiali corretti, dai quali si produrrà la seconda bozza.

Dopo la definitiva approvazione di Michele Ansani, l'edizione sarà pubblicata nel CDLM.

Tale procedura di pubblicazione vale tanto per le edizioni nuove quanto per le edizioni già pubblicate che siano state sottoposte a una revisione sostanziale.

6. Download cdlm_utils

È disponibile per il download un archivio zip, denominato cdlm_utils, contenente tutti i file utili per la validazione e la visualizzazione dei documenti in locale:

La data di aggiornamento dell'archivio (nella forma aaaa-mm-gg) è indicata in fondo al nome dell'archivio stesso in cui i file sono contenuti (es.: cdlm_utils-2005-02-07.zip).

Ultimo aggiornamento: 24 settembre 2005