Newsgroup: it.comp.retrocomputing
Titolo: Archivio Polveroso XML: ultima proposta con istruzioni

Salute a tutti,
  invio quella che per me e` la proposta definitiva per il formato XML
dell'Archivio Polveroso. Le modifiche rispetto la versione precedente sono:
1) aggiunta dell'attributo id per <computer>, <board> e <item>
2) aggiunta del tag <reference> per poter spedire piu` facilmente un <item>
per un <computer> o <board> gia` presenti in archivio. Tale tag non deve
apparire nell'Archivio
3) totale riscrittura delle istruzioni, in formato piu` "tutorial".
--------
Archivio Polveroso: istruzioni per la compilazione dell'XML
-----------------------------------------------------------
0. Premessa
Innanzitutto, per evitare di rifare lavoro gia` svolto da altri, si consiglia 
di scaricare sempre un versione aggiornata del file XML dall'archivio 
centrale prima di effettuare nuovi inserimenti.
Gli inserimenti inoltre vanno spediti da soli e non assieme al resto 
dell'Archivio!
Una definizione basilare: il tag e` 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 e` inteso come un dato sul contenuto del tag (dato sul dato).
Un tag puo` contenere altri tag, come si vedra`.
Queste sono le uniche due forme utilizzate nell'Archivio Polveroso, sebbene 
l'XML ne preveda altre.
Cerchiamo ora di suddividere i vari casi, in modo da dare istruzioni piu` 
dettagiate possibili: potreste infatti voler inserire una scheda informativa 
generica su un modello di computer o di periferica, oppure un un pezzo in 
vostro possesso.
1. Nuova scheda tecnica di...
1.1 ...un computer
Dopo aver verificato che non esista gia` tale scheda in 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 piu` precisa, potete usare il tag 
<computer> in questa maniera piu` 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 e` quella di inserimento) e` 
il 22/4/2001 ed avrete inoltre assegnato con l'attributo id un codice univoco 
alla scheda. Come avrete notato la data e` scritta nel formato 
AnnoMeseGiorno, utilizzando SEMPRE 4 cifre per l'anno, due per il mese e due 
per il giorno: questo e` il formato standard per tutte le date che verranno 
utilizzate nell'Archivio.
Per quanto riguarda l'id, esso e` stato ottenuto unendo un soprannome di chi 
scrive e la data e ora (OreMinutiSecondi) di quando il tag e` stato scritto. 
E` fondamentale che non esistano due id uguali all'interno dell'Archivio!
Gli attributi id e update sono entrambi facoltativi.
A questo punto potreste aver gia` completato la scheda: se non avete altri 
dati potrete semplicemente chiuderla aggiungendo:
 </computer>
La scheda cosi` ottenuta e`:
 <computer update="20010422" id="alhazred20010422234512">
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>
 </computer>
...piuttosto scarna...
Vogliamo aggiungere 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 e` possibile omettere il giorno 
oppure giorno e mese se questi non sono noti, cosi` come esprimere un 
intervallo giustapponendo due date con il - in mezzo.
Aggiungiamo anche 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>
e un paio di link interessanti a riguardo:
  <link src="http://...">Un'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 e` la descrizione del link.
La scheda e` ora ben piu` interessante:
 <computer update="20010422" id="alhazred20010422234512">
  <model>Indigo</model>
  <brand>Silicon Graphics</brand>
  <date>1990-1991</date>
  <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>
  <link src="http://...">Un'interessante pagina informativa</link>
  <link src="http://...">Una bella foto</link>
 </computer>
L'ordine in cui appaiono i tag <date>, <descr>, e <link> non e` importante.
<date> e <descr> sono facoltativi e possono ovviamenta apparire solo una 
volta, <link> e` anch'esso facoltativo, ma puo` apparire piu` volte.
1.2 ...una scheda o periferica
La procedura e` molto simile al caso 1.1: 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; e` facoltativo, anche se 
consigliabile per una piu` veloce categorazzazione.
Anche in questo caso e` possibile essere piu` precisi, specificando:
 <board type="video" update="20010422" id="alhazred20010422234512">
o aggiungendo i tag <date>, <descr> e <link>, esattamente come per <computer>:
 <board type="video" update="20010422" id="alhazred20010422234512">
  <model>LG1</board>
  <brand>Silicon Graphics</brand>
  <date>1990-1991</date>
  <descr>
   Scheda video con accelerazione 2D, 1024x768 8bpp, connettore 13W3 e SVGA
   DB15
  </descr>
  <link src="http://...">Un'interessante pagina informativa</link>
 </board>
