Creando Documentación Técnica con DocBook

Hardy Beltran Monasterios Instructor y Consultor Linux hardy@acm.org

Hardy
Distribuido bajo Licencia Creative Commons Attribution-NonCommercial-NoDerivs

Agenda
Introducción
Hardy Beltran Monasterios • www.hardy.com.bo

Comenzado con DocBook Creando un artículo DocBook Conociendo marcas útiles de DocBook Generando documentos HTML y PDF Personalizando hojas de estilo Conclusiones y Referencias Preguntas
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Introducción

¿ Y qué es documentación Técnica ?
Para nosotros del mundo de las compu
Hardy Beltran Monasterios • www.hardy.com.bo

Manuales de usuario Libros, Tutoriales Ensayos y artículos técnicos Documentación de un API Preguntas Comunes Diapositivas

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

¿ Y qué es DocBook ?
Hardy Beltran Monasterios • www.hardy.com.bo

Es un sistema para escribir documentos estructurados en SGML o XML Bien adaptado para escribir documentos técnicos relacionados con las computadoras, aunque no está limitado a ello Apoyado por empresas y organizaciones Cuenta con un número amplio de usuarios y desarrolladores
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Un poco de historia
Hardy Beltran Monasterios • www.hardy.com.bo

Creado en 1991 por HaL Computer Systems y O'Reilly & Associates Desde 1998 es parte de OASIS Hoy en día participan varias empresas
Novell Sun Microsystems Hewlett Packard Fujitsu y muchos otros mas
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

¿ Quienes usan DocBook ?
Varias empresas del sector IT
Hardy Beltran Monasterios • www.hardy.com.bo

Varias distribuciones de Linux
Red Hat, Fedora, Suse, Gentoo, LFS, etc.

Varios proyectos de documentación de Software Libre/Abierto
GNOME, KDE, PHP, Linux Documentation Proyect, etc.

Varios consultores y autores de documentación libre
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

¿ Por qué usar DocBook ?
Hardy Beltran Monasterios • www.hardy.com.bo

El autor se concentra en el contenido y no en el aspecto del documento Estilos personalizables y extensibles Se pueden producir varios formatos
HTML, XHTML, Ayuda Java, Ayuda HTML PostScript, PDF, RTF, Texto «man pages», «XSL Formating Objects»

Número creciente de herramientas comerciales y libres/abiertas
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Desventajas de DocBook
Demasiadas marcas XML/SGML
Hardy Beltran Monasterios • www.hardy.com.bo

Inicialmente su aprendizaje es lento para quienes nunca usaron «lenguajes de marcas» Algunas herramientas libres no son suficiente maduras para ciertos usos (Ej. Editor XML, Convertir XML FO a PDF) Varias herramientas maduras son solo para Windows y no son libres
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

¿ Cómo funciona DocBook ?
FOP
XSL FO
Hardy Beltran Monasterios • www.hardy.com.bo

FO XML

PDF

Procesador XSLT XSL

DVI PassiveTex

HTML, XHTML, Java Help

Postscript

dvips

Modo de operación de DocBook XML

Los íconos fueron tomados de GNOME

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Comenzando con DocBook

¿ DocBook XML o SGML ?
XML es más simple de manejar
Hardy Beltran Monasterios • www.hardy.com.bo

Clara tendencia a XMLizar el mundo ;-) Históricamente DocBook ha sido SGML Desde la versión 4 es XML y SGML La versión 5 será principalmente XML Hay un creciente número de herramientas para tratar XML

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Básicamente se necesita
Un editor de texto o editor XML
Hardy Beltran Monasterios • www.hardy.com.bo

DocBook instalado en su sistema
El DTD de DocBook XML Hojas de estilo XSLT DocBook

Un procesador XSLT
Por ejemplo xsltproc

Un procesador FO (si quiere PDF)
Por ejemplo Apache FOP
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Editando XML
Emacs y nXML
Hardy Beltran Monasterios • www.hardy.com.bo

