Scrivere in XML

Istruzioni per i redattori (e gli autori) del
BTFP

Francesca Di
Donato

Copyright © 2004 Francesca Di Donato

(29 marzo 2005)

Sommario

Strumenti

A.
Per scrivere

B.
Per validare

C.
Per trasformare

A.
Appendice. Perché XML?

Struttura
di un file XML- DocBook

Strumenti

A. Per scrivere

Prerequisiti: Per facilitare la scrittura, è necessario scegliere un buon
editor XML. Certamente è possibile scrivere anche con notepad (Blocco note) o
con programmi equivalenti, ma scrivere con un editor xml rende la composizione
di file validi e ben formati più semplice e più rapida.

Per Windows, consiglio NoteTab Light; per Linux, Bluefish e Kate. Se avete particolari
domande su questo, scrivetemi!

1. Intestazione e
dichiarazione

Un documento XML deve avere la seguente intestazione, in cui sono dichiarate
la versione (1.0) e il tipo di codifica (UTF-8).

<?xml version="1.0" encoding="UTF-8"?>

Subito sotto si trova il richiamo alla DTD: nel nostro caso è la seguente

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"/usr/share/sgml/docbook/dtd/xml/4.4/docbookx.dtd">

"/usr/share/sgml/docbook/dtd/xml/4.4/docbookx.dtd" è l'indirizzo locale della
DTD (cioè indica dove si trova sul nostro server). Se volete validare il file
senza doverlo caricare, ma direttamente sul vostro computer, guardate la sezione
B. Per
validare.

2. Come imparare in
fretta

Per capire la struttura di un file XML- Docbook consiglio caldamente la
lettura del Manuale, consultabile gratuitamente on-line, e in particolare dei
capitoli 1 e 2: http://www.docbook.org/tdg/en/html/docbook.html. Nell'Appendice,
trovate un'introduzione agli argomenti del primo capitolo, che forse può esservi
utile.

Non è necessario leggere i paragrafi seguenti: Entities, Making an SGML
Document, Making a DocBook Book, Making a Chapter, Making a Reference Page,
Making Front- and Backmatter. In generale, è sufficiente una lettura veloce del
manuale, in modo da capire le regole principali di codifica.

3. Esempi

Per cominciare, potete provare a scaricare il file di esempio n.1. Apritelo con il browser (non usate IExplorer) e
salvatelo sul vostro hard disk. Apritelo con Blocconote. Si tratta di un file
molto semplice, valido e ben formato. Le parti di testo racchiuse tra tag di
commento (<!-- Commento -->) non sono visibili nell'html, e sono state
inserite per indicare la funzione degli elementi principali. Questo file
contiene gli elementi principali che usiamo (una frazione minima di quelli che
DocBook offre).

Per rispettare la struttura della DTD, è utile consultare l'Element Reference:
http://www.docbook.org/tdg/en/html/part2.html

Di ogni elemento viene indicato il Content Model, cioè la struttura degli
elementi contenuti. La lettura del Content Model è tutt'altro che semplice;
anzi, forse è la parte più difficile dell'opera. Tuttavia è necessaria per
imparare; inoltre, i validatori generalmente mostrano gli errori che abbiamo
commesso riportando parti del Content Model. Per questo, un esempio potrà
rivelarsi utile:

Esempio del Content Model dell'elemento <sect1>:

Per capire il significato di questo terribile elenco, è necessario conoscere
gli operatori di ricorrenza:

?: significa un'unica volta o mai;

+: da 1 a N volte,

*: da 0 a N volte.

Inoltre, il simbolo | significa oppure.

Pertanto, il Content Model di sect1 ci dice che:

l'elemento sectlinfo può comparire all'interno di sect1 una sola volta,
oppure mai;

dev'esserci l'elemento title, mentre subtitle e titleabbrev possono non
esserci, ma se presenti non possono essere più di una volta ciascuno;

toc, lot, etc, possono essere presenti o no, senza un limite quantitativo;

e così via ...