Potremmo pero` anche voler specificare che questa scheda e` 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 e` il metodo preferito se la scheda o periferica e` SOLO per un certo 
computer, che esiste nell'Archivio. In caso contrario, si utilizza il tag 
<for>:
 <for>Indigo</for>
 <for>Indigo R4000</for>
che va ripetuto per ciascun computer, quando cio` a senso.
La scheda tecnica diventa quindi:
 <board type="video" update="20010422" id="alhazred20010422234512">
  <model>LG1</board>
  <brand>Silicon Graphics</brand>
  <for>Indigo</for>
  <for>Indigo R4000</for>
  <date>1990-1991</date>
  <descr>
   Scheda video con accelerazione 2D, 1024x768 8bpp, connettore 13W3 e SVGA
   DB15
  </descr>
  <link src="http://...">Un'interessante pagina informativa</link>
 </board>
2. 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 gia`, in caso contrario crearne una, anche 
minima, come da punto 1.
L'oggetto va quindi inserito nella forma:
 <item>
  <owner type="nick">Alhazred</owner>
 </item>
<item> e` il tag che indica un oggetto particolare, posseduto dal 
Retrocomputerista specificato dal tag <owner>. Quest'ultimo puo` 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 valore per type sono: name, email, nick, ICQ.
<owner> e` obbligatorio e deve apparire solo una volta e al primo posto in 
<item>.
Anche per <item> e` possibile specificare data di aggiornamento e id in 
maniera del tutto analoga ai casi del punto 1:
 <item update="20010422" id="alhazred20010422234700">
cosi` 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>
  <date>1992</date>
  <descr>Il mio primo Silicon Graphics!</descr>
  <link src="http://...">Una sua foto</link>
 </item>
Esistono anche alcuni tag specifici: per esempio e` utile indicare quando 
l'oggetto e` stato acquisito dal Retrocomputerista:
 <acquisition>199904</acquisition>
le condizioni in cui l'oggetto si trova:
 <status>Sportello rotto</status>
la sua disponibilita` 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 maccina posseduto:
 <software>IRIX 5.3, NFS, Indigo Magic, IDO</software>
Tutti questi tag sono facoltativi e possono apparire una sola volta in ordine 
qualsiasi.
La scheda risultante sara`:
 <item update="20010422" id="alhazred20010422234700">
  <owner type="nick">Alhazred</owner>
  <date>1992</date>
  <acquisition>199904</acquisition>
  <status>Sportello rotto</status>
  <descr>Il mio primo Silicon Graphics!</descr>
  <avail>Lo regalo al primo che se lo viene a prendere</avail>
  <software>IRIX 5.3, NFS, Indigo Magic, 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>
   <date>1992</date>
   <acquisition>199904</acquisition>
   <status>Sportello rotto</status>
   <descr>Il mio primo Silicon Graphics!</descr>
   <avail>Lo regalo al primo che se lo viene a prendere</avail>
   <software>IRIX 5.3, NFS, Indigo Magic, IDO</software>
   <link src="http://...">Una sua foto</link>
  </item>
 </computer>
Se la scheda tecnica e` gia` 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; e` facoltativo, 
ma fortemente incoraggiato. Tale tag non deve apparire in schede all'interno 
dell'Archivio!
Il dato da inviare sara` quindi:
 <item update="20010422" id="alhazred20010422234700">
  <owner type="nick">Alhazred</owner>
  <reference type="computer" id="alhazred20010422234512">
   Silicon Graphics Indigo
  </reference>
  <date>1992</date>
  <acquisition>199904</acquisition>
  <status>Sportello rotto</status>
  <descr>Il mio primo Silicon Graphics!</descr>
  <avail>Lo regalo al primo che se lo viene a prendere</avail>
  <software>IRIX 5.3, NFS, Indigo Magic, IDO</software>
  <link src="http://...">Una sua foto</link>
 </item>
Il responsabile eliminera` quindi il tag <reference> e inserira` l'<item> nel 
<computer> opportuno.
3. La struttura generale dell'Archivio
L'Archivio Polveroso sara` 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> e` 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 computer SYSTEM "computer.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>
  <board type="video">
   <model>XS</board>
  </board>
  <item>
   <owner type="name">Pico Palla</owner>
  <item>
 </computer>
 <board type="casescsi">
  <model>711</board>
  <brand>Sun</brand>
  <item>
   <owner type="nick">Tizio</owner>
  <item>
  <item>
   <owner type="nick">Anch'io!</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:
 &lt;    <
 &gt;    >
 &quot;  "
 &apos;  '
 &amp;   &