Emacs es un poderoso editor de textos ampliamente usado en Linux. nXML es un complemento que facilita escribir marcas XML. Valida mientras se escribe, ofrece sintaxis coloreada y autocompleta.

VIM
Con ayuda de determinadas macros se puede editar también fácilmente XML.

Conglomerate
Editor XML Libre basado en GTK. (no maduro)
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Instalar DTD y XSL DocBook
En sistemas Debian Linux
Hardy Beltran Monasterios • www.hardy.com.bo

apt-get install docbook-xml docbook-xsl

En sistemas RPM con yum
yum install docbook

Vea si su distro ya trae instalado DocBook
Red Hat, Fedora, CentOS, WhiteBox instalan de modo predeterminado las herramientas DocBook
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

El DTD de DocBook
Hardy Beltran Monasterios • www.hardy.com.bo

Define la estructura, elementos y atributos de un documento DocBook Los procesadores XSLT requieren el DTD para validar el documento XML El DTD puede ser accedido en línea o puede estar en el sistema de archivos local

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Hojas de estilo DocBook
Hardy Beltran Monasterios • www.hardy.com.bo

Norman Walsh mantiene las hojas de estilo estándar Hay dos tipos de hojas de estilo, pero con DocBook XML usamos hojas de estilo XSL Las hojas de estilo son las que permiten generar varios formatos de salida
HTML, XHTML, PS, PDF, RTF, etc
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Sobre el procesador XSLT
Puede utilizar los siguientes
Hardy Beltran Monasterios • www.hardy.com.bo

libxsl/xsltproc – escrito en C, originalmente para GNOME. Veloz y maduro. Saxon – escrito en Java incluye funciones experimentales. Xalan – escrito en Java por el proyecto Apache, ampliamente usado en la comunidad.

Hay también alternativas comerciales
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Instalar un procesador XSLT
En sistemas Debian Linux
Hardy Beltran Monasterios • www.hardy.com.bo

apt-get install xmlto En sistemas RPM con yum yum install xmlto Para usar Xalan vaya al sitio de Apache, descarge el programa y siga las instrucciones. Varias distribuciones ya traen libxsl/xsltproc instalado xmlto es un conjunto de scripts que facilita el uso de un «toolchain». Actualmente sólo usa xsltproc
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Creando un artículo DocBook

Cabecera de DocBook XML
Un documento empieza con la cabecera:
Hardy Beltran Monasterios • www.hardy.com.bo

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

DOCTYPE define el tipo de documento article – para un artículo (varias secciones) book – para un libro (varios capítulos con varias secciones)
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Datos básicos de un artículo
... <article id="tutorial-ejemplo" lang="es"> <articleinfo> <title>Trabajando con directorios</title> <copyright> <year>2005</year> <holder>Hardy Beltran Monasterios</holder> </copyright> <authorgroup> <author> <surname>Beltran Monasterios</surname> <firstname>Hardy</firstname> <email>hbm@hardy.com.bo</email> </author> </authorgroup> <legalnotice><para>...</para></legalnotice> </articleinfo> ... ...
Hardy Beltran Monasterios • www.hardy.com.bo

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Secciones de un artículo
Hardy Beltran Monasterios • www.hardy.com.bo

Un documento tipo artículo puede estar formado de varias secciones:
... <sect1 id=”seccion_1”> <title>Título de esta sección</title> <para>Este párrafo aparece en la sección 1</para> </sect1> <sect1 id=”seccion_2”> <title>Otra sección</surname> <para>Algún texto</para> <sect2 id=”seccion_2.1> <title>Otro título</email> <para>...</para> </sect2> </sect1> ...

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marcas de sección
Hardy Beltran Monasterios • www.hardy.com.bo

Una sección es una división lógica del contenido del documento Las secciones se definen usando las marcas <sect1> a <sect5> o simplemente <section> Esta última sólo se puede usar en documentos tipo “article” Se pueden usar cuantas secciones se necesite.
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Conociendo marcas útiles de DocBook

