Un dels requisits alhora d'escollir el software ha estat que el llenguatges de programació fora multiplataforma, en aquest cas Java, per tal que el sistema operatius fóra independent. En aquesta secció s'expliquen els passos per a Instal·lar aquest software en el sistema operatiu Windows XP.
L'esquema no és més que un arxiu de text que hem de tindre localitzat al dis dur. Baixar la versió XML DTD
corresponent a la del document DocBook que anem a publicar de
http://www.oasis-open.org/docbook/xml/, descomprimir
a una carpeta, per exemple c:\docbook-dtd. El fitxer que hem baixat està compost de una sèrie
d'arxius, el principal i que haurem de referenciar a la capçalera del nostre document és
docbookx.dtd
Alhora de referenciar la còpia local del DTD, que per exemple tenim localitzada a
c:\docbook-dtd\xml\4.5\docbookx.dtd, a la capçalera del document DocBook ha d'aparèixer com:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/docbook-dtd/xml/4.5/docbookx.dtd">
Catàlegs XML:
Un catàleg XML és un fitxer XML, l'element document del qual s'anomena catalog i segueix l'esquema DTD definit per OASIS a http://www.oasis-open.org/committees/entity/spec.html.
S'utilitza per a mapejar direccions globals d'arxius a direccions locals en una determinada màquina. D'aquesta manera els documents XML que s'utilitzen, tant les fulles d'estil com els arxius DocBook, poden tindre referències globals al seu DTD i a les fulles d'estil i és el catàleg qui s'encarrega de traduir-les a les referències locals. D'aquesta manera, a més de centralitzar la localització dels DTD's i les fulles d'estil donant flexibilitat i portabilitat al procés, fem possible l'us dels arxius locals en compte dels localitzats a les URL's, fent més ràpid el procés de transformació.
En cas d'utilitzar Catàlegs XML per a localitzar el DTD no cal modificar la capçalera del document DocBook, només mapejar correctament al Catàleg la ubicació del DTD:
Exemple 4.1. Catàleg XML per a mapejar les referències al DTD de DocBook
<!DOCTYPE catalog
PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<group prefer="public" xml:base="file:///C:/docbook_dtd/xml/" >
<public
publicId="-//OASIS//DTD DocBook XML V4.5//EN"
uri="4.5/docbookx.dtd"/>
<system
systemId="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
uri="4.5/docbookx.dtd"/>
<system
systemId="docbook4.5.dtd"
uri="4.5/docbookx.dtd"/>
</group>
</catalog>
D'aquesta manera el catàleg resoldrà la referència al DTD al fitxer local si és posible,
sinó la traduirà a la referència global. Sempre serà millor treballar amb fitxers locals
per eficiència, és més ràpid l'accés. En cas de canviar la localització del DTD a la màquina
on fem les transformacions, només caldria canviar l'element URI del catàleg i el xml:base.
S'ha d'indicar al processador XSLT que estem utilitzant un catàleg i la seva localització.
Hem de tindre en compte que el catàleg no pot resoldre la seva pròpia referència al DTD, pel que si no disposem de connexió a Internet, hauríem de llevar la declaració DOCTYPE, o canviar-la per a que fera referència a un DTD local i disposar d'ell.
Al igual que el DTD, només cal descomprimir l'arxiu per a poder referenciar els arxius
.xsl necessaris per a cada transformació.
Les fulles d'estil que s'utilitzen són les següents:
/html/docbook.xsl: Aquesta fulla d'estil
transforma un document DocBook a un sol arxiu HTML.
/html/chunk.xsl: Aquesta fulla d'estil
transforma un document DocBook a varis arxius HTML i crea els enllaços per a navegar entre ells.
Mitjançant paràmetres es pot indicar quin element DocBook genera un arxiu HTML.
/html/onechunk.xsl: genera un sol
arxiu HTML al digual que docbook.xsl però té els paràmetres de
chunk.xsl que tenen més opcions com per exemple indexar el codi HTML
generat per a una millor visualització posterior, quan siga necessari accedir a aquest codi
per a fer la fulla d'estil CSS que li donarà el disseny i apariència.
/fo/docbook.xsl: Aquesta fulla d'estil
transforma un document DocBook a format XSL:FO, per a una posterior transformació a PDF.
Per facilitar la referència als fitxers, al igual que amb els DTD es pot fer ús dels catàlegs XML, de manera que a la línia de comandaments no s'ha de posar tota la ruta completa fins el fitxer xsl, només el nom.
Exemple 4.2. Catàleg XML per a mapejar les referències a les fulles d'estil
<!DOCTYPE catalog
PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<group prefer="public" xml:base="file:///C:/docbook_dtd/xml/" >
..... códig de resolució del DTD ......
</group>
<group prefer="public" xml:base="file:///C:/docbook-xsl-1.70.1/html">
<uri
name="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
uri="docbook.xsl"/>
<uri
name="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"
uri="chunk.xsl" />
</group>
</catalog>
En la realització d'aquest projecte s'han utilitzat indistintament els dos processadors XSLT escollits, obtenint resultats equivalents, pel que no s'ha trobat ningun criteri per escollir-ne un dels dos.
Requisits:
Com que els processadors estan escrits en Java, s'ha de tindre una màquina virtual Java instal·lada: la Java 2 Plataform Standard Edition (J2SE) que podem baixar per a diferents plataformes al lloc web de Sun Microsystems, Inc. Recomanable tindre la versió 1.5.
Disponible a http://saxon.sourceforge.net/ o a la
carpeta /programari del CD que acompanya la memòria, utilitzar
la versió 6.5.5 que correspon a l'estándar XSLT 1.0 i descomprimir. L'arxiu descomprimit inclou la documentació,
el codi font i els arxius ja compilats per a utilitzar en la màquina Java que són els que utilitzarem, aquests
arxius tenen extensió .jar i només cal el següent:
saxon.jar: el processador XSLT.
A més del processador, per a poder utilitzar les extensions que incorpora s'ha de localitzar el fitxer
que les implementa, a la carpeta on prèviament s'han descomprimit les fulles d'estil. Aquest fitxer implementa
les extensions en Java per al processador Saxon i està localitzat a la carpeta /extensions
de les fulles d'estil.
saxon65.jar: implementa les extensions per
a utilitzar amb les fulles d'estil de Norman Walsh. En cas d'haver varis fitxer amb nom paregut, hem d'utilitzar
el que més s'aprope a la versió de Saxon que utilitzem.
Una vegada localitzats els arxius .jar els hem d'incloure a la variable
CLASSPATH per a que l'entorn d'execució Java els puga localitzar. En Windows XP es fa de
la següent manera:
A través del Panell de Control, obrir l'icona de Sistema.
En la pestanya de Opcions avançades clicar el botó de Variables d'entorn situat a la part inferior de la finestra.
A la llista de Variables de Sistema localitzar-ne una anomenada
CLASSPATH, en cas de que no existeixca la creem.
El valor de la variable CLASSPATH és una cadena de caràcters que conté
les rutes als fitxers .jarseparades per el símbol ';'.
Si els fitxers saxon.jar i saxon65.jar estan a la
carpeta c:\saxon\ el valor de la variable CLASSPATH
seria c:\saxon\saxon.jar;c:\saxon\saxon65.jar
.
Si teníem una finestra amb la línia de comandaments oberta,
els canvies que hem fet a la variables CLASSPATH no tenen efecte, cal tancar la
línia de comandaments i tornar-la a obrir.
Es pot comprovar que Saxon s'ha instal·lat correctament amb el següent comandament, que donarà com a eixida la versió de Saxon instal·lada:
java com.icl.saxon.StyleSheet -t
Per a utilitzar Saxon a la línia de comandaments:
Exemple 4.3. Sintaxi general de la utilització de Saxon a la línia de comandaments
java com.icl.saxon.StyleSheet \
opcions-del-processador \ (1)
document-xml \ (2)
fulla-d'estil \ (3)
parametres-fulla-d'estil (4)
Opcions del processador (opcional), a la documentació o a http://saxon.sourceforge.net/saxon6.5.3/using-xsl.html podem vore'n les possibilitats.
La ruta completa fins el document XML amb format DocBook que anem a transformar.
La ruta completa fins la fulla d'estil que s'utilitzarà per a transformar el document XML.
Els paràmetres de les fulles d'estil amb els valors associats (opcional).
El caràcter '\' que apareix a l'exemple indica que no s'ha de introduïr cap salt de línia a la línia de comandaments, en Linux es pot copiar el text de l'exemple tal i com apareix, però a Windows s'ha d'eliminar aquest caràcter i els salts de línia.
Opcional: utilitzar l'analitzador Xerces.
En comptes de l'analitzador que inclou Saxon, podem utilitzar el
Xerces, l'analitzador d'Apache que dóna més informació
com per exemple el fitxer, línia i tipus d'error trobat en el procés. Podem baixar-lo per separat o localitzar
el fitxer que s'anomena xercesImpl.jar en el processador Xalan, que el du incorporat.
Per a poder utilitzar l'analitzador Xerces, hem d'incloure la ruta del fitxer
xercesImpl.jar al CLASSPATH tal com s'ha fet prèviament,
i incloure les opcions corresponents a la línia de comandament per al Saxon:
java com.icl.saxon.StyleSheet \
-Djavax.xml.parsers.DocumentBuilderFactory=\
org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \
-Djavax.xml.parsers.SAXParserFactory=\
org.apache.xerces.jaxp.SAXParserFactoryImpl \
mes-opcions-del-processador \
document-xml \
fulla-d'estil \
parametres-fulla-d'estil
Podem baixar l'última versió de http://xml.apache.org/xalan-j/
o utilitzar la versió 2.7 de la carpeta Programari del CD que acompanya la memòria.
De manera anàloga a com s'ha fet amb el Saxon, hem de localitzar els arxius .jar que
necessitem i incloure'ls al CLASSPATH:
xalan.jar: el processador XSLT.
xercesImpl.jar: l'analitzador, que es
pot utilitzar també amb el Saxon.
xml-apis.jar: implementa les API's
SAX, DOM i JAXP que utilitza el Xalan.
xalansamples.jar: Algunes aplicacions
que no són necessàries per a transformar DocBook però si que poden ser útils, com per exemple
l'aplicació Validate, per a validar els documents DocBook:
java Validate document.xml
resolver.jar: Necessari per a l'ús de
catàlegs, tant en Xalan com amb Saxon.
A més d'aquests arxius, s'ha de localitzar l'arxiu que conté les extensions de les fulles d'estil
per al processador Xalan, localitzat a la carpeta /extensions de les fulles d'estil
i que s'anomena xalan27.jar.
Una vegaga localitzats aquests arxius, s'ha d'actualitzar la variable CLASSPATH,
que quedaria de la següent manera si tenim instal·lats Saxon i Xerces a les carpetes c:\saxon\
i c:\xalan\ respectivament:
c:\saxon\saxon.jar;\ c:\saxon\saxon65.jar;\ c:\xalan\xalan.jar;\ c:\xalan\xercesImpl.jar;\ c:\xalan\xml-apis.jar;\ c:\xalan\xalansamples.jar;\ c:\xalan\xalan27.jar
Per a comprovar que Xalan està instal·lat correctament podem executar el següent paràmetre que donarà com a eixida la versió de Xalan i de l'entorn d'execució Java que tenim instal·lats:
java org.apache.xalan.xslt.EnvironmentCheck
Per a utilitzar Xalan a la línia de comandaments:
Exemple 4.4. Sintaxi general de la utilització de Xalan a la línia de comandaments
java org.apache.xalan.xslt.Process \ -out fitxer-d'eixida \ (1) -in document-xml \ (2) -xsl fulla-d'estil \ (3) -param parametres valor (4)
Nom del fitxer resultat de la transformació.
La ruta completa fins el document XML amb format DocBook que anem a transformar.
La ruta completa fins la fulla d'estil que s'utilitzarà per a transformar el document XML.
Els parametres de les fulles d'estil amb els valors associats (opcional) i els paràmetres del processador (opcional).
Al igual que els altres dos processadors instalats, aquest està escrit en Java i el procediment
és similar. Baixem l'arxiu comprimit amb el processador de
http://xmlgraphics.apache.org/fop/ o de la carpeta /Programari del CD que
acompanya la memòria. Descomprimir i localitzar els arxius .jar necessaris:
fop.jar: el processador.
avalon-framework-cvs-20020806.jar: utilitzat
internament pel processador per a que tots els components puguen treballar conjuntament.
batik.jar: suport per a la inclusió de
gràfics en format SVG.
Són necessaris també l'analitzador i l'arxiu que implementa les API's, que es suposa que ja estàn
instalats amb Xalan: xercesImpl.jar i xml-apis.jar. Fop suporta
alguns formats gràfics però no tots, si volem per exemple incloure imatges amb format PNG cal instal·lar
també les llibreries gràfiques JAI
(Java Advanced Imaging) de Sun. Les podem baixar de la web
http://java.sun.com/products/java-media/jai/current.html o de la carpeta /Programari
del CD. Per a Windows és un executable que instal·la les llibreries gràfiques, però que
després Fop no pot localitzar, pel que una vegada instal·lat hem de buscar a la carpeta d'instal·lació
que per defecte és C:\jai-1_1_2_01\ i localitzar els arxius
.jar i les
llibreries .dll que utilitzen: jai_core.jar i jai_codec.jar
i incloure'ls al CLASSPATH (Només els arxius jar, les llibreries només cal que
estiguen a la mateixa carpeta).