Está en la página 1de 69

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
Comenzado con DocBook
Hardy Beltran Monasterios • www.hardy.com.bo

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
Manuales de usuario
Hardy Beltran Monasterios • www.hardy.com.bo

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 ?
Es un sistema para escribir documentos
estructurados en SGML o XML
Hardy Beltran Monasterios • www.hardy.com.bo

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
Creado en 1991 por HaL Computer
Systems y O'Reilly & Associates
Hardy Beltran Monasterios • www.hardy.com.bo

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
Varias distribuciones de Linux
Hardy Beltran Monasterios • www.hardy.com.bo

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 ?
El autor se concentra en el contenido y
no en el aspecto del documento
Hardy Beltran Monasterios • www.hardy.com.bo

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
Inicialmente su aprendizaje es lento
Hardy Beltran Monasterios • www.hardy.com.bo

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
FO PDF
Hardy Beltran Monasterios • www.hardy.com.bo

XML

Procesador DVI
XSLT PassiveTex

XSL

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
Clara tendencia a XMLizar el mundo ;-)
Hardy Beltran Monasterios • www.hardy.com.bo

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
DocBook instalado en su sistema
Hardy Beltran Monasterios • www.hardy.com.bo

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
Emacs es un poderoso editor de textos
Hardy Beltran Monasterios • www.hardy.com.bo

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
apt-get install docbook-xml docbook-xsl
Hardy Beltran Monasterios • www.hardy.com.bo

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
Define la estructura, elementos y
atributos de un documento DocBook
Hardy Beltran Monasterios • www.hardy.com.bo

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
Norman Walsh mantiene las hojas de
estilo estándar
Hardy Beltran Monasterios • www.hardy.com.bo

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
libxsl/xsltproc – escrito en C, originalmente
Hardy Beltran Monasterios • www.hardy.com.bo

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
apt-get install xmlto
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Hardy Beltran Monasterios • www.hardy.com.bo

<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>
...
...

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


Secciones de un artículo
Un documento tipo artículo puede estar
formado de varias secciones:
Hardy Beltran Monasterios • www.hardy.com.bo

...
<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
Una sección es una división lógica del
contenido del documento
Hardy Beltran Monasterios • www.hardy.com.bo

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
Todas las marcas DocBook XML se
deben escribir en minúsculas
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para referirse a una aplicación
gráfica o texto.
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para hacer cita una referencia
externa.
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para referirse al ejecutable de
una aplicación, a una orden o una
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para mostrar mensajes que
aparecen en la pantalla. Por ejemplo:
Hardy Beltran Monasterios • www.hardy.com.bo

<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
Ejemplo:
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para mostrar ejemplos
acompañados de un título
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para hacer referencia a
nombres de archivo o directorios.
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Use si quiere incluir una figura que
tenga un título y una breve descripción
Hardy Beltran Monasterios • www.hardy.com.bo

<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>
Se usa para insertar una nota al pie de
página
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para mostrar una palabra o
frase en un idioma diferente al del
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para mostrar información breve
que no requiere un orden específico
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Para mostrar una lista de ítemes cuyo
orden tiene importancia
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Para mostrar una lista de términos y
definiciones con sus descripciones
Hardy Beltran Monasterios • www.hardy.com.bo

<variablelist>
<varlistentry>
<term>Servidor X</term>
<listimtem>
<para>Ofrece las operaciones básicas de...</para>
</listimtem>
</varlistentry>
<varlistentry>
<term>Servidor de Letras X</term>
<listimtem>
<para>Provee los tipos de letras...</para>
</listimtem>
</varlistentry>
...
</variablelist>

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


Lista simple <simplelist>
Se usa principalmente para crear una
lista contenida en una tabla
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para indicar una opción de una
determinada orden
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Esta marca se emplea alrededor de
cualquier párrafo simple.
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Sólo use marcas <para> alrededor de
párrafos simples únicamente
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa para mostrar un indicador
(prompt).
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Se usa indicar que el lector debe
remplazar el texto mostrado de manera
Hardy Beltran Monasterios • www.hardy.com.bo

adecuada a su situación
Ejemplo:
Los módulos del núcleo se encuentran en el directorio
<filename>/lib/modules/<replaceable>versión-de-
núcleo</replaceable>/</filename>

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


Marca <screen>
Se usa para mostrar listado de
programas, contenido de archivos o
Hardy Beltran Monasterios • www.hardy.com.bo

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>
La marca y el contenido deben estar
justificados a la izquierda
Hardy Beltran Monasterios • www.hardy.com.bo

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"/>
Hardy Beltran Monasterios • www.hardy.com.bo

<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>

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=...
Hardy Beltran Monasterios • www.hardy.com.bo

<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>

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


Marca <userinput>
Se usa para indicar lo que el usuario
debe escribir.
Hardy Beltran Monasterios • www.hardy.com.bo

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>
Use para hacer referencia a otra
sección o capítulo del documento
Hardy Beltran Monasterios • www.hardy.com.bo

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
DB=/usr/share/xml/docbook/stylesheet/nwalsh
Hardy Beltran Monasterios • www.hardy.com.bo

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
El archivo inicial es «index.html»
Hardy Beltran Monasterios • www.hardy.com.bo

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
Generar documento FO desde XML
Hardy Beltran Monasterios • www.hardy.com.bo

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
Las herramientas libres para generar
PDF no están del todo maduras
Hardy Beltran Monasterios • www.hardy.com.bo

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
Muchos autores de DocBook usan la
herramienta XEP
Hardy Beltran Monasterios • www.hardy.com.bo

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
Una ventaja de las hojas de estilo XSL
es su flexible personalización (uso de
Hardy Beltran Monasterios • www.hardy.com.bo

«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
Significa que se crea una capa de
personalización con todos los cambios
Hardy Beltran Monasterios • www.hardy.com.bo

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' ?>

<xsl:stylesheet
Hardy Beltran Monasterios • www.hardy.com.bo

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/xsl-
stylesheets/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
Basta con usar nuestra hoja de estilo
en lugar de la hoja de estilo estándar
Hardy Beltran Monasterios • www.hardy.com.bo

Usando nuestro procesador XSLT


xsltproc -o ejemplo-mixsl.html miestilo_1.xsl
ejemplo.xml
Para ver el resultado abrimos ejemplo-
mixsl.html en el navegador

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


Usando CSS con HTML/XHTML
Para mejorar la calidad de presentación
de los documentos HTML/XHTML
Hardy Beltran Monasterios • www.hardy.com.bo

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' ?>

<xsl:stylesheet
Hardy Beltran Monasterios • www.hardy.com.bo

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/xsl-
stylesheets/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 {
font-size: 0.9em;
font-family: bitstream vera sans,sans-serif;
Hardy Beltran Monasterios • www.hardy.com.bo

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 ?
Hay dos libros que cubren ampliamente
DocBook XML/SGML y DocBook XSL
Hardy Beltran Monasterios • www.hardy.com.bo

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
DocBook llama la atención por dos
cualidades importantes
Hardy Beltran Monasterios • www.hardy.com.bo

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
Sitio de Norman Walsh - http://nwalsh.com
Hardy Beltran Monasterios • www.hardy.com.bo

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 (continuación)
Repositorio Abierto DocBook
http://docbook.sourceforge.net/docs.html
Hardy Beltran Monasterios • www.hardy.com.bo

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/

También podría gustarte