Recomendaciones generales
Hardy Beltran Monasterios • www.hardy.com.bo

Todas las marcas DocBook XML se deben escribir en minúsculas Toda marca que se abra se debe cerrar Los identificadores de capítulos, secciones, tablas, figuras, etc., deben ser únicos

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <application>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para referirse a una aplicación gráfica o texto. Ejemplo:
Para trabajar con archivos Zip comprimidos, usted puede usar el programa <application>File Roller</application> en modo gráfico o utilizar el programa <application>Zip</application> desde la línea de órdenes.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <citetitle>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para hacer cita una referencia externa. Por ejemplo:
Para una descripción detallada del proceso de instalación consulte la <citetitle>Guía Oficial de Instalación para Intel x86</citetitle>.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <command>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para referirse al ejecutable de una aplicación, a una orden o una directiva de configuración. Por ejemplo:
Para configurar la red en Linux Red Hat usted puede usar la orden <command>netconfig</command>. <command>DocumentRoot</command> - Esta directiva de configuración le indica al servidor Apache la ubicación de los documentos (páginas web) a servir.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <computeroutput>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para mostrar mensajes que aparecen en la pantalla. Por ejemplo:
<computeroutput>rm: ¿borrar el fichero regular «Makefile»? (s/n)</computeroutput>

El contenido se debe poner inmediatamente después de la marca. Como en la marca <screen> se respetan los espacios y líneas extras.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <emphasis>
Se usa para poner énfasis a una frase
Hardy Beltran Monasterios • www.hardy.com.bo

Ejemplo:
Usar <command>/sbin/mke2fs</command> sobre un sistema de archivos existente, provocará que se pierda <emphasis>toda</emphasis> la información contenida en éste.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <example>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para mostrar ejemplos acompañados de un título Típicamente son secciones de código o de archivos de configuración. Ejemplo:
<example id=”ej-resolv”> <title>Dominio y servidor DNS a utilizar</title> <screen> <computeroutput>domain unsitio.com nameserver 192.168.1.4;</computeroutput> </screen> </example>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <filename>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para hacer referencia a nombres de archivo o directorios. Si es un directorio se sugiere incluir “/” al final para clarificar el texto Ejemplo:
El archivo <filename>/etc/passwd</filename> contiene varias piezas de información de una cuenta de usuario.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <figure>
Hardy Beltran Monasterios • www.hardy.com.bo

Use si quiere incluir una figura que tenga un título y una breve descripción
<figure id=”f-pref-mozilla”> <title>Preferencias de Mozilla</title> <mediaobject> <imageobject> <imagedata fileref="./figs/moz-pref.eps" format="EPS"/> </imageobject> <imageobject> <imagedata fileref="./figs/moz-pref.png" format="PNG"/> </imageobject> <textobject> <phrase>La figura muestra las preferencias...</phrase> </textobject> </mediaobject> </figure>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <footnote>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para insertar una nota al pie de página Ejemplo:
En una instalación estándar, la partición asignada a <filename>/boot</filename> <footnote> <para>En algunos sistemas debido a problemas con discos grandes, se acostumbra crear esta partición dentro los primeros 1024 cilindros.</para> </footnote> requerirá un espacio de 60 a 100 MiB.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <foreignphrase>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para mostrar una palabra o frase en un idioma diferente al del documento Ejemplo:
Las siguientes órdenes deben ser escritas desde el indicador del sistema (<foreignphrase>prompt </foreignphrase>).

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Lista de ítemes <itemizedlist>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para mostrar información breve que no requiere un orden específico Ejemplo:
<itemizedlist> <listitem> <para>Revisar uso de espacio libre en disco</para> </listitem> <listitem> <para>Monitorear y gestionar procesos</para> </listitem> <listitem> <para>Mantener programas al día</para> </listitem> </itemizedlist>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Lista ordenada <orderedlist>
Hardy Beltran Monasterios • www.hardy.com.bo

