1 Cursillos de Julio 2006 DocBook Unai Aguilera gkalgan @ gmail. com

2 DocBook Introducción DocBook es un lenguaje de etiquetas para elaborar documentación técnica. Fue creado para elaborar documentación relativa a hardware y software pero puede utilizarse para cualquier otro tema. La principal característica de DocBook es que utiliza un lenguaje neutral para especificar el documento separándolo de la presentación final. Se puede general HTML, PDF, páginas man, etc, sin necesidad de cambiar el fichero fuente.

3 DocBook Introducción DocBook comenzó como un proyecto de las empresas HAL Computer Systems y O' Reilly Associates en 1991. En 1998 fue adoptado por el SGML Open Consortium, Actualmente es un estándar mantenido por el DocBook Technical Committee del OASIS Consortium. OASIS es Organization for the Advancement of Structured Information Standards (www.oasis- open.org)

4 DocBook Introducción DocBook esta disponible tanto en SGML como en XML. SGML (Standard Generalized Markup Language) Es un metalenguaje para definir lenguajes de marcado de documentos. Es complicado. Disponible como DTD (Document Type Definition). XML (Extensible Markup Languaje) Es un lenguaje de marcado que permite definir otros lenguajes de marcado. Es un subconjunto simplificado de SGML. Disponible como DTD y XML Schema.

5 DocBook Introducción En nuestro caso vamos a utilizar DocBook definido mediante XML Schema. XML Schema Permite expresar el conjunto de reglas que debe cumplir un documento XML para que se le considere del tipo determinado por el esquema. El XML Schema de DocBook define las etiquetas y la estructura de un documento de este tipo. Cualquier documento que no respete estas reglas no será considerado un documento DocBook válido.

6 DocBook Introducción Por lo tanto escribir un documento DocBook es similar a escribir HTML pero con otras etiquetas y reglas. ¿Y después de escribir el documento DocBook? Es necesario realizar un proceso para generar el documento. En HTML el navegador “ hace algo” para pintar la página. En DocBook este proceso se realiza utilizando hojas de estilo llamadas XSL.

7 DocBook Introducción XSL (eXtensible Stylesheet Languaje) Es un lenguaje que permite definir como se debe transformar otro fichero XML. Existen varios tipos XSLT: lenguaje XML para transformar otros documentos XML. XSL-FO: lenguaje XML para especificar el formateo visual de otros documentos XML. XPath: lenguaje no XML que permite acceder a partes de documentos XML. Las transformaciones para DocBook se realizan utilizando hojas XSTL y XSL-FO

8 DocBook Conversión a otros formatos Docbook HTML (Single) HTML (Multiple) XSL-FO PDF XSL T LaTeX RTF

9 DocBook Referencias imprescindibles DocBook XSL: The Complete Guide Bob Stayton http://www.sagehill.net/docbookxsl/ DocBook: The Definitive Guide Norman Walsh, Leonard Muellner http://www.docbook.org/tdg/

10 DocBook Introducción Un ejemplo rápido Ejemplo Sencillo Primer capitulo Primer parrafo Segundo parrafo $docbook2html test.hmtl $>docbook2html ejemplo.xml

11 DocBook Sintaxis XML DocBook XML es un dialecto XML, con lo que hay que tener muy presentes las normas de sintaxis de XML. En XML una etiqueta empieza por el símbolo ‘menor que’ Justo después del símbolo < se encuentra el nombre de la etiqueta.

12 DocBook Sintaxis XML Hay dos tipos de etiquetas: Non-Empty o ‘contenedora’: Contienen texto o más etiquetas. Tiene que haber una etiqueta de comienzo y una etiqueta de fin. En la etiqueta de fin, el símbolo < siempre va seguido del símbolo /...

13 DocBook Sintaxis XML Empty o vacía: No contienen nada. El símbolo > debe ir siempre precedido del símbolo / También se admite la forma:

14 DocBook Sintaxis XML Las etiquetas pueden tener atributos. Estos atributos indican opciones de la etiqueta. Los atributos tienen la siguiente sintaxis: nombre_atributo =“ valor ” Si hay mas de un atributo, tienen que ir separados por espacios.

