XML/DocBook

Obiettivi di apprendimento

• Conoscere le basi di DocBook
• Creare un documento DocBook utilizzando il DTD DocBook
• Convertire un documento di testo in un documento DocBook
• Usare i fogli di stile XSL per trasformare un documento DocBook XML in più formati come diapositive HTML, PDF o di presentazione.

DocBook è un vocabolario XML e SGML particolarmente adatto a libri, articoli e documenti. Ha un definizione (DTD) ampia, potente e di facile comprensione e le sue strutture principali corrispondono all'idea generale di ciò che costituisce un libro. DocBook è però un argomento complesso che non può essere trattato in modo esauriente in poche pagine. Pertanto, ai fini di questo capitolo, parleremo della creazione di un semplice documento DocBook con i principali elementi del DTD DocBook e della pubblicazione del documento, così da dare un'idea di DocBook. Se si desidera approfondire l'argomento, si consiglia di dare un'occhiata ai riferimenti forniti alla fine del capitolo.

Che cos'è DocBook?

• DocBook ti consente di creare e archiviare il contenuto del documento in una forma indipendente rispetto alla presentazione, dedicandosi solo alla struttura logica del contenuto.
• Ha un DTD di facile comprensione e ampiamente utilizzato. I tag DocBook vengono applicati in modo da avere un un nome di "buon senso", facilmente comprensibile per chi conosce l'inglese.
• Al momento non ci sono versioni ufficiali dello schema XML DocBook W3C. Il comitato tecnico di DocBook ha in programma di offrire uno schema ufficiale nel periodo di tempo di DocBook V5.0. Gli esempi forniti in questo capitolo utilizzeranno l'attuale DTD ufficiale.

DTD vs. Schema

Un DTD contiene le dichiarazioni di markup che formano una grammatica per una classe di documenti. Uno schema è un insieme di vocabolari condivisi che consentono alle macchine di eseguire le regole stabilite dai creatori. Fornisce un mezzo per definire la struttura, il contenuto e la semantica dei documenti XML. In sintesi, gli schemi sono un mezzo più ricco e più potente per descrivere le informazioni rispetto ai DTD.

Ecco un semplice documento XML:

<author>
   <firstname>Rusen</firstname>
   <lastname>Gul</lastname>
 </author>

Ecco il DTD per questo documento:

<!ELEMENT author(firstname, lastname)>
<!ELEMENT firstname(#PCDATA)>
<!ELEMENT lastname(#PCDATA)>

Ed ecco lo SCHEMA:

<xs:element name="author">
   <xs:complexType>
*  <xs:sequence>
*    <xs:element name="firstname" type="xs:string"/>
*    <xs:element name="lastname" type="xs:string"/>
*  </xs:sequence>
   </xs:complexType>
</xs:element>

Formati di output per DocBook

I fogli di stile XSL (Extensible Style Language) possono trasformare DocBook XML nei seguenti formati:

• HTML
• HTML Help (per la Guida di Windows)
• Java Help
• XHTML
• XSL Formatting Objects (FO)
• PDF

I fogli di stile DSSSL (Document Style Semantics and Specification Language) possono trasformare DocBook SGML nei seguenti formati:

• HTML
• MIF
• RTF
• TeX

Breve storia

DocBook è stato creato intorno al 1991 da HaL Computer Systems e O'Reilly & Associates. È stato sviluppato principalmente allo scopo di contenere i risultati della conversione troff della documentazione UNIX, in modo che i file possano essere scambiati. Ora è gestito da OASIS. Il sito ufficiale di DocBook è http://www.oasis-open.org/docbook/

Usi

DocBook è utilizzato per:

• libri per la stampa e pubblicazioni commerciali. Molti autori utilizzano DocBook per scrivere libri di ogni tipo, in vari formati di stampa e online, in tutto il mondo;
• articoli e tesi di laurea;
• manutenzione di siti Web;
• produzione di diapositive di presentazione e volantini;
• documentazione per software e hardware commerciale.

Strumenti DocBook

DocBook è ufficialmente disponibile come DTD sia per XML che per SGML. Si può scaricare sia il DTD DocBook XML più recente sia il DTD SGML DocBook dal sito ufficiale DocBook su OASIS. Gli esempi forniti in questo capitolo utilizzeranno il DTD DocBook XML. Alcuni schemi sperimentali di DocBook sono disponibili su sourceforge.net. DocBook è supportato da numerosi strumenti commerciali e open source. Alcuni DocBookStylesheets "standard" facilmente personalizzabili ed estensibili sono disponibili da DocBookOpenRepository insieme ad altri strumenti open source gratuiti. Vedi DocBookTools sul Wiki di DocBook per un elenco più completo di strumenti commerciali e open source.

Altri strumenti gratuiti

• XSLTProc: uno dei processori più conosciuti e veloci
• Apache FOP: implementazione XSL-FO
• Xt: uno dei processori XSLT originali. Usata meno frequentemente ora
• DocBook2x: converte DocBook in pagine man e Texinfo
• Refdb: crea database per riferimenti e bibliografie da DocBook

Strumenti commerciali

• Arbortext Epic: suite completa di strumenti di modifica ed elaborazione
• RenderX XEP: motore di rendering da FO a PDF
• Antenna House XSL Formatter: motore di rendering da FO a PDF

SGML vs XML

La sintassi di SGML e XML DTD è molto simile ma non identica. La più grande differenza tra il DTD DocBook per SGML e quello per XML è che il DTD SGML contiene esclusioni SGML in alcuni modelli di contenuto.

Esempio: SGML DTD esclude <footnote> come discendente di <footnote>, perché non ha molto senso pratico avere delle note che hanno a loro volta della note. I DTD XML non possono contenere esclusioni, quindi se stai utilizzando il DTD XML DocBook, è possibile produrre documenti contenenti alcuni markup validi ma non logici come le note a piè di pagina.

Creazione di un documento DocBook

Per iniziare, avrai bisogno di:

• Un editor XML. Scarica NetBeans IDE se non l'hai ancora fatto.
• Il DTD XML di DocBook. Sebbene sia facoltativo usarne uno, i DTD sono utili quando si desidera convalidare un documento per verificare che sia effetivamente conforme al DTD a cui si fa riferimento. Pertanto, il DTD DocBook può essere utilizzato per convalidare un documento DocBook presunto. DocBook XML 4.2 è la versione corrente di DocBook DTD. Scarica dal sito Web ufficiale di DocBook
• I fogli di stile DocBook XSL sono gestiti principalmente da Norman Walsh. Esistono due set di fogli di stile: XSL e DSSSL
• Un processore XSLT (trattato nelle ulteriori sezioni)

Ecco ora un semplice esempio di libro in DocBook, "book.xml":

 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <book>
  <bookinfo>
   <title>XML – Managing Data Exchange</title>
   <author>
    <firstname>Rusen</firstname>
    <surname>Gul</surname> 
   </author> 
  </bookinfo>
  <chapter> 
   <title>Introduction</title>
   <sect1>
    <title>First Section</title>
    <para>This is a paragraph.</para>
   </sect1>
   <sect1>...</sect1>
  </chapter>
  <chapter>...</chapter>
  <chapter>...</chapter>
  <chapter>...</chapter>
  <appendix>...</appendix>
  <appendix>...</appendix>
 </book>

Un semplice articolo in DocBook, "article.xml"

 <?xml version="1.0"?>
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <article>
  <articleinfo>
   <title>A Simple Approach To DocBook</title>
   <author>
    <firstname>Rusen</firstname> 
    <surname>Gul</surname> 
   </author> 
  </articleinfo>
  <para>This is the introductory paragraph of my article.</para>
  <sect1>
   <title>First Section</title>
   <para>This is a paragraph in the first section.</para>
  <sect2>
   <title>This is the title for section2.</title>
   <para>This is a paragraph in section2.</para>
  </sect2>
  <sect2>...</sect2>
  <sect2>...</sect2>
  </sect1>
  <sect1>This is a high level section</sect1>
  <sect1>...</sect1>
  <sect1>...</sect1>
 </article>

Esaminiamo i dettagli di un documento DocBook. L'intestazione standard di un file XML DocBook è una dichiarazione DocType:

<!DOCTYPE name FORMALID "Owner//Keyword Description//Language">

Questo indica agli strumenti di manipolazione XML il DTD in uso. Name è il nome dell'elemento radice del documento. FORMALID viene sostituito con l'identificatore PUBLIC o SYSTEM o entrambi. PUBLIC identifica il DTD a cui il documento è conforme. SYSTEM esplicita la posizione del DTD utilizzato nel documento mediante un URI (Uniform Resource Indicator). Gli identificatori PUBLIC sono opzionali nei documenti XML sebbene gli identificatori SYSTEM siano obbligatori nella dichiarazione DOCTYPE.

Ecco quindi un altro esempio

 <?xml version="1.0"?>
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

Il codice riporta le seguenti informazioni:

• Proprietario: Oasis
• Descrizione parola chiave: DTD DocBook XML V4.2
• Lingua: EN (inglese)

Attenzione! Se non sei online, devi modificare l'identificatore del sistema URL con il percorso in cui è installato DTD:

 <?xml version="1.0"?>
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "/usr/share/sgml/docbook/xml-dtd-4.2/docbookx.dtd">

Dividere un documento in parti

Prima di iniziare, ecco un suggerimento utile! Per comodità e per migliorare le prestazioni, potresti prendere in considerazione la possibilità di suddividere un documento in blocchi e lavorare su ciascun blocco separatamente. Se hai un libro composto da tre capitoli e due appendici, potresti creare un file chiamato book.xml, che assomiglierà a questo:

 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
 [<!ENTITY chap1 SYSTEM "chap1.xml">
 <!ENTITY chap2 SYSTEM "chap2.xml">
 <!ENTITY chap3 SYSTEM "chap3.xml">
 <!ENTITY appa SYSTEM "appa.xml">
 <!ENTITY appb SYSTEM "appb.xml">]
 <book>
  <title>A Physically Divided Book</title>
  &chap1;
  &chap2;
  &chap3;
  &appa;
  &appb;
 </book>

È quindi possibile scrivere comodamente i capitoli e le appendici in file separati. Ecco perché DocBook è adatto a contenuti di grandi dimensioni. Si noti che questi file separati non hanno e non devono avere dichiarazioni del tipo di documento.

Ad esempio, il capitolo 1 potrebbe iniziare in questo modo:

 <chapter id="ch1">
 <title>My First Chapter</title>
 <para>My first paragraph.</para>
 ...................................

Dividere un documento in parti logiche

Esistono, letteralmente, centinaia di elementi DocBook. Questo è ciò che rende docBook molto potente. Cercheremo di coprire qui quelli principali e di lasciarti esaminare il resto da solo. Gli elementi DocBook possono essere suddivisi in queste categorie:

Set	collezione di libri
Book	libri
Division	divide i libri in parti
Component	divide i libri o le loro parti in capitoli
Section	suddivide le componenti
Meta-information Elements	contiene informazioni sugli altri elementi
Block Elements	hanno effetto a livello di paragrafo
Inline Elements	usati per il markup del testo

Principali elementi di DocBook

Set: una collezione di libri

set è il vertice della gerarchia strutturale di DocBook. Non c'è nulla che contenga un set.

Alcuni elementi secondari sono: Book, SetIndex, SetInfo, Subtitle, Title, TitleAbbrev, ToC (indice).

 <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <set>
  <title>Lord of the Rings</title>
  <setinfo>
   <author>J.R. Tolkien</author>
  </setinfo>
  <book><title>The Fellowship of the Ring</title> ... </book>
  <book><title>The Two Towers</title> ... </book>
  <book><title>Return of the King</title> ... </book>
 <set>

Book: un libro

Book è probabilmente l'elemento di primo livello più comune in un documento. La definizione di DocBook di un libro è molto ampia e generale. Ti dà ampia libertà non imponendo un rigoroso ordinamento di elementi.

Alcuni elementi figli: Appendix, Article, Bibliography, BookInfo, Chapter, Colophon, Dedication, Glossary, Index, LoT, Part, Preface, Reference, SetIndex, Subtitle, Title, TitleAbbrev, ToC.

 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <book>
  <title>XML – Managing Data Exchange</title>
  <titleabbrev>XML</titleabbrev>
  <bookinfo>
   <legalnotice><para>No notice is required.</para></legalnotice>
   <author><firstname>Rusen</firstname><surname>Gul</surname></author>
  </bookinfo>
  <dedication>
   <para>This book is dedicated to MIST 7700 class of 2004 at UGA.</para>
  </dedication>
  <preface>
   <title>Forword</title>
   <para>The book aims to fulfill the need for an introductory XML
   textbook. It contains the basics of XML as well as several tools
   using XML.</para>
   </preface>
  <chapter>
   <title>Introduction</title>
   <para>At least one chapter, reference, part, or article is required.</para>
  </chapter>
  <appendix>
   <title>Optional Appendix</title>
   <para>Appendixes are optional but handy.</para>
  </appendix>
 </book>

Division: una raccolta di parti e riferimenti (opzionale)

Le division sono il primo livello gerarchico al di sotto sotto di book.

Elementi secondari: Part (contiene componenti), Reference (contiene RefEntrys)

Componenti: elementi simili a capitoli di un libro o di una parte

Questi sono Preface, Chapter, Appendix, Glossary, Bibliography e Article. I componenti generalmente contengono elementi a blocchi o sezioni, e alcuni possono contenere componenti di navigazione e RefEntrys.

 <!DOCTYPE bibliography PUBLIC "-//OASIS//DTD DocBook 4.2//EN">
 <bibliography>
  <title>References</title>
  <bibliomixed>
   <bibliomset relation=article>
    <surname>Watson</surname>
    <firstname>Richard</firstname>.
    <title role=article>Managing Global Communities </title>
   </bibliomset>
   <bibliomset relation=journal>
    <title>The World Wide Web Journal</title> 
    <volumenum>2</volumenum>
    <issuenum>1</issuenum>.
    <publishername>O'Reilly &amp; Associates, Inc.</publishername> and
    <corpname>The World Wide Web Consortium</corpname>.
    <pubdate>Winter, 1996</pubdate>
   </bibliomset>.
  </bibliomixed>
 </bibliography>

Sezioni: diversi elementi di sezionamento

Per il sezionamento sono previsti diversi elementi.

1. Sect1 ... Sect5: sono gli elementi di sezionamento più comuni che possono trovarsi nella maggior parte degli elementi a livello di componente. Questi elementi di sezione numerati devono essere nidificati correttamente (Sect2 può trovarsi solo all'interno di Sect1, Sect3 può avvenire solo all'interno di Sect2 e così via).
2. section: un'alternativa alle sezioni numerate. Le sezioni sono ricorsive, quindi è possibile nidificarle a qualsiasi profondità desiderata.
3. SimpleSect: una sezione terminale che può trovarsi a qualsiasi livello. SimpleSect non può avere nessun altro elemento di sezionamento nidificato al suo interno.
4. BridgeHead: un titolo di sezione senza alcuna sezione di contenuto
5. RefSect1 ... RefSect3: elementi di sezione numerati in RefEntrys # GlossDiv, BiblioDiv e IndexDiv: elementi che non prevedono nidificazione

Elementi per meta-informazioni

Tutti gli elementi a livello di sezione e superiori includono un wrapper per meta-informazioni sul contenuto. Esempi di meta-wrapper: BookInfo, ArticleInfo, ChapterInfo, PrefaceInfo, SetInfo, GlossaryInfo.

 <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <bookinfo>
  <title>XML – Managing Data Exchange</title>
  <authorgroup>
   <author>
    <firstname>Richard</firstname>
    <surname>Watson</surname>
   </author>
   <author>
    <firstname>Hendrik</firstname>
    <surname>Fischer</surname>
   </author>
   <author>
    <firstname>Rusen</firstname>
    <surname>Gul</surname>
    <affiliation>
     <orgname>University of Georgia</orgname>
    </affiliation>
   </author>
  </authorgroup>
  <edition>Introduction to XML - Version 1.0 </edition>
  <pubdate>1997</pubdate>
  <copyright>
   <year>1999</year>
   <year>2000</year>
   <year>2001</year>
   <year>2002</year>
   <year>2003</year>
   <holder> O'Reilly &amp; Associates, Inc. </holder>
   </copyright>
   <legalnotice>
     <para>Permission to use, copy, modify and distribute the DocBook 
     DTD and its accompanying documentation for any purpose and without
     fee is hereby granted in perpetuity, provided that the above
     copyright notice and this paragraph appear in all copies.
     </para>
    </legalnotice>
 </bookinfo>

Elementi block vs. inline

Esistono due classi di elementi a livello di paragrafo: block e inline.

Gli elementi a blocchi (block) sono generalmente presentati con un'interruzione di paragrafo prima e dopo di essi. La maggior parte può contenere altri elementi di blocco e molti possono contenere dati di caratteri ed elementi incorporati. Esempi di elementi di blocco sono: paragrafi, elenchi, barre laterali, tabelle e citazioni.

Gli elementi incorporati (inline) sono generalmente rappresentati senza evidenti interruzioni. Il segno distintivo più comune degli elementi incorporati è un cambio di carattere, ma a seconda dei casi potrebbero non presentare alcuna distinzione visiva. Gli elementi incorporati contengono dati carattere e possibilmente altri elementi incorporati, ma non contengono mai elementi blocco. Sono utilizzati per contrassegnare i dati. Alcuni esempi sono: riferimenti incrociati, nomi di file, comandi, opzioni, pedici e apici e termini di glossario.

Elementi a blocchi

Gli elementi block si trovano immediatamente sotto il componente e gli elementi di sezionamento.

CalloutList	Un elenco di segni, spesso numerati e generalmente messi in un ambiente grafico o testuale con le relative descrizioni
GlossList	Un elenco di termini del glossario e le relative definizioni
ItemizedList	Un elenco non ordinato (puntato)
OrderedList	Un elenco numerato
SegmentedList	Un insieme ripetuto di elementi con nome. Ad esempio, un elenco di stati e le loro capitali potrebbe essere rappresentato come un SegmentedList
SimpleList	Un elenco di elementi senza punti o numeri
VariableList	Un elenco di termini e definizioni o descrizioni

Ecco un esempio SegmentedList, "statecapital.xml":

 <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <para>The capitals of the states of the United States of America are:
  <segmentedlist>
   <title>State Capitals</title>
   <segtitle>State</segtitle>
   <segtitle>Capital</segtitle>
   <seglistitem>
    <seg>Georgia</seg>
    <seg>Atlanta</seg>
   </seglistitem>
   <seglistitem>
    <seg>Alaska</seg>
    <seg>Juneau</seg>
   </seglistitem>
   <seglistitem>
    <seg>Arkansas</seg>
    <seg>Little Rock</seg>
   </seglistitem>
  </segmentedlist>
 </para>

L'output di "statecapital.xml":

Le capitali degli stati degli Stati Uniti d'America sono:
Capitali di stato
Stato: Georgia
Capitale: Atlanta
Stato: Alaska
Capitale: Juneau
Stato: Arkansas
Capitale: Little Rock

Qui invece un esempio con <orderedlist>, "mashpotatoe.xml"

 <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <para>
  <orderedlist numeration="upperroman">
   <listitem>
    <para>Preparation</para>
    <orderedlist numeration="upperalpha">
     <listitem><para>Chop tomatoes</para>
     </listitem>
     <listitem><para>Peel onions</para>
     </listitem>
     <listitem><para>Mash potatoes</para>
     </listitem>
    </orderedlist>
   </listitem>
   <listitem>
    <para>Cooking</para>
    <orderedlist numeration="upperalpha">
     <listitem><para>Boil water</para>
     </listitem>
      <listitem><para>Put tomatoes and onions in </para></listitem>
      <listitem><para>Blanch for 5 minutes</para>
     </listitem>
    </orderedlist>
   </listitem>
  </orderedlist>
 </para>

L'ouput di "mashpotatoe.xml" sarà

---

I.Preparation
    A.Chop tomatoes
    B.Peel onions
    C.Mash potatoes
II.Cooking
    A.Boil water
    B.Put tomatoes and onions in
    C.Blanch for 5 minutes

---

Avvisi

Esistono cinque tipi di avvisi: Caution, Important, Note, Tip e Warning.

<small>Table 15: <caution> element, "caution.xml"</small>
 <!DOCTYPE caution PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <caution>
  <title>This is a caution</title>
  <para>Be careful while opening the box!</para>
 </caution>

Ambienti specifici per linea

Gli ambienti specifici per linea preservano spazi bianchi e interruzioni di linea.

Address	Un indirizzo nel mondo reale, generalmente un indirizzo postale
LiteralLayout	Un blocco di testo in cui le interruzioni di riga e lo spazio bianco devono essere riprodotti fedelmente
ProgramListing	Un elenco letterale di tutto o parte di un programma
Screen	Testo che un utente vede o potrebbe vedere sullo schermo di un computer
ScreenShot	Una rappresentazione di ciò che l'utente vede o potrebbe vedere sullo schermo di un computer
Synopsis	Un elemento generico per rappresentare la sintassi di comandi o funzioni

 <!DOCTYPE blockquote PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <blockquote>
  <attribution>Rudyard Kipling,
   <citetitle>If</citetitle>
  </attribution>
  <literallayout>
      If you can force your heart and nerve and sinew
 To serve your turn long after they are gone,
 And so hold on when is nothing in you
 Except the Will
 which says to them:
      Hold on!
  </literallayout>
 </blockquote>

Elementi comuni a livello di blocco

Gli elementi comuni a livello di blocco includono esempi, figure e tabelle. La distinzione tra elementi formali e informali è che gli elementi formali hanno titoli mentre quelli informali no.

Example, InformalExample

 <!DOCTYPE example PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <example>
  <title>Sample code</title>
  <programlisting>print "Hello, world!"</programlisting>
 </example>

Figure, InformalFigure

 <!DOCTYPE figure PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <figure>
  <title>Revenues for Q1</title>
  <mediaobject>
   <imageobject>
    <imagedata fileref="q1revenue.jpg" format="JPG"/>
   </imageobject>
  </mediaobject>
 </figure>

Table, InformalTable

<!DOCTYPE table PUBLIC "-//OASIS//DTD DocBook V4.2//EN"><br>
<table frame="frametype">
 <title>frame="frametype"</title>
 <tgroup cols="1">
  <thead>
   <row>
    <entry>row 1, cell 1</entry>
    <entry>row 1, cell 2</entry>
    <entry>row 1, cell 3</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>row 2, cell 1</entry>
    <entry>row 2, cell 2</entry>
    <entry>row 3, cell 3</entry>
   </row>
  </tbody>
 </tgroup>
</table>

Paragrafi

I paragrafi sono Para, SimPara (i paragrafi semplici non possono contenere altri elementi a livello di blocco) e FormalPara (i paragrafi formali hanno titoli). I paragrafi sono gli elementi di alto livello più comunemente usati che possono contenere elementi a blocchi come itemizedlist e Mediaobject e possono contenere quasi tutti gli elementi incorporati.

<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
<para> 
 <quote>Behold the superfluous. They are always sick. They vomit their gall and call it a newspaper.</quote> 
 -Friedrich Wilhelm Nietzsche,  
 <citetitle>Twilight of the Idols</citetitle> 
</para>

Equazioni

Equation e InformalEquation (senza titoli)

<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> <para>
  The equation
  <informalequation>
   <alt>e^(pi*i) + 1 = 0</alt>
   <graphic fileref="figures/epi10"></graphic>
  </informalequation>
is delightful because it joins together five of the most important mathematical constants.
</para>

Grafica

InlineGraphic, MediaObject, InlineMediaObject: questi elementi possono contenere dati video, audio, di immagine e di testo. Un singolo oggetto multimediale può contenere diverse forme alternative da cui il sistema di presentazione può selezionare l'oggetto più appropriato.

Elementi incorporati

Nei documenti pubblicati, gli elementi in linea spesso causano una modifica del carattere o altre piccole modifiche, ma non provocano interruzioni di riga o di paragrafo.

Abbrev	Un'abbreviazione, in particolare se seguita da un punto
Acronym	Una parola composta dalle lettere iniziali (o selezionate) di un nome o una frase
Emphasis	Testo enfatizzato
Footnote	Una nota a piè di pagina; la posizione di Footnote identifica la posizione del primo riferimento alla nota a piè di pagina. Ulteriori riferimenti alla stessa nota a piè di pagina possono essere inseriti con FootnoteRef
Phrase	Uno stralcio di testo
Quote	Una citazione in linea
Trademark	Un marchio
Citation	Un riferimento bibliografico in linea ad un'altra opera pubblicata
GlossTerm	Un termine di glossario
Link	Un collegamento ipertestuale
ULink	Un collegamento che contiene l'indirizzo del suo oggetto tramite un URL (Uniform Resource Locator)
XRef	Un riferimento incrociato a un'altra parte del documento
ForeignPhrase	Una parola o frase in una lingua diversa dalla lingua principale del documento
ComputerOutput	Dati, generalmente di testo, visualizzati o presentati da un computer
Markup	Una stringa di markup di formattazione nel testo che deve essere rappresentata alla lettera
Replaceable	Contenuto che può o deve essere sostituito dall'utente
UserInput	Dati inseriti dall'utente
Literal	Testo incorporato che ha un valore letterale
Command	Il nome di un programma eseguibile o di un altro comando software
MsgText	Il testo effettivo di un componente del messaggio in un set di messaggi
Optional	Informazioni opzionali
Email	Un indirizzo email
Database	Il nome di un database o di una parte di un database
Filename	Il nome di un file
Token	Un'unità di informazioni
Type	La classificazione di un valore
Application	Il nome di un programma software

Le seguenti entità sono usate per caratteri speciali:

Carattere	Entità
<	& lt;
>	& gt;
&	& amp;
"	& quot;
'	'

Pubblicazione di un documento DocBook

Il Document Style Semantics and Specification Language (DSSSL) è un linguaggio per fogli di stile destinato sia per la stampa che per il rendering online. È principalmente destinato a funzionare con SGML.

L'Extensible Stylesheet Language (XSL) è un linguaggio per fogli di stile scritti in XML. Include il linguaggio dell'oggetto da formattare, ma fa riferimento a documenti separati per il linguaggio di trasformazione e il linguaggio del percorso. In questo capitolo utilizzeremo i fogli di stile XSL perché sono più potenti, sono già stati descritti in un modulo precedente e sono pensati per funzionare con XML.

Fase 1: procurati i fogli di stile standard

DocBook separa rigorosamente il contenuto e l'aspetto di un documento. Un documento DocBook spiega solo la semantica del documento, non la sua formattazione o il suo aspetto. Per pubblicare il tuo documento DocBook, dovrai utilizzare una serie di fogli di stile DSSSL o XSL che descrivono la formattazione e un processore XSL.

Se stai pensando che sarebbe molto difficile scrivere i tuoi fogli di stile XSL, hai ragione. La buona notizia è che non è necessario. Esistono molti fogli di stile XSL standard disponibili gratuitamente per DocBook gestiti principalmente da Norman Walsh.

Assicurati di scaricare l'ultima versione di questi fogli di stile su Sourceforge.net. La distribuzione del foglio di stile consiste in una raccolta di file XSL modulari che sono assemblati in diversi fogli di stile XSL completi. Esiste un foglio di stile per la generazione di un singolo file HTML e uno per la generazione di più file HTML più piccoli da un singolo documento DocBook. Esistono fogli di stile per l'output di stampa, l'output XHTML, l'output della HTML Help e l'output JavaHelp. Poiché esistono processori XSL per tutti i principali tipi di computer, è possibile utilizzare DocBook su computer Unix, Linux, Windows e Macintosh. Usando questi fogli di stile predefiniti installati sul tuo sistema, è abbastanza facile creare fogli di stile personalizzati. Ma non dimenticare di notare che l'approccio comune per personalizzare i fogli di stile consiste nel creare un livello di personalizzazione anziché modificarli direttamente.

Fase 2: scarica un processore XSLT

Per pubblicare HTML dai tuoi documenti XML, avrai bisogno di un motore XSLT. Per stampare, è necessario un motore XSLT per produrre oggetti di formattazione (FO), che devono quindi essere elaborati con un motore FO per produrre output PostScript o PDF. Sono disponibili vari motori XSLT. Ecco un elenco di alcuni gratuiti / open-source che potresti prendere in considerazione. Nota che xsltproc e Saxon sono attualmente gli unici motori XSLT consigliati per l'uso con DocBook.

Motori XSLT

• Xsltproc: un processore gratuito scritto in C, disponibile come parte della libreria open source libxml2 dal progetto di sviluppo di Gnome. È considerato il più veloce tra i processori ed è altamente conforme alle specifiche.
• Saxon: un processore gratuito scritto in Java, che può essere eseguito su qualsiasi sistema operativo con un moderno interprete Java. Utilizza internamente il parser Aelfred XML, che presenta alcuni bug, quindi molte persone sostituiscono il parser Xerces.
• Xalan: Xalan fa parte del progetto Apache XML. Ha versioni scritte sia in Java che in C++, entrambe gratuite. La versione Java è altamente portatile e maggiormente sviluppata. Generalmente Xalan viene utilizzato con il parser XML Xerces (Java o C++), disponibile anche dal progetto XML Apache.

La scelta del motore XSLT può dipendere molto dall'ambiente in cui verrà eseguito il motore. Molti utenti di DocBook che necessitano o desiderano un'applicazione non Java utilizzano xsltproc. È molto veloce e i suoi sviluppatori rispondono molto rapidamente a segnalazioni di bug e domande. Ma una delle attuali limitazioni di xsltproc è che non supporta ancora le funzioni di estensione XSLT specifiche per DocBook di Norm Walsh.

Saxon è il più popolare per l'uso in un ambiente Java. Supporta anche le funzioni di estensione XSLT specifiche per DocBook di Norm Walsh.

NetBeans IDE ha un processore XSLT integrato che utilizza il parser XALAN per impostazione predefinita. NetBeans IDE non solo ti consente di convalidare i tuoi documenti XML, ma esegue anche le trasformazioni XSL proprio nell'IDE. Tuttavia, non fornisce alcun debug XSLT, quindi potresti voler ottenere un IDE XSL decente (ad esempio, XML Spy o Xcelerator) per un serio lavoro XSLT.

Motori FO

Per generare output di stampa/PDF da file FO, esistono due motori FO liberi e/o open source:

• PassiveTeX
• FOP: un processore basato su Java del progetto Apache XML

Fase 3: personalizza i fogli di stile XSL

Output in HTML

• Il punto di forza dei fogli di stile standard è che sono facilmente personalizzabili.
• I parametri si trovano in params.xsl
• Richiama il tuo layer personalizzato anziché il foglio di stile standard

Un esempio di foglio di stile XSL personalizzato, "myxsl1.xsl"

 <?xml version="1.0"?>
   <!-- Customization layer -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <nowiki><!-- Use 'chunk.xsl' in line below to chunk files. --></nowiki>
 <xsl:import href="/usr/share/sgml/docbook/docbook-xsl-1.51.1/html/docbook.xsl"/>
 <xsl:param name="chapter.autolabel" select="1"/>
 <xsl:param name="section.autolabel" select="1"/>
 <xsl:param name="section.label.includes.component.label" select="1"
 doc:type="boolean"/>
   <!-- Insert more parameters here. -->
 </xsl:stylesheet>

• Oltre all'impostazione dei parametri, è possibile modificare i "modelli" XSLT per sovrascrivere un comportamento predefinito
• È necessaria almeno una conoscenza minima di XSLT

Secondo esempio di foglio di stile XSL personalizzato, "myxsl2.xsl"

 <xsl:template match="emphasis">
 <xsl:choose>
 <xsl:when test="(@role='strong') or (@role='bold')">
   <xsl:call-template name="inline.boldseq"/>
 </xsl:when>
 <xsl:otherwise>
   <xsl:call-template name="inline.italicseq"/>
 </xsl:otherwise>
 </xsl:choose>
 </xsl:template>

Output in PDF

In genere richiede un processo in due fasi:

1. Generazione di FO da XML
2. Generazione di PDF da FO

Questo è un foglio di stile XSL per generare FO, "myxsl3.xsl":

  xsltproc -o sample.fo $ DB / fo / docbook.xsl sample.xml
 fop.sh -fo sample.fo -pdf sample.pdf

Estensioni per slide

• Creazione di diapositive per presentazioni da DocBook XML
• È possibile creare HTML (con o senza frame) e FO
• Utilizza gli elementi DocBook all'interno di una specifica struttura gerarchica
• Scaricabile da DocBook Open Repository su SourceForge

<!DOCTYPE slides SYSTEM "/usr/share/sgml/docbook/xsl-slides-1.1/slides.dtd">
<slides>
 <slidesinfo>
  <title>A Simple Approach to DocBook</title>
 </slidesinfo>
 <foil>
  <title>My first slide</title>
  <itemizedlist>
   <listitem><para>...</para></listitem>
   <listitem><para>...</para></listitem>
   <listitem><para>...</para></listitem>
  </itemizedlist>
 </foil>
 <foil>
  <title>My second slide</title>
  <para>... </para>
 </foil>
</slides>

Estensioni per siti web

• Creazione di siti Web da una raccolta di file XML DocBook
• Utilizza la maggior parte degli elementi di DocBook in un framework specifico. Ha file separati che controllano la navigazione e la gerarchia delle pagine.
• Scaricabile da DocBook Open Repository su SourceForge.

<!DOCTYPE webpage SYSTEM "../website.dtd" [
<!NOTATION XML SYSTEM "xml">
<!ENTITY test1a SYSTEM "test1a.xml" NDATA XML>
<!ENTITY test3 SYSTEM "test3.xml" NDATA XML>
<!ENTITY about.xml SYSTEM "about.xml" NDATA XML>]>
<webpage id="home">
    <config param="desc" value="The Test Home Page"/>
    <config param="rcsdate" value="$Date: 2001/11/08 20:44:20 $"/>
    <config param="footer" value="about.html" altval="About..."/>
    <head>
        <title>Welcome to Website</title>
        <summary>Introduction</summary>
        <keywords>Rusen Gul, XSL, XML, DocBook, Website</keywords>
    </head>
    <para> This website demonstrates the DocBook.</para>
   <webtoc/>
        <section>
            <title>What is a Website?</title>
               <para>A website is a collection of pages organized, for the purposes of navigation, into one or more hierarchies. In Website, each page is a separate XML document authored according to the Website DTD, a customization of <ulink url="http://www.oasis-open.org/docbook/">DocBook</ulink>.</para>
        </section>
</webpage>

Perché usare DocBook?

Quello descritto sembra certamente un lavoro enorme, no? Non hai torto. Perché allora ci prendiamo la briga di usare DocBook?

• È portatile! Un documento scritto con il markup DocBook può essere facilmente e rapidamente convertito in HTML, PostScript, PDF, RTF, DVI, ASCII, il tutto senza ricorrere a strumenti costosi.
• È flessibile! Consente l'output in più formati, tra cui HTML, PDF, presentazioni e molti altri.
• Separa il contenuto dall'aspetto! DocBook si occupa solo della struttura di un documento. Libera l'autore dal preoccuparsi della formattazione e del layout di un documento.
• È facile da capire! La maggior parte degli elementi di DocBook si spiega da sé.
• Può gestire grandi quantità di contenuto. Puoi dividere fisicamente il documento in diversi file e lavorarci separatamente e comodamente.
• È gratis! Ci sono molti strumenti open source disponibili gratuitamente per lavorare con DocBook.

DocBook è adatto a qualsiasi raccolta di documentazione tecnica che viene regolarmente mantenuta e pubblicata. Più autori possono contribuire a un singolo documento e il loro contenuto può essere facilmente unito perché tutti gli autori utilizzano un linguaggio di markup standard altamente strutturato. C'è solo un piccolo punto da tenere a mente: poiché la formattazione per i documenti DocBook è rigorosamente realizzata da fogli di stile, DocBook non è adatto a contenuti strettamente collegati al loro layout, come per esempio gli articoli delle riviste.

La configurazione di un sistema DocBook richiederà sicuramente tempo e fatica. Il risultato sarà un sistema di pubblicazione efficiente, flessibile e poco costoso, che è iterativo e che può crescere con le tue esigenze. Pertanto, ne vale la pena!

Collegamenti esterni

• DocBook Official Website
• DocBook: The Definitive Guide, by Norman Walsh and Leonard Muellner, published by O'Reilly & Associates, October 1999 http://www.docbook.org/
• Sourceforge - DocBook Open Repository
• Installing and Using DocBook - Copyright 2002, The University Of Birmingham
• Using the DocBook XSL Stylesheets - http://www.sagehill.net/docbookxsl/index.html
• Setting Up A Free XML/SGML DocBook Editing Suite For Windows And Unix
• http://lists.oasis-open.org/archives/docbook-apps/
• http://www.dulug.duke.edu/~mark/docbookmarks/
• http://www.linuxdoc.org/LDP/LDP-Author-Guide/
• http://www.nwalsh.com/docs/
• http://www.e-smith.org/docs/docprocess.html
• http://www.lodestar2.com/people/dyork/talks/docbook/
• DocBook mailing list: mailto:docbook@lists.oasis-open.org
• http://xml.openoffice.org/xmerge/docbook/