Para mostrar una lista de ítemes cuyo orden tiene importancia Ejemplo:
<orderedlist> <listimtem> <para>Instalar el paquete</para> </listimtem> <listimtem> <para>Modificar el archivo de configuración</para> </listimtem> <listimtem> <para>Iniciar el servicio</para> </listimtem> </orderedlist>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Lista de términos y definiciones <variablelist>
Hardy Beltran Monasterios • www.hardy.com.bo

Para mostrar una lista de términos y definiciones con sus descripciones
<variablelist> <varlistentry> <term>Servidor <listimtem> <para>Ofrece </listimtem> </varlistentry> <varlistentry> <term>Servidor <listimtem> <para>Provee </listimtem> </varlistentry> ... </variablelist> X</term> las operaciones básicas de...</para>

de Letras X</term> los tipos de letras...</para>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Lista simple <simplelist>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa principalmente para crear una lista contenida en una tabla Ejemplo:
<simplelist> <member>Procesador Intel</member> <member>Pentium IV 4.2 Ghz</member> <member>512 MiB RAM</member> <member>80 GiB Disco</member> <member>CDWR/DVD</member> </simplelist>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <option>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para indicar una opción de una determinada orden Ejemplo:
La orden <command>uname</command> seguida de la opción <option>-r</option> muestra la versión de núcleo que está ejecutando su sistema.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <para>
Hardy Beltran Monasterios • www.hardy.com.bo

Esta marca se emplea alrededor de cualquier párrafo simple. Ejemplo:
<para> La orden <command>uname</command> seguida de la opción <option>-r</option> muestra la versión de núcleo que está ejecutando su sistema. </para>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Contenido en marcas <para>
Hardy Beltran Monasterios • www.hardy.com.bo

Sólo use marcas <para> alrededor de párrafos simples únicamente Específicamente no use <para> alrededor de las siguientes marcas:
<itemizedlist> <orderedlist> <variablelist> <screen> <table>
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <prompt>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para mostrar un indicador (prompt). Ejemplo:
En el indicador <prompt>LILO:</prompt> escriba linux para arrancar su sistema. El indicador <prompt>#</prompt> está reservado al usuario privilegiado root.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <replaceable>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa indicar que el lector debe remplazar el texto mostrado de manera adecuada a su situación Ejemplo:
Los módulos del núcleo se encuentran en el directorio <filename>/lib/modules/<replaceable>versión-denúcleo</replaceable>/</filename>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <screen>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para mostrar listado de programas, contenido de archivos o cualquier resultado mostrado en pantalla. Por ejemplo
<para>Para ver la versión de su núcleo escriba:</para> <screen> <userinput>uname -r</userinput> </screen> <para>Que mostrará un resultado similar a:</para> <screen> <computeroutput>2.4.29-686</computeroutput> </screen>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Contenido en marcas <screen>
Hardy Beltran Monasterios • www.hardy.com.bo

La marca y el contenido deben estar justificados a la izquierda Cualquier espacio dentro la marca <screen> se conserva Esta marca puede contener otras como: <computeroutput>, <userinput>, o <replaceable> Por definición no se requiere incluir otras marcas dentro de <screen>
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <table>
<table id="tb-pop-imap"> <title>Características de POP e IMAP</title> <tgroup cols=”3”> <colspec colnum="1" colname="carac" colwidth="120pt"/> <colspec colnum="2" colname="pop" colwidth="30pt"/> <colspec colnum="3" colname="imap" colwidth="30pt"/> <thead> <row> <entry>Característica</entry> <entry>POP</entry> <entry>IMAP</entry> </row> </thead> <tbody> <row> <entry>Trabaja en modo conectado (on-line)</entry> <entry>Si</entry> <entry>Si</entry> </row> </tbody> </tgroup> </table>
Hardy Beltran Monasterios • www.hardy.com.bo

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Tablas <table>
<table id="tb-pop-imap"> <title>Características de POP... <tgroup cols=”3”> <colspec colnum="1" colname=... <colspec colnum="2" colname=... <colspec colnum="3" colname=... <thead> <row> Tabla 1. Características POP e IMAP <entry>Característica</entry> <entry>POP</entry> Característica POP IMAP <entry>IMAP</entry> </row> Trabaja en modo conectado Si Si </thead> <tbody> <row> <entry>Trabaja en modo... <entry>Si</entry> <entry>Si</entry> </row> </tbody> </tgroup> </table>
Hardy Beltran Monasterios • www.hardy.com.bo

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <userinput>
Hardy Beltran Monasterios • www.hardy.com.bo