15 DocBook Sintaxis XML Toda etiqueta de comienzo debe tener etiqueta de fin. Las etiquetas no deben solaparse. Debe haber una única etiqueta en la raíz del documento ( ). Los valores de los atributos deben ir entre comillas (dobles o simples) Una etiqueta no puede tener dos atributos con el mismo nombre.

16 DocBook Estructura Básica El documento siempre debe empezar por: Declaración XML Declaración del tipo de documento

17 DocBook Estructura Básica (II) El elemento raíz de un documento DocBook es También podemos utilizar otros elementos raíz....

18 DocBook Estructura Básica La etiqueta puede contener: Metadatos (autor, copyright, etc.) Prólogos Apéndices Bibliografías Glosarios Índices etc. Los veremos en detalle más adelante.

19 DocBook Estructura Básica Un ejemplo de una etiqueta para añadir metadatos: Ejemplo Sencillo...

20 DocBook Estructura Básica (V) Añadimos capitulos con También pueden contener una etiq. Ejemplo Sencillo Primer capitulo...

21 DocBook Estructura Básica (VI) Dentro de los capítulos nos encontraremos con etiquetas de bloque. Por ejemplo, parrafos: Hay una gran cantidad de etiquetas de bloque: imagenes, tablas, etc. Los capítulos también pueden dividirse en secciones:

22 DocBook Estructura Básica (VII) Ejemplo Sencillo Primer capitulo Primer parrafo Segundo parrafo

23 DocBook Índice Introducción Estructura básica de un documento DocBook Generación básica de documentos Más etiquetas DocBook Generación avanzada de documentos

24 DocBook Generación Básica A partir del documento DocBook podemos generar documentos orientados a la presentación: XHTML (un único fichero) XHTML (un fichero por capítulo) XSL-FO. A partir de este formato: PDF LaTeX RTF

25 DocBook Generación Básica Esta conversión se hace con hojas de transformación XSLT. No tenemos que escribirlas nosotros mismos. Existen unas hojas de transformación prácticamente estándares: http://docbook.sourceforge.net/ Debian: paquetes “docbook-xml” y “docbook- xsl” Veremos que estas hojas son fácilmente parametrizables para ajustarlas a nuestras necesidades.

26 DocBook Generación Básica Una vez hayamos instalado las hojas de transformación, seguiremos dos pasos para generar un documento XHTML: Validar el documento DocBook (paso opcional, pero recomendable) Realizar la transformación

27 DocBook Generación Básica Para validar el documento podemos utilizar la utilidad “xmllint” Parte de libxml: http://xmlsoft.org/ Debian: paquete libxml2-utils xmllint --valid --noout fichero_docbook Nos indicará si hay algún error en el documento (falta alguna etiqueta, errores de sintaxis, etc.)

28 DocBook Generación Básica Para realizar la transformación, podemos utilizar cualquier procesador XSLT: Saxon: http://saxon.sourceforge.net/ http://saxon.sourceforge.net/ Xalan: http://xml.apache.org/ http://xml.apache.org/ xsltproc: http://xmlsoft.org/XSLT/ http://xmlsoft.org/XSLT/ Nosotros utilizaremos xsltproc

29 DocBook Generación Básica Para aplicar una transformación: xsltproc \ --output fichero_salida \ fichero_XSLT \ fichero_DocBook En Debian: xsltproc \ --output fichero_salida \ /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl \ fichero_DocBook

30 DocBook Generación Básica En general, siempre es válido lo siguiente: xsltproc \ --output fichero_salida \ http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl \ fichero_DocBook El procesador XSLT recuperará el fichero de Internet, o lo mapeará a un fichero local (si tenemos soporte para XML Catalogs) Debian Sarge incluye soporte para XML Catalogs.

31 DocBook Etiquetas DocBook Las etiquetas en DocBook se dividen en las siguientes categorías: Conjuntos ( set ) Libros ( book ) Divisiones ( part ) Componentes ( chapter ) Secciones ( section ) Metadatos ( author ) Bloques ( para ) Elementos inline ( citation )

