Istruzioni per i redattori (e gli autori) del BTFP
Copyright © 2004 Francesca Di Donato
(29 marzo 2005)
Sommario
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!
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.
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.
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.
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">
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.
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).
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.