Se usa para indicar lo que el usuario debe escribir. Ejemplo:
En el indicador del sistema escriba: <userinput>fdformat /dev/fd0</userinput>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Marca <xref>
Hardy Beltran Monasterios • www.hardy.com.bo

Use para hacer referencia a otra sección o capítulo del documento Ejemplo:
Para ver más información sobre las particiones de disco en Linux, refiérase a <xref linkend=”sec-particiones” />.

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Generando documentos

Generar un sólo archivo HTML
Por claridad vamos a usar la variable
Hardy Beltran Monasterios • www.hardy.com.bo

DB=/usr/share/xml/docbook/stylesheet/nwalsh

Aplicamos la hoja de estilo al documento XML para generar HTML
xsltproc -o ejemplo.html $DB/html/docbook.xsl ejemplo.xml

Ver el documento en el navegador
mozilla ~/Vcongreso/ejemplo.html

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Generar varios archivos HTML
Cada sección es un archivo HTML
Hardy Beltran Monasterios • www.hardy.com.bo

El archivo inicial es «index.html» La hoja de estilo que se debe usar es «chunk.xsl»
xsltproc $DB/html/chunk.xsl ejemplo.xml

Ver el documento en el navegador
mozilla ~/Vcongreso/index.html

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Generar PDF
Es un proceso de dos pasos
Hardy Beltran Monasterios • www.hardy.com.bo

Generar documento FO desde XML Generar PDF desde FO

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

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Limitaciones de generar PDF
Hardy Beltran Monasterios • www.hardy.com.bo

Las herramientas libres para generar PDF no están del todo maduras
FOP PassiveTex / pdflatex

Los problemas típicos son:
Contenido dentro de tablas Manejo de imágenes con formato especial de presentación Problemas de memoria al generar documentos de muchas páginas (> 100)
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Alternativas propietarias
Hardy Beltran Monasterios • www.hardy.com.bo

Muchos autores de DocBook usan la herramienta XEP XEP genera a partir de XML documentos PDF y PostScript aplicando XSL FO Tienen una versión gratuita para uso no comercial (Personal Edition) Visite http://www.renderx.com/ para más información
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Personalización de XSL
Hardy Beltran Monasterios • www.hardy.com.bo

Una ventaja de las hojas de estilo XSL es su flexible personalización (uso de «capas») La personalización es posible de dos formas
Modificando parámetros predeterminados
Ej. Tipo de papel, enumerar títulos

Modificando procesamiento de elementos
Ej. Insertar una imagen al inicio de un capítulo
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Personalización por capas
Hardy Beltran Monasterios • www.hardy.com.bo

Significa que se crea una capa de personalización con todos los cambios deseados y se mantienen las hojas de estilo DocBook XSL estándar Una capa de personalización es una hoja de estilo XSL, que se aplica encima de las hojas de estilo DocBook XSL existentes

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Ejemplo de capa de personalización XSL
<?xml version='1.0' ?>
Hardy Beltran Monasterios • www.hardy.com.bo

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <!-- Referencia a la hoja de estilo estandar DocBook XSL --> <xsl:import href="/usr/share/sgml/docbook/xslstylesheets/xhtml/docbook.xsl"/> <!-- Parametros TOC --> <xsl:param name="toc.section.depth">2</xsl:param> <xsl:param name="section.autolabel" select="1"/> </xsl:stylesheet>

