Archivio Polveroso: Guida al formato XML

Introduzione

L'Archivio Polveroso vorrebbe essere un raccoglitore per le schede tecniche dei pezzi posseduti dai Retrocomputeristi, mantenuto da una persona che si preoccuperà di raccogliere i dati, controllarli ed inserirli in un file XML liberalmente scaricabile.

Il formato XML è stato proposto perchè standard, aperto, generabile e visibile con qualsiasi editor ASCII e ricco di software libero per la sua manipolazione. In questa semplice guida non si parlerà realmente di XML, ma dell'implementazione scelta per l'Archivio: maggiori informazioni si possono trovare sul sito del World Wide Web Consortium (W3C).

Una definizione basilare: il tag è un marcatore, un testo che delimita un dato: tutti i tag dell'Archivio Polveroso sono in standard XML, nella forma:

<tag> contenuto (dato) </tag>

oppure

<tag attributo="valore" ...> contenuto </tag>

Un attributo è inteso come un dato sul contenuto del tag (dato sul dato).

Un tag può contenere altri tag, come si vedrà.

Queste sono le uniche due forme utilizzate nell'Archivio Polveroso, sebbene l'XML ne preveda altre.

I dati contenuti nell'Archivo si possono ragguppare in tre categorie:

Vediamo ora, caso per caso, come inserire questi dati nel formato XML dell'Archivio.

Nuova scheda tecnica generale per un modello di computer

Il tag contenitore per tale tipo di scheda è <computer>.

Dopo aver verificato che non esista già la scheda nell'Archivio, procedete con la seguente intestazione, per esempio per un Indigo:

<computer>
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>

Il tag <computer> indica l'inizio di una nuova scheda tecnica per computer. I tag <model> e <brand> indicano rispettivamente il nome del modello e la ditta costruttrice ("marca") del computer in questione; questi due tag vanno sempre inseriti, nell'ordine specificato.

Se volete fare le cose in maniera più precisa, potete usare il tag <computer> in questa maniera più completa ed informativa:

<computer update="20010422" id="alhazred20010422234512">

In questo caso avrete specificato con l'attributo update che la data di ultimo aggiornamento della scheda (che in questo caso è quella di inserimento) è il 22/4/2001 ed avrete inoltre assegnato con l'attributo id un codice univoco alla scheda. Come avrete notato la data è scritta nel formato AnnoMeseGiorno, utilizzando sempre 4 cifre per l'anno, due per il mese e due per il giorno: questo è il formato standard per tutte le date che verranno utilizzate nell'Archivio.

Per quanto riguarda l'id, esso è stato ottenuto unendo un soprannome di chi scrive e la data e ora (OreMinutiSecondi) di quando il tag è stato scritto. Questo formato è solo una proposta, ma è fondamentale che non esistano due id uguali all'interno dell'Archivio!

Gli attributi id e update sono entrambi facoltativi.

L'attributo id (identificativo) è stato introdotto per avere un riferimento rapido e univoco alle varie schede tecniche. Tale identificativo può quindi diventare un codice (primary key) nel caso in cui l'XML venga inserito in un database relazionale, oppure un comodo riferimento nel caso si desideri effettuare un aggiornamento ad una scheda e si debba quindi comunicare al responsabile dell'Archivio a quale scheda ci si riferisce.

A questo punto potreste aver già completato la scheda: se non avete altri dati potrete semplicemente chiuderla aggiungendo:

</computer>

La scheda così ottenuta è:

<computer update="20010422" id="alhazred20010422234512">
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>
</computer>

...piuttosto scarna, ma valida.

Vogliamo aggiungere una breve descrizione:

  <descr>
   CPU MIPS R3000 a 33MHz, RAM proprietaria (da 8 a 96MB), bus GIO-32, SCSI I,
   due seriali RS-232, tastiera e mouse proprietari, audio stereo 16bit con
   DSP 56000 e ingresso/uscita digitale e analogica, tre slot per memorie di
   massa da 3 1/2" con slitta proprietaria
  </descr>

Aggiungiamo anche l'anno di rilascio sul mercato, ma non lo ricordiamo con certezza, dovrebbe essere tra il 1990 e il 1991: aggiungiamo il tag:

  <date>1990-1991</date>

Le date vanno espresse nel solito formato, ma è possibile omettere il giorno oppure giorno e mese se questi non sono noti, così come esprimere un intervallo giustapponendo due date con il - in mezzo.

E infine un paio di link interessanti a riguardo:

  <link src="http://...">Interessante pagina informativa</link>
  <link src="http://...">Una bella foto</link>

In questo caso l'attributo src (obbligatorio) indica l'URL, mentre il contenuto del tag è la descrizione del link.