32 DocBook Conjuntos Podemos definir varios libros en un único documento utilizando conjuntos:......

33 DocBook Libros, Divisiones, Componentes (I) Un libro ( ) se divide en... Divisiones ( ) que se dividen en... Componentes Un libro también puede dividirse directamente en componentes.

34 DocBook Libros, Divisiones, Componentes (II)...

35 DocBook Secciones (I) Un componente se divide en secciones: (pueden anidarse recursivamente) (sección no numerada) excepto, e que solo pueden dividirse en: No pueden anidarse

36 DocBook Secciones (II) Ejemplo Sencillo Primer capitulo Sección Primer parrafo Segundo parrafo

37 DocBook Metadatos (I) Es posible agregar metadatos a...,,,,,,, etc. mediante el tag En estas etiquetas podemos incluir información sobre : Autor/es, Copyright y otros avisos legales (licencias, etc.) Lista de cambios (change log), etc.

38 DocBook Metadatos (II) Por ejemplo: Ejemplo con Metadatos Pablo Perez 2004 Este ejemplo esta disponible bajo los terminos de la GFDL bla, bla, bla...

39 DocBook Bloques Las etiquetas de bloque son aquellas que, en la presentación, generalmente requieren un salto de lineas antes y/o después del bloque. Por ejemplo: Listas Ejemplos, figuras, tablas Parrafos Ecuaciones

40 DocBook Listas (I) y Hay más tipos de listas Tienen que contener etiquetas que, a su vez, deben contener elementos de bloque (p.ej. parrafos)

41 DocBook Listas (II) Primer item Segundo item (1) Segundo item (2)

42 DocBook Ejemplos, Figuras, Tablas,, Contienen ejemplos, figuras, y tablas. Siempre tienen titulo ( ) Al convertir DocBook a un formato de presentación, estos bloques pueden flotar o permanecer donde están (dependerá de la conversión, no de DocBook).,, No tienen título y generalmente no flotan.

43 DocBook Figuras (I) Para insertar datos multimedia: Puede contener:,, contiene Atributos de fileref: URL de la imagen Atributos para controlar tamaño de la imagen

44 DocBook Figuras (II) Una imagen

45 DocBook Tablas (I) Las tablas en DocBook son muy versátiles, y están indicadas únicamente para datos que se presten a una presentación tabular. No podemos utilizarlas para maquetar, como en HTML. La sintaxis de una tabla sencilla en DocBook es muy similar a la de HTML Tabla Fila Celda

46 DocBook Tablas (II) Una tabla A B C D

47 DocBook Miscelanea Lista de preguntas y respuestas Código fuente Contenidos de una consola de texto Citas textuales Ecuación matemática Para describir procedimientos que consten de varios pasos ( )

48 DocBook Elementos en Linea (I) Las etiquetas inline se utilizan para anotar ciertas partes del texto, pero sin provocar un salto de linea antes o despues del texto etiquetado (a diferencia de los bloques). Las etiquetas inline generalmente sirven para añadir metadatos al propio texto del documento, aunque muchas veces también afectan a la presentación.

49 DocBook Elementos en Linea (II) Los típicos... énfasis (cursiva) nota al pie de página cita textual (no bloque)

50 DocBook Elementos en Linea (III) Enlaces Enlace con una URL Enlace con otra parte del documento El valor de “linkend” debe ser el valor del atributo “id” de la etiqueta con la que queremos enlazar Referencia a otra parte del documento.

51 DocBook Elementos en Linea (IV) Primer capitulo Primer parrafo Segundo parrafo Segundo capitulo Enlace

52 DocBook Elementos en Linea (V) Tenemos una gran cantidad de elementos inline para anotar el texto. Por ejemplo: Una frase en otro idioma El valor devuelto por una función Denota el nombre de un fichero Denota una dirección de e-mail Muchos, muchos más. La mayoría de estos elementos no afectan a la presentación, pero aportan muchos metadatos al documento, facilitanto búsquedas, indexación, etc.