Mire en /usr/share/doc/docbook-xsl/doc/reference.html para ver una referencia de los parámetros disponibles
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Uso de la capa de personalización XSL
Hardy Beltran Monasterios • www.hardy.com.bo

Basta con usar nuestra hoja de estilo en lugar de la hoja de estilo estándar Usando nuestro procesador XSLT
xsltproc -o ejemplo-mixsl.html miestilo_1.xsl ejemplo.xml

Para ver el resultado abrimos ejemplomixsl.html en el navegador

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Usando CSS con HTML/XHTML
Hardy Beltran Monasterios • www.hardy.com.bo

Para mejorar la calidad de presentación de los documentos HTML/XHTML podemos utilizar CSS CSS tiene la ventaja de ser muy flexible y lograr ricos resultados Para esto requerimos
Una capa de personalización XSL que indique la hoja de estilo CSS a utilizar Crear las hojas de estilo CSS
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

La capa de personalización
<?xml version='1.0' ?>
Hardy Beltran Monasterios • www.hardy.com.bo

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <!-- Uso de una hoja de estilo CSS --> <xsl:param name="html.stylesheet" select="'docbook.css'"/> <xsl:param name="html.stylesheet.type">text/css</xsl:param> <!-- Referencia a la hoja de estilo estandar DocBook XSL --> <xsl:import href="/usr/share/sgml/docbook/xslstylesheets/xhtml/docbook.xsl"/> <!-- Parametros TOC --> <xsl:param name="toc.section.depth">2</xsl:param> <xsl:param name="section.autolabel" select="1"/> </xsl:stylesheet>

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Extracto docbook.css
body {
Hardy Beltran Monasterios • www.hardy.com.bo

font-size: 0.9em; font-family: bitstream vera sans,sans-serif; margin: 30px; padding: 0; background-color: #ffffff; } pre.screen { font-size: 1.15em; padding: 10px; border: 1px solid #bbb; margin: 0.5em 2em; background-color: #fbfbfb; } i.replaceable { color: blue; }

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

¿ Necesita saber más ?
Hardy Beltran Monasterios • www.hardy.com.bo

Hay dos libros que cubren ampliamente DocBook XML/SGML y DocBook XSL
DocBook: The Definitive Guide Norman Walsh and Leonard Muellner http://www.docbook.org DocBook XSL: The Complete Guide Bob Stayton http://www.docbook.org

Hay versiones impresas y para leer en línea (HTML)
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Conclusiones
Hardy Beltran Monasterios • www.hardy.com.bo

DocBook llama la atención por dos cualidades importantes
Se puede generar varios formatos desde una sola fuente Los documentos estructurados abren la posibilidad de crear sistemas avanzados de búsqueda de información

Cada día las herramientas en Linux maduran más y la adopción de DocBook se extiende.
V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Referencias
OASIS - http://www.oasis-open.org
Hardy Beltran Monasterios • www.hardy.com.bo

Sitio de Norman Walsh - http://nwalsh.com NXML mode - http://www.thaiopensource.com/nxml-mode/ VIM - http://www.lodestar2.com/software/docbook/vimrc Conglomerate - http://www.conglomerate.org Procesadores XSLT libxslt/xsltpro - http://xmlsoft.org/XSLT/ Saxon - http://saxon.sourceforge.net/ Apache Xalan - http://xml.apache.org Script xmlto - http://cyberelk.net/tim/xmlto/

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

Referencias
Hardy Beltran Monasterios • www.hardy.com.bo

(continuación)

Repositorio Abierto DocBook http://docbook.sourceforge.net/docs.html Procesadores FO Apache FOP

-

http://xml.apache.org/fop

PassiveTex - http://www.tei-c.org.uk/Software/passivetex/ Recursos sobre XML http://www.ibiblio.org/xml/ http://www.xmlto.com

V Congreso Nacional de Software Libre y GNU/Linux • Agosto 2005 • Cochabamba, Bolivia

¿ Preguntas ?
Esta presentación y los ejemplos puede encontrarlos en http://www.hardy.com.bo/seminarios/