La scheda è ora ben più interessante:

<computer update="20010422" id="alhazred20010422234512">
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>
  <descr>
   CPU MIPS R3000 a 33MHz, RAM proprietaria (da 8 a 96MB), bus GIO-32, SCSI I,
   due seriali RS-232, tastiera e mouse proprietari, audio stereo 16bit con
   DSP 56001 e ingresso/uscita digitale e analogica, tre slot per memorie di
   massa da 3 1/2" con slitta proprietaria
  </descr>
  <date>1990-1991</date>
  <link src="http://...">Interessante pagina informativa</link>
  <link src="http://...">Una bella foto</link>
</computer>

L'ordine in cui appaiono i tag è importante. <date> e <descr> sono facoltativi e possono ovviamente apparire solo una volta, <link> è anch'esso facoltativo, ma può apparire più volte.

Nuova scheda tecnica generale per una scheda o periferica

La procedura è molto simile al caso precedente, ma il tag contenitore per tale tipo di scheda è questa volta <board>: si inizia con:

<board type="video">
  <model>LG1</board>
  <brand>Silicon Graphics</brand>
</board>

Il tag <board> indica l'inizio di una scheda tecnica per una scheda o periferica, mentre i tag <model> e <brand> hanno lo stesso significato del caso precedente. L'attributo type di <board> indica il tipo di scheda o periferica, in questo caso una scheda video; è facoltativo, anche se consigliabile per una più veloce categorizzazione.

Anche in questo caso è possibile essere più precisi, specificando:

<board type="video" update="20010422" id="alhazred20010422234512">

o aggiungendo i tag <descr>, <date> e <link>, esattamente come per <computer>:

<board type="video" update="20010422" id="alhazred20010422234512">
  <model>LG1</board>
  <brand>Silicon Graphics</brand>
  <descr>
   Scheda video con accelerazione 2D, 1024x768 8bpp, connettore 13W3 e SVGA
   DB15
  </descr>
  <date>1990-1991</date>
  <link src="http://...">Interessante pagina informativa</link>
</board>

Potremmo però anche voler specificare che questa scheda è specifica per l'Indigo: per fare questo potremmo inserire tutto il blocco <board>...</board> dentro la scheda tecnica dell'Indigo, ottenendo:

<computer update="20010422" id="alhazred20010422234512">
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>
  ...
  <board type="video">
   <model>LG1</board>
   <brand>Silicon Graphics</brand>
   ...
  </board>
</computer>

Questo è il metodo preferito se la scheda o periferica è solo per un certo computer, che esiste nell'Archivio. In caso contrario, si utilizza il tag <for>:

  <for>SGI Indigo</for>
  <for>SGI Indigo R4000</for>

che va ripetuto per ciascun computer, quando ciò abbia senso.

La scheda tecnica diventa quindi:

<board type="video" update="20010422" id="alhazred20010422234512">
  <model>LG1</board>
  <brand>Silicon Graphics</brand>
  <for>SGI Indigo</for>
  <for>SGI Indigo R4000</for>
  <descr>
   Scheda video con accelerazione 2D, 1024x768 8bpp, connettore 13W3 e SVGA
   DB15
  </descr>
  <date>1990-1991</date>
  <link src="http://...">Interessante pagina informativa</link>
</board>

Inserire un proprio computer o scheda o periferica

Computer, schede o periferiche intesi come oggetto proprio devono essere presenti nell'Archivio sempre all'interno di una scheda tecnica: verificare quindi se tale scheda esiste già, in caso contrario crearne una, anche minima.

L'oggetto va quindi inserito nella forma:

<item>
  <owner type="nick">Alhazred</owner>
</item>

<item> è il tag che indica un oggetto particolare, posseduto dal Retrocomputerista specificato dal tag <owner>. Quest'ultimo può specificare, come in questo caso, un soprannome, ma anche il nome e cognome, l'indirizzo E-mail, un UIN per ICQ, ecc...: l'attributo type indica proprio questo. Alcuni esempi di type sono: name, email, nick, icquin. <owner> è obbligatorio e deve apparire almeno una volta e al primo posto dentro <item>. Se appare più volte deve avere type diversi e indicherà quindi più dati sul possessore.

Anche per <item> è possibile specificare data di aggiornamento e id in maniera del tutto analoga ai casi del punto 1:

<item update="20010422" id="alhazred20010422234700">