53 DocBook Índice Introducción Estructura básica de un documento DocBook Generación básica de documentos Más etiquetas DocBook Generación avanzada de documentos

54 DocBook Generación Avanzada Podemos generar más tipos de documentos: XHTML 'en cachos' XSL-FO LaTeX, PDF, RTF Podemos parametrizar la generación: Pasando parámetros al procesador XSLT Creando una hoja de transformación XSLT como extensión de una existente

55 DocBook Varios Documentos XHTML (I) Para generar varios documentos XHTML... En Debian: xsltproc \ /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl \ fichero_DocBook En general: xsltproc \ http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl \ fichero_DocBook

56 DocBook Varios Documentos XHTML (II) El fichero “index.html” es el índice del documento generado. Por defecto: Un índice Una página por cada capítulo con el índice del capítulo y la primera sección. Una página por cada sección. Este comportamiento puede modificarse.

57 DocBook XSL-FO y PDF (I) Para generar XSL-FO... En Debian: xsltproc \ --output fichero_salida \ /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl \ fichero_DocBook En general: xsltproc \ --output fichero_salida \ http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl \ fichero_DocBook

58 DocBook XSL-FO y PDF (II) Aunque existen visualizadores de XSL-FO, es más habitual convertirlo a otro formato más extendido. XSL-F O PDF XSL-FO LaTeX PDF

59 DocBook XSL-FO y PDF (III) XSL-FO PDF Utilizando Apache FOP http://xml.apache.org/fop/ http://xml.apache.org/fop/ Programado en Java El proyecto está congelado y todavía no soporta todas las características de XSL- FO. El resultado es aceptable, pero puede dar problemas con documentos grandes y complejos. Es aconsejable pasar el siguiente parámetro a xsltproc: --string-param fop.extensions 1

60 DocBook XSL-FO y PDF (IV) XSL-FO LaTeX PDF Utilizando PassiveTeX. Suele venir incluido en las distribuciones de LaTeX, pero como componente opcional. En Debian: paquetes “passivetex” y “xmltex” Para convertir de XSL-FO a PDF: pdfxmltex fichero_xslfo Es aconsejable pasar el siguiente parámetro a xsltproc: --string-param passivetex.extensions 1

61 DocBook XSL-FO y PDF (V) Calidad tipográfica de LaTeX. Suele producir mejores resultados que FOP. Sin embargo, si nos encontramos con errores o problemas, nos costará entenderlos si no sabemos LaTeX

62 DocBook Parametrización (I) Podemos parametrizar la generación de XHTML, XSL-FO, etc. Pasando parámetros al procesador XSLT Creando una hoja de transformación XSLT como extensión de una existente Los parámetros son simplemente parejas (nombre,valor) La lista completa de parámetros está disponible en: http://docbook.sourceforge.net/release/xsl/current/doc/reference.html http://docbook.sourceforge.net/release/xsl/current/doc/reference.html

63 DocBook Pasando parámetros al procesador XSLT: Pasando a xsltproc el siguiente parámetro desde la linea de comandos: --string-param nombre_param valor_param Por ejemplo, para eliminar los enlaces de navegación en el pie de las páginas (al generar varios documentos XHTML): --string-param suppress.footer.navigation 1 Parametrización (II)

64 DocBook Parametrización (III) Creando una nueva hoja XSLT: Si utilizamos muchos parámetros, la invocación de XSLT puede resultar bastante engorrosa. Podemos definir una hoja de transformación en función de otra. En nuestra nueva hoja solo tenemos que incluir nuestros parámetros. Indicaremos al procesador XSLT que queremos utilizar la nueva hoja.

65 DocBook Parametrización (IV) valor1 valor2 valor3

66 DocBook Parametrización (V) 1

67 DocBook Parametrización (VI) Si no encontramos un parámetro que nos permita ajustar algún aspecto concreto de la generación, podemos añadir nuestro propio código XSLT. Las modificaciones más habituales que requieren escribir código XSLT ya están bien documentadas.

68 Cursillos de Julio 2006 DocBook Unai Aguilera gkalgan @ gmail.com Créditos: Nando Quintana Pablo Pérez Borja Sotomayor