quindi per scrivere:
 <descr>Peso > 250Kg; etichettato "Grande & piu`"</descr>
e` necessario usare la forma:
 <descr>Peso &gt; 250Kg; etichettato &quot;Grande &amp; piu`&quot;</descr>
4. 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 e` 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:    disponibilita` a scambio, vendita, ecc...
status:   stato estetico e di funzionamento
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)
5. Relazioni di annidamento dei tag
archiviopolveroso puo` contenere:
 computer (anche piu` di uno)
 board    (anche piu` di uno)
computer puo` contenere:
 model (obbl.)
 brand (obbl.)
 date
 descr
 link  (anche piu` di uno)
 board (anche piu` di uno)
 item  (anche piu` di uno)
board puo` contenere:
 model (obbl.)
 brand (obbl.)
 date
 descr
 for   (anche piu` di uno)
 link  (anche piu` di uno)
 item  (anche piu` di uno)
item puo` contenere:
 owner (obbl.)
 date
 acquisition
 descr
 avail
 status
 software
 link  (anche piu` di uno)
 reference (SOLO PER L'INVIO DATI!)
6. DTD
<!-- Versione Gamma 20010423 -->
<!-- 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): ATTENZIONE! Solo per l'invio dati! -->
<!ELEMENT reference (#PCDATA)>
 <!-- type: tipo di referenza -->
 <!ATTLIST reference
  type "computer" (computer|board)
  id IDREF #IMPLIED>
<!-- Computer al quale è 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>
<!-- Stato di funzionamento -->
<!ELEMENT status (#PCDATA)>
<!-- Disponibilità 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 | date | acquisition |
    status | avail | descr | 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, ( date | for* | descr | item* | link*))>
 <!-- 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,
   (date | board* | descr | item* | link*))>
 <!-- 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>
<!--
Note:
 1) tutte le date vanno specificate nella forma standard "AnnoMeseGiorno",
 senza spazi e con padding a 0; puo` essere omessa la parte terminale
 ("Giorno" o "MeseGiorno")
 es.: 1991 198303 19710123
 È anche possibile, qualora la data esatta sia incerta, specificare un range
 di tempo nella forma "data_inizio-data_fine"
 es.: 1991-1992
 2) l'id per <computer>, <board> e <item> deve essere univoco, ma non è
 obbligatorio. Una forma ragionevole potrebbe essere del tipo
 NickAnnoMeseGiornoOraMinutiSecondi, come per esempio:
  alhazred20010422234300
 3) sebbene l'indentazione non sia obbligatoria, è meglio utilizzarla per
 una maggiore leggibilità
-->
-----------
Adesso fatene quello che volete!
A risentirci
  Davide G. Borin

 dell'Archivio Polveroso. 
Salvato, appena ho un po' di tempo gli do' un'occhiata e magari faccio
anche qualche prova a leggerlo e scriverlo con PHP :)))
Ma non sara' a breve purtroppo....  :///
Ciao
-Guglielmo Cancelli

   <date>1990-1991</date>
Un momento, generalmente, il trattino indica "durata": "1990-1991" vuol dire
"dal 1990 al 1991", quindi se non lo  ricordiamo con certezza sarebbe meglio
inserire la data nei commenti (o usare un punto interrogativo, cioč
"1990?-1991" per dire "dal 1990, forse, al 1991, sicuramente", ma bisogna
modificare il DTD?)
La spiegazione č comprensibile. Aggiungerei in appendice una scheda "vuota"
per velocizzare la compilazione (ma si rischia l'invio di tag e attributi
vuoti)
<computer update="" id="">
    <model></model>
    <brand></brand>
    <item update="" id="">
        <owner type=""></owner>
        <date></date>
        <acquisition></acquisition>
        <status></status>
        <descr></descr>
        <avail></avail>
        <software></software>
        <link src=""></link>
    </item>
</computer>
E poi un programma in BASIC 8-) che fa le domande del caso e crea il file da
inviare
Ciao,
Daniele

 file da inviare
OK, scrivilo pure! 8-)
A risentirci
\  Davide G. Borin
\\ !!Scudo anti-spam attivo!! Togliere le x e "eliminami" dall'indirizzo
\\\_____________________________________________________________________