così come la data di acquisto da nuovo, una descrizione e dei link (specifici per l'oggetto in questione!), ottenendo:

<item update="20010422" id="alhazred20010422234700">
  <owner type="nick">Alhazred</owner>
  <descr>Il mio primo Silicon Graphics! Ha lo sportello rotto</descr>
  <date>1992</date>
  <link src="http://...">Una sua foto</link>
</item>

Esistono anche alcuni tag specifici: per esempio è utile indicare quando l'oggetto è stato acquisito dal Retrocomputerista:

  <acquisition>199904</acquisition>

la sua disponibilità per scambio, vendita o che altro:

  <avail>Lo regalo al primo che se lo viene a prendere</avail>

ed infine il software specifico per la macchina posseduto:

  <software>IRIX 5.3, NFS, DSE, IDO</software>

Tutti questi tag sono facoltativi e possono apparire una sola volta in ordine come da esempio seguente.

La scheda risultante sarà:

<item update="20010422" id="alhazred20010422234700">
  <owner type="nick">Alhazred</owner>
  <descr>Il mio primo Silicon Graphics! Ha lo sportello rotto</descr>
  <date>1992</date>
  <acquisition>199904</acquisition>
  <avail>Lo regalo al primo che se lo viene a prendere</avail>
  <software>IRIX 5.3, NFS, DSE, IDO</software>
  <link src="http://...">Una sua foto</link>
</item>

Che inserita nella scheda tecnica dell'Indigo risulta:

<computer update="20010422" id="alhazred20010422234512">
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>
  ...
  <item update="20010422" id="alhazred20010422234700">
   <owner type="nick">Alhazred</owner>
   <descr>Il mio primo Silicon Graphics! Ha lo sportello rotto</descr>
   <date>1992</date>
   <acquisition>199904</acquisition>
   <avail>Lo regalo al primo che se lo viene a prendere</avail>
   <software>IRIX 5.3, NFS, DSE, IDO</software>
   <link src="http://...">Una sua foto</link>
  </item>
</computer>

Se la scheda tecnica è già presente nell'Archivio, per specificarla nell'invio dei dati dell'oggetto al responsabile si utilizza il tag <reference>:

  <reference type="computer" id="alhazred20010422234700">
   Silicon Graphics Indigo
  </reference>

inserendo come contenuto marca e modello e indicando con l'attributo type se si tratta di un computer o una board (default: computer). L'attributo id indica l'id della scheda tecnica alla quale ci si riferisce; è facoltativo, ma fortemente incoraggiato. Tale tag non deve apparire in schede all'interno dell'Archivio!

Il dato da inviare sarà quindi:

<item update="20010422" id="alhazred20010422234700">
  <owner type="nick">Alhazred</owner>
  <reference type="computer" id="alhazred20010422234512">
   Silicon Graphics Indigo
  </reference>
  <descr>Il mio primo Silicon Graphics! Ha lo sportello rotto</descr>
  <date>1992</date>
  <acquisition>199904</acquisition>
  <avail>Lo regalo al primo che se lo viene a prendere</avail>
  <software>IRIX 5.3, NFS, DSE, IDO</software>
  <link src="http://...">Una sua foto</link>
</item>

Il responsabile eliminerà quindi il tag <reference> e inserirà l'<item> nel <computer> opportuno.

Come inviare i dati al responsabile

Se i dati inviati sono schede tecniche generali totalmente nuove, non si pongono particolari problemi: basterà inviare un file di testo (Attenzione! Usare la codifica ISO 8859-1!) contenenti in sequenza le varie schede.

Nel caso di schede di computer posseduti, seguire la procedura indicata nel punto precedente, cioè controllare se esiste la scheda generale nell'Archivio ed in tal caso indicarla con il tag <reference>, altrimenti scrivere anche la scheda generale (almeno minima) ed inviare il tutto.

Il caso delle correzioni o aggiunte è più complesso: per le schede tecniche generali è opportuno indicare l'id o il modello e marca dell'oggetto, mentre per la scheda del pezzo (<item>) va indicato l'id o modello, marca e possessore. A questo punto specificare quali righe sono correzioni e quali aggiunte. Vediamo un esempio:

Aggiungere all'item con id alhazred20010422234700 il seguente link:

 <link src="http://altrosito...">Altra bella foto</link>

e correggere la data di acquisizione in:

 <acquisition>199904-199905</acquisition>

Alternativamente è possibile mandare la nuova scheda per intero, ma così sarà più difficile per il respinsabile effettuare i controlli.

La struttura generale dell'Archivio

L'Archivio Polveroso sarà quindi un file XML, con la seguente struttura:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE computer SYSTEM "computer.dtd">

<archiviopolveroso update="20010422">

...

</archiviopolveroso>

Il tag <archiviopolveroso> è il tag "raccoglitore" che contiene tutto l'archivio. Al suo interno troveremo in sequenza i vari tag <computer> e <board>, nelle varie possibili combinazioni; per esempio:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE archiviopolveroso SYSTEM "archiviopolveroso.dtd">

<archiviopolveroso update="20010422">

<computer update="20010422" id="alhazred20010422234512">
 <model>Indigo</model>
 <brand>Silicon Graphics</brand>
 <board type="video">
  <model>Elan</board>
 </board>
 <board type="video">
  <model>XZ</board>
  <item>
   <owner type="ICQ">123456789</owner>
   <descr>Non funziona</descr>
  <item>
 </board>
</computer>

<board type="video">
 <model>LG1</board>
 <brand>Silicon Graphics</brand>
 <for id="alhazred20010422234512">Silicon Graphics Indigo</for>
 <for id="tix20010311145512">Silicon Graphics Indigo R4000</for>
</board>

<computer id="tix20010311145512">
 <model>Indigo R400</model>
 <brand>Silicon Graphics</brand>
 <item>
  <owner type="name">Pinco Palla</owner>
 <item>
 <board type="video">
  <model>XS</board>
 </board>
</computer>

<board type="casescsi">
 <model>711</board>
 <brand>Sun</brand>
 <item>
  <owner type="nick">Tizio</owner>
 <item>
 <item>
  <owner type="nick">Io pure!</owner>
  <avail>Lo vendo</avail>
 <item>
</board>

</archiviopolveroso>
Per inserire dei commenti estranei alle schede, si usa la speciale forma: 
<!-- Commento -->

Esistono inoltre delle particolari sequenze per rappresentare i caratteri speciali <, >, ", ' e &, che NON POSSONO essere inseriti normalmente, in quanto aventi uno speciale significato in XML:

Codifica XMLCarattere
&lt;<
&gt;>
&quot;"
&apos;'
&amp;&

quindi per scrivere:

<descr>Peso > 250Kg; etichettato "Grande & più"</descr>

è necessario usare la forma:

<descr>Peso &gt; 250Kg; etichettato &quot;Grande &amp; più&quot;</descr>

Elenco dei tag e relativi attributi

archiviopolveroso
contenitore per l'intero Archivio
update
data di ultimo aggiornamento
computer
scheda tecnica di un computer
id
ID univoco
update
data di ultimo aggiornamento
board
scheda tecnica di una scheda o periferica
id
ID univoco
update
data di ultimo aggiornamento
type
tipo
item
un particolare oggetto posseduto
id
ID univoco
update
data di ultimo aggiornamento
descr
descrizione
model
nome del modello
brand
ditta costruttrice, marca
date
data di rilascio (per computer e board), o di acquisto da nuovo (per item)
link
link
src
URL
for
computer al quale è dedicata una scheda o periferica
id
riferimento all'ID del computer
owner
possessore di un oggetto
type
tipo di nome
acquisition
data di acquisizione
avail
disponibilità a scambio, vendita, ecc...
software
software posseduto specifico per l'oggetto
reference
solo per l'invio dati! riferimento di un oggetto alla scheda tecnica
id
riferimento all'ID della scheda tecnica
type
tipo di scheda tecnica (computer o board, default: computer)

Relazioni di annidamento dei tag

archiviopolveroso
Tag contenutoObbligatorioOrdinePiù di uno
computerno-sì
boardno-sì

computer
Tag contenutoObbligatorioOrdinePiù di uno
modelsìIno
brandsìIIno
descrnoIIIno
datenoIVno
linknoVsì
itemnoVIsì
boardnoVIIsì

board
Tag contenutoObbligatorioOrdinePiù di uno
modelsìIno
brandsìIIno
fornoIIIsì
descrnoIVno
datenoVno
linknoVIsì
itemnoVIIsì

item
Tag contenutoObbligatorioOrdinePiù di uno
ownersìIsì
referencenoIIno
descrnoIIIno
datenoIVno
acquisitionnoVno
availnoVIno
softwarenoVIIno
linknoVIIIsì

Elenco dei possibili type di <owner>

Sebbene la DTD permetta l'utilizzo di un testo qualsiasi in tale attributo, è meglio, se possibile, utilizzare uno dei valori seguenti:

name
nome e cognome
address
indirizzo dell'abitazione
nick
soprannome generico
newsnick
soprannome su Usenet ed in particolare su it.comp.retrocomputing
ircnick
soprannome su IRC ed in particolare su #retrocomputing
icquin
UIN su ICQ
email
indirizzo di E-mail preferito
otheremail
altro indirizzo di E-mail (secondario)
url
URL della propria homepage

Elenco dei possibili type di <board>

Sebbene la DTD permetta l'utilizzo di un testo qualsiasi in tale attributo, è meglio, se possibile, utilizzare uno dei valori seguenti:

video
scheda video
audio
scheda audio
cpu
scheda CPU
memory
scheda di memoria RAM/ROM o altro
emulator
scheda emulatrice
serial
scheda seriale (es.: RS-232)
net
scheda di rete (es.: ethernet)
controller
controller, per esempio SCSI, IDE, MFM, GP-IB
analog_io
scheda di Input/Oputput analogico
io
scheda generica di Input/Output
board
scheda generica
unknown_board
scheda sconosciuta
hd
hard disk
floppy
floppy disk drive
cassette
unità a nastro in cassetta (es.: DAT, audio)
tape
unità a nastro in bobine
cdrom
lettore CD-ROM
optic
unità ottica generica
mo
unità magneto-ottica
card
lettore/perforatore di schede
ribbon
lettore/perforatore di nastro perforato
mass_storage
memoria di massa generica
keyboard
tastiera
mouse
mouse
pointer
dispositivo di puntamento diverso dal mouse (es.: trackball, tavoletta grafica)
joystick
joystick
input
dispositivo di input generico
monitor
monitor
terminal
terminale
printer
stampante
plotter
plotter
scanner
scanner
modem
modem
cable
cavo
adapter
adattatore tra connettori di diverso formato
media
supporto vergine per memorie di massa (es.: floppy disk, cassetta per DAT)
case
contenitore per schede o memorie di massa
unknown_periph
periferica sconosciuta
other
quasiasi altra cosa

La DTD

<!-- Versione 1.0 20010521 -->

<!-- Modello (es.: C-64) -->
<!ELEMENT model (#PCDATA)>

<!-- Marca, ditta costruttrice (es.: Commodore) -->
<!ELEMENT brand (#PCDATA)>

<!-- Descrizione di UN link con informazioni relative all'oggetto -->
<!ELEMENT link (#PCDATA)>
 <!-- URI (URL) del link -->
 <!ATTLIST link
  src CDATA #REQUIRED>

<!-- Data di rilascio di un oggetto o di acquisto da nuovo di un'oggetto -->
<!ELEMENT date (#PCDATA)>

<!-- Data di acquisizione di un'oggetto -->
<!ELEMENT acquisition (#PCDATA)>

<!-- Riferimento di un oggetto (item) ad una scheda tecnica
     (computer o board): solo per l'invio dati! -->
<!ELEMENT reference (#PCDATA)>
 <!-- type: tipo di referenza -->
 <!ATTLIST reference
  type (computer|board) "computer"
  id IDREF #IMPLIED>

<!-- Computer al quale e` destinata la periferica o la scheda -->
<!ELEMENT for (#PCDATA)>
 <!ATTLIST for
  id IDREF #IMPLIED>

<!-- Descrizione -->
<!ELEMENT descr (#PCDATA)>

<!-- Proprietario -->
<!ELEMENT owner (#PCDATA)>
 <!-- type: Tipo di nome (es.: nome, nick, e-mail) -->
 <!ATTLIST owner
  type CDATA #IMPLIED>

<!-- Disponibilita` per scambio, vendita o altro -->
<!ELEMENT avail (#PCDATA)>

<!-- Software posseduto -->
<!ELEMENT software (#PCDATA)>

<!-- Il singolo computer o periferica posseduta da un retrocomputerista -->
<!ELEMENT item (owner+, reference?, descr?, date?, acquisition?, avail?,
  software?, link*)>
 <!-- acq: Data di ultimo aggiornamento -->
 <!ATTLIST item
  update CDATA #IMPLIED
  id ID #IMPLIED>

<!-- Periferica o scheda sostituibile, di base o di espansione -->
<!ELEMENT board (model, brand, for*, descr?, date?, link*, item*)>
 <!-- type: Tipo di scheda (es.: audio) -->
 <!-- update: Data di ultimo aggiornamento -->
 <!ATTLIST board
  type CDATA #IMPLIED
  update CDATA #IMPLIED
  id ID #IMPLIED>

<!-- La descrizione generale del computer -->
<!ELEMENT computer (model, brand, descr?, date?, link*, item*, board*)>
 <!-- update: Data di ultimo aggiornamento -->
 <!ATTLIST computer
  update CDATA #IMPLIED
  id ID #IMPLIED>

<!-- Elemento che racchiude tutto, obbligatorio nell'XML -->
<!ELEMENT archiviopolveroso (computer | board)*>
 <!-- update: Data di ultimo aggiornamento -->
 <!ATTLIST archiviopolveroso
  update CDATA #IMPLIED>