Nello stesso file, inoltre, vengono indicati i "Parent" e "Children" di ogni
elemento, cioè elementi che lo possono contenere ed elementi che possono esservi
contenuti. Infine, in fondo alla pagina è presente un esempio (o un link ad
altre pagine in cui c'è un esempio). Gli esempi sono utilissimi a capire la
funzione e la struttura degli elementi.

Per scrivere i nostri file non è necessaria una comprensione approfondita dei
Content Model, anche perché ci sono già molti modelli disponibili a partire dai
quali è facile produrre file validi e ben formati. Tuttavia la lettura degli
Element Reference può essere utile per rispondere a specifiche esigenze che non
abbiamo soddisfatto nei file presenti sul nostro server, o per capire un errore
nella validazione.

Una guida alla lettura dell'Element Reference è qui:
http://www.docbook.org/tdg/en/html/ref-elements.html.

B. Per validare

Un documento è VALIDO se rispetta le regole di una DTD (o di uno Schema) ed è
BEN FORMATO se conforme alla grammatica di XML.

Esempio 1: un file xml-docbook NON è VALIDO se dopo <sect1> , elemento
che rappresenta l'inizio di una sezione, non è presente l'elemento
<title></title>.

Esempio 2: un file xml NON è BEN FORMATO se manca un tag di chiusura, come in
questo caso: <para

L'uso di un editor XML permette di evitare di fare errori; alcuni editor, in
particolare, consentono la validazione durante la composizione del file

Il programma che usiamo per trasformare i file in html ha anche un
validatore, che restituisce messaggi molto difficili da decifrare. Esistono
tuttavia molti validatori facili da usare. Questo, per esempio, vi permette di
controllare il vostro file via Web: http://www.stg.brown.edu/service/xmlvalid/ (Ma ne trovate a
piacimento, cercando su Google).

Per validare, dovete mettere il link all'indirizzo 'ufficiale' della DTD, cioè
sostituire la dichiarazione che ho indicato in precedenza con questa:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://docbook.org/xml/4.4/docbookx.dtd">

C. Per trasformare

Per l'ultima operazione, usiamo un programma che si trova sul nostro server;
questo ci garantisce che i nostri file abbiano un'interfaccia leggermente
differenziata secondo le sezioni del Bollettino, e che tutti i file di una
sezione abbiamo una grafica identica, senza che dobbiamo preoccuparcene ogni
volta.

Prerequisiti: Mettere nel file XML il riferimento alla dtd giusta, cioè, di
nuovo:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"/usr/share/sgml/docbook/dtd/xml/4.4/docbookx.dtd">

Scaricare winscp o simili (programmi grafici per copiare i file sul server);
scaricare Putty (che serve a connettersi al server in modalità testo).

Caricare il file sul server: Su windows, con winscp (basta metterlo nella
propria home).

Aprire connessione ssh col server (con Putty), digitando il numero del server
(o il nome), preceduto dal vostro nomeutente seguito dalla chiocciola.

a. xml to html

La procedura di trasformazione di un articolo generico è descritta
nell'esempio; "articolo" è un programma che applica i fogli di stile grazie ai
quali produciamo pagine appartenenti alla sezione articoli; per convertire un
testo che sarà pubblicato nella sezione classici, basterà digitare "classici",
al posto di articolo; digitando "articoli_rete" potete trasformare un articolo
per la sezione cultura di rete; "fedro", invece, permette di produrre un
ipertesto per la sezione didattica. Potete anche usare "ovreprocessa", tramite
il quale ho trasformato questa pagina.

Esempio: trasformazione di un articolo generico dall'xml all'html:

Digitare, stando attenti agli spazi

articolo nomefile.xml

Se il file è valido e ben formato, dopo pochi secondi otterrete la seguente
risposta:

nessun errore, il file XML e' valido e ben formato.
vuoi trasformare l' articolo in html (richede un po' di tempo) y/n?

Digitare y e premere invio;

Comparirà la scritta:

inserisci il nome del file di output
(ad esempio nomefile.html)

Digitare:

nomefile.html

Dopo qualche secondo, otterrete la seguente risposta:

File trasformato correttamente.
Per renderlo disponibile sul web spostalo nella directory
/var/www/bfp/articoli con il comando
mv nomefile.html /var/www/bfp/articoli

A quel punto avrete ottenuto il file html; potete spostarlo seguendo
l'indicazione del programma, cioè digitando

mv nomefile.html /var/www/bfp/articoli

Oppure, se avete tenuto aperto anche winscp, provate a ricaricare la vostra
home, sul server: vedrete che nomefile.html è presente; ora lo potete pubblicare
sul bfp (spostandolo in /var/www/bfp/dovevipare....)!

A. Appendice.
Perché XML?

XML (eXtensible Markup
Language) è un linguaggio di marcatura (mark-up) che permette di strutturare
semanticamente un documento senza definire come debba apparire. XML sta
sostituendo HTML come formato per la *produzione* di pagine destinate al
web.

Scrivere in XML presenta diversi vantaggi:

Permette di strutturare un documento e le sue sottoparti; nella pratica,
ciò significa che diviene possibile individuare e linkare (citare) singole
parti di documenti.

Separa la grafica dalla struttura, e permette di pubblicare un documento in
diversi formati (in particolare in pdf e in html) e con diversi layout
grafici, a partire da un unico file.

Tuttavia, la pubblicazione sul web a partire da un file XML è più complessa
di quanto non fosse per chi era abituato all'HTML, perché richiede qualche
passaggio in più: il documento dev'essere validato e poi trasformato in html.

La
prima condizione, cioè la validità di un file, non è necessaria ai fini della
trasformazione; tuttavia, abbiamo deciso di permettere al programma che usiamo
per trasformare i file, di convertirli solo una volta verificatane la validità.
Pubblicare file non validi renderebbe il nostro sistema di archiviazione e di
catalogazione (e anche di selezione) debole. La validazione dell'XML ci permette
inoltre di avere la garanzia di un html anch'esso valido, dunque leggibile da
tutti i browser, anche testuali (di produrre, cioè, testi accessibili a chi
abbia computer obsoleti, e ai portatori di handicap).

Struttura di un file
XML- DocBook

Sostanzialmente, un documento XML si costituisce di tre parti:

Il documento che scriviamo, che termina con l'estensione .xml, in cui sono
presenti i dati, marcati da tag di apertura e di chiusura (elementi e loro
attributi).

Un file in cui viene definita la struttura secondo la quale è stata
dichiarata la marcatura dei dati. Questa dichiarazione può essere espressa
attraverso una DTD (Document Type
Declaration) o attraverso un XML
Schema; in particolare, la DTD attribuisce i nomi e definisce le
regole di combinazione di regole delle varie caratteristiche strutturali e
semantiche che costituiscono un documento; è un dialetto di XML 1
, che sceglie un particolare insieme di caratteristiche del linguaggio.
La DTD che abbiamo prescelto è Docbook 2

Il foglio di stile XSL, un documento che specifica quale formattazione i
dati debbano assumere.

Come indicato nella figura, noi ci occupiamo di scrivere soltanto il primo
documento. Un programma lo trasforma (server-side, cioè sul nostro server) in un
documento HTML (più avanti aggiungerò una sezione anche per la trasformazione
dall'XML al PDF).

[1]
Come esprime il nome stesso, eXtensible Markup Language è un linguaggio
che può essere esteso: vale a dire che chiunque può creare particolari elementi
o attributi. Scegliere una DTD o uno Schema significa, nella pratica, adottare
elementi, attributi e regole per la loro combinazione determinati.

[2]
Perché DocBook? Docbook è una DTD di XML che è stata inventata *per
scrivere* libri e articoli di documentazione del software; in particolare è
usata da The Linux Documentation Project (http://www.tldp.org/authors/) per
produrre e pubblicare la documentazione di Linux, tuttavia il suo uso si sta
estendendo ad altri generi di pubblicazioni scientifiche. La specifica
destinazione di DocBook e la vasta comunità di riferimento hanno determinato la
nostra scelta in suo favore.

This
work is licensed under a Creative
Commons Attribution 2.0 Italy License.