Construya un libro digital con EPUB

El formato abierto de eBook basado en XML

¿Necesita distribuir documentos, crear un eBook o simplemente archivar sus publicaciones de blog favoritas? EPUB es una especificación abierta para libros digitales basada en tecnologías conocidas como XML, CSS, XHTML y archivos EPUB que pueden leerse en dispositivos e-ink portátiles, teléfonos móviles y computadoras de escritorio. Este tutorial explica en detalles el formato EPUB, demuestra la validación de EPUB utilizando la tecnología Java y avanza paso a paso a través de la automatización de la creación de EPUB usando DocBook y Python.

05 de febrero de 2009 - Como seguimiento a los comentarios de lectores, el autor revisó el contenido del Listado 3 y actualizó el archivo epub-raw-files.zip (ver Descargas).

27 de abril de 2010 - Actualizó el archivo epub-raw-files.zip (ver Descargas).

03 de junio de 2010 - A solicitud del autor, revisó el contenido de los Listados 3 y 8. También actualizó el archivo epub-raw-files.zip (ver Descargas).

11 de enero de 2011 - A solicitud del autor, revisó el contenido del Listado 5. Cambió la segunda línea del código, de <item id="ncx" href="toc.ncx" media-type="text/xml"/>; a <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>.

12 de julio de 2011 - Como seguimiento a los comentarios de lectores, revisó el contenido del Listado 14. Eliminó el carácter ` próximo al final de la primera línea del código de <?xml version="1.0" encoding="utf-8"?`>. El código revisado ahora se lee como: <?xml version="1.0" encoding="utf-8"?>.

Liza Daly, Software Engineer and Owner, Threepress Consulting Inc.

Photo of Liza DalyLiza Daly es una ingeniera de software especializada en aplicaciones para la industria editorial. Ha sido desarrolladora líder de los principales productos online de Oxford University Press, O'Reilly Media y otras editoras. Actualmente se desempeña como consultora independiente y es la fundadora de Threepress, un proyecto de fuente abierta para el desarrollo de aplicaciones de ebook.



18-06-2012

Antes de comenzar

Este tutorial lo guía a través de la creación de eBooks en el formato EPUB. EPUB es un formato basado en XML, orientado a los desarrolladores y que emerge como el estándar de hecho para los libros digitales. Pero EPUB no es solo para libros: Con él, usted puede:

  • Empaquetar documentos para lectura offline o fácil distribución
  • Paquetes de publicaciones de blog u otros contenidos web nativos
  • Desarrollar, buscar y volver a mezclar utilizando herramientas de fuentes abiertas

Acerca de este tutorial

Acrónimos de uso frecuente

  • API: application programming interface
  • CSS: Cascading stylesheets
  • DOM: Document Object Model
  • DTD: Document type definition
  • GUI: Graphical user interface
  • HTML: Hypertext Markup Language
  • SAX: Simple API For XML
  • W3C: World Wide Web Consortium
  • XHTML: Extensible HTML
  • XML: Extensible Markup Language

Usted empieza este tutorial generando manualmente un libro EPUB para ayudarle a conocer todos los componentes y archivos necesarios. A continuación, el tutorial muestra cómo empaquetar el libro digital terminado y validarlo contra la especificación, así como la manera de probarlo en diferentes sistemas de lectura.

A continuación, trata de cómo generar EPUB a partir de DocBook XML—uno de los estándares más ampliamente utilizado para documentación técnica—y cómo utilizar Python para automatizar completamente la creación de EPUB con DocBook de punta a punta.

Objetivos

En este tutorial, usted va a:

  • Aprender lo que EPUB es, quién está detrás de él, y quién lo está adoptando
  • Explorar la estructura de un paquete EPUB, incluyendo sus esquemas y archivos necesarios
  • Crear un archivo EPUB válido desde el principio con contenido sencillo
  • Utilizar herramientas de fuente abierta para producir archivos EPUB desde DocBook, un esquema ampliamente utilizado para documentación técnica y libros
  • Automatizar la conversión de EPUB utilizando Python y DocBook

Prerrequisitos

No se supone ningún sistema operativo en particular para este tutorial, aunque usted debe estar familiarizado con la mecánica de creación de archivos y directorios. Se recomienda el uso de un editor de XML o un entorno de desarrollo integrado (IDE).

Para las últimas secciones del tutorial sobre cómo automatizar la creación de EPUB, este tutorial supone que usted cuenta con una o más habilidades básicas de procesamiento de XML—XSLT, DOM o análisis basado en SAX—y sobre cómo construir un documento XML utilizando un API nativo basado en XML.

No es necesario estar familiarizado con el formato de archivo EPUB para completar este tutorial.

Requerimientos de sistema

Para completar los ejemplos de este tutorial, necesita un intérprete Java (versión 1.5 o posterior) y un intérprete Python (versión 2.4 o posterior) así como las bibliotecas XML necesarias para cada uno. No obstante, los desarrolladores con experiencia deben estar capacitados para adaptar los ejemplos a cualquier lenguaje de programación con bibliotecas XML.


Acerca del formato EPUB

Conozca la base de EPUB, en qué se utiliza más comúnmente y cómo EPUB difiere del Portadle Document Format (PDF).

¿Qué es EPUB?

EPUB es el formato XML para libros digitales y publicaciones "reflowable" estandarizado por International Digital Publishing Forum (IDPF), una asociación comercial y de estándares para la industria editorial digital. IDPF adoptó oficialmente el EPUB en octubre del 2007, y en el 2008 vio la rápida adopción por los principales editores. Usted puede leer el formato EPUB utilizando una variedad de software de fuente abierta y comercial en todos los principales sistemas operativos, dispositivos e-ink, como el Sony PRS y dispositivos pequeños, como el iPhone de Apple.

¿Quién produce EPUB? ¿Es solo para libros?

Aunque los editores tradicionales fueron los primeros en adoptar EPUB, nada en el formato limita su uso a los eBooks. Con las herramientas de software disponibles gratuitamente, usted puede empaquetar páginas web como EPUB, convertir archivos de texto plano o transformar documentación DocBook XML existente en EPUB bien formado y válido. (Voy a tratar de lo último en Desde el DocBook al EPUB.)

¿Cómo EPUB difiere del PDF?

PDF es el formato de documento electrónico más ampliamente utilizado en el mundo. Desde el punto de vista de la editorial de un libro, PDF tiene varias ventajas:

  • Los archivos PDF permiten perfecto control de pixeles sobre el diseño, incluyendo diseños de fácil impresión complejos como múltiples columnas y estilos alternativos de anverso y reverso.
  • Los archivos PDF pueden ser generados por una amplia variedad de herramientas de documentos basados ​​en GUI, como Microsoft ® Office Word o Adobe® InDesign®.
  • Los lectores de PDF son ubicuos y se instalan en la mayoría de las computadoras modernas.
  • Fuentes específicas se pueden incorporar en el PDF para controlar el resultado final con exactitud.

Tres estándares en uno

EPUB se compone de tres especificaciones de IDPF separadas, aunque en la práctica es seguro referirse a ella colectivamente como EPeUB:

  • Open eBook Publication Structure Container Format (OCF): Especifica la estructura de árbol de directorio y el formato de archivo (ZIP) de un archivo EPUB.
  • Open Publication Structure (OPS): Define los vocabularios comunes para el eBook, especialmente los formatos que se permite utilizar para el contenido del libro (por ejemplo, XHTML y CSS).
  • Open Packaging Format (OPF): Describe los metadatos necesarios y opcionales, orden de lectura y tabla de contenidos en un EPUB.

Además, EPUB reutiliza otros estándares, como XHTML versión 1.0 y Digital Accessible Information SYstem (DAISY), para tipos específicos de contenidos en el archivo EPUB.

Desde el punto de vista de un desarrollador de software, PDF dista mucho de lo ideal:

  • No es un estándar trivial para aprender; por lo tanto, no es una simple cuestión de lanzar juntos su propio código de generación de PDF.
  • Aunque PDF ahora es un estándar de la International Organization for Standardization (ISO) (ISO 32000-1:2008), tradicionalmente ha sido controlado por una sola corporación: Adobe Systems.
  • Aunque las bibliotecas PDF están disponibles para la mayoría de los lenguajes de programación, muchas son comerciales o están incorporadas en aplicaciones GUI y no son fácilmente controladas por los procesos externos. No todas las bibliotecas gratuitas son mantenidas activamente.
  • El texto nativo de PDF se puede extraer y buscar mediante programación, pero pocos archivos PDF están etiquetados de modo que la conversión a un formato web fácil sea sencilla o confiable.
  • Los documentos PDF no son fácilmente "reflowable", lo que significa que no se adaptan bien a pantallas pequeñas o a cambios radicales en sus diseños.

Porqué EPUB es fácil para los desarrolladores

EPUB aborda todas las fallas en el PDF en relación a la facilidad de los desarrolladores. Un EPUB es un archivo simple en formato ZIP (con una extensión .epub ) que contiene archivos ordenados de una manera prohibida. Existen algunos requerimientos difíciles sobre cómo preparar el archivo ZIP, que se discutirán en detalle más adelante en Empaquetar su archivo EPUB como un archivo ZIP. Aparte de eso, EPUB es sencillo:

  • Casi todo en EPUB es XML. Los archivos EPUB pueden construirse utilizando kits de herramientas XML estándar sin ningún software especial o propietario.
  • El contenido EPUB (el texto real de un eBook) casi siempre es XHTML versión 1.1. (Un formato alternativo es DTBook, un estándar para la codificación de libros para los discapacitados visuales. Consulte Recursos para más información sobre DTBook, que no se trata en este tutorial).
  • La mayoría de los esquemas XML de EPUB se toman de las especificaciones existentes, publicadas y disponibles gratuitamente.

Los dos puntos claves son que los metadatos EPUB están en XML y el contenido EPUB está en XHTML. Si su sistema de desarrollo de documentación genera una salida para la web o se basa en XML, está muy cerca de también poder producir EPUB.


Desarrollo de su primer EPUB

Un paquete EPUB con mínima conformidad tiene varios archivos necesarios. La especificación puede ser bastante rigurosa sobre el formato, contenido y ubicación de los archivos en el archivo EPUB. Esta sección explica lo que usted debe saber al trabajar con el estándar EPUB.

Anatomía de un paquete EPUB

La estructura básica de un archivo EPUB mínimo sigue el patrón del Listado 1. Cuando esté lista para su distribución, esta estructura de directorio se empaqueta en un archivo de formato ZIP, con algunos requerimientos especiales discutidos en Empaquetar su archivo EPUB como un archivo ZIP.

Listado 1. Diseño de archivos y directorios para un archivo EPUB sencillo
mimetype
META-INF/
   container.xml
OEBPS/
  content.opf
  title.html
  content.html
  stylesheet.css
  toc.ncx
  images/
     cover.png

Nota: Una muestra de libro que sigue este patrón se encuentra disponible en Descargas, sin embargo recomiendo que cree uno propio a medida que avance en el tutorial.

Para empezar a desarrollar su libro EPUB, cree un directorio para el proyecto EPUB. Abra un editor de texto o un IDE como Eclipse. Recomiendo utilizar un editor que cuente con un modo XML—en particular, uno que pueda validarse contra los esquemas Relax NG listados en Recursos.

El archivo mimetype

Esto es muy fácil: El archivo mimetype es necesario y debe ser denominado mimetype. Los contenidos del archivo siempre son:

application/epub+zip

Note que el archivo mimetype no puede contener líneas nuevas ni retornos de carro.

Además, el archivo mimetype debe ser el primer archivo en el archivo ZIP y no debe estar comprimido. Usted va a ver cómo incluirlo utilizando argumentos ZIP comunes, en Empaquetar su archivo EPUB como un archivo ZIP. Por ahora, solo cree este archivo y sálvelo, asegurándose de que esté en el nivel de raíz de su proyecto EPUB.

META-INF/container.xml

En el nivel de raíz del EPUB, debe existir un directorio META-INF que debe contener un archivo denominado container.xml. Los sistemas de lectura de EPUB buscarán en primer lugar este archivo ya que apuntan a la ubicación de los metadatos para el libro digital.

Crear un directorio denominado META-INF. En él, abra un nuevo archivo llamado container.xml para escritura. El archivo container es muy pequeño, pero sus requerimientos de estructura son rigurosos. Pegue el código en el Listado 2 en META-INF/container.xml.

Listado 2. Ejemplo de archivo container.xml
<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
  <rootfiles>
    <rootfile full-path="OEBPS/content.opf"
     media-type="application/oebps-package+xml" />
  </rootfiles>
</container>

El valor de full-path (en negrita) es la única parte de este archivo que siempre variará. La ruta de acceso al directorio debe ser en relación a la raíz del propio archivo EPUB, no en relación al directorio META-INF.

Información adicional sobre META-INF

El directorio META-INF también puede contener algunos archivos opcionales. Estos archivos permiten a EPUB dar soporte a firmas digitales, cifrado, y a la administración de derechos digitales (DRM). Estos temas no son tratados en este tutorial. Para más información, consulte la especificación OCF.

Los archivos mimetype y container son los únicos cuyas ubicaciones en el archivo EPUB se controlan rigurosamente. Según lo recomendado (aunque no es obligatorio), almacene los archivos restantes en un subdirectorio del EPUB. (Por convención, esto se denomina OEBPS, for Open eBook Publication Structure, pero puede ser lo que desee.)

A continuación, cree el directorio denominado OEBPS en su proyecto EPUB. La siguiente sección de este tutorial trata de los archivos que van en OEBPS—la parte principal del libro digital: sus metadatos y sus páginas.

Archivo de metadatos de Open Packaging Format

Aunque este archivo puede tener cualquier nombre, el archivo OPF convencionalmente se denomina content.opf. Especifica la ubicación de todo el contenido del libro, desde su texto hasta otros medios como las imágenes. También apunta a otro archivo de metadatos, la tabla de contenidos Navigation Center eXtended (NCX).

El archivo OPF es el metadato más complejo en la especificación EPUB. Crear el archivo OEBPS/content.opf, y pegar los contenidos del Listado 3 en él.

Listado 3. Archivo de contenidos OPF con muestra de metadatos
<?xml version='1.0' encoding='utf-8'?>
<package xmlns="http://www.idpf.org/2007/opf"
            xmlns:dc="http://purl.org/dc/elements/1.1/"
            unique-identifier="bookid" version="2.0">
  <metadata>
    <dc:title>Hello World: My First EPUB</dc:title>
    <dc:creator>My Name</dc:creator>
    <dc:identifier
id="bookid">urn:uuid:0cc33cbd-94e2-49c1-909a-72ae16bc2658</dc:identifier>
    <dc:language>en-US</dc:language>
    <meta name="cover" content="cover-image" />
  </metadata>
  <manifest>
    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
    <item id="cover" href="title.html" media-type="application/xhtml+xml"/>
    <item id="content" href="content.html"
media-type="application/xhtml+xml"/>
    <item id="cover-image" href="images/cover.png" media-type="image/png"/>
    <item id="css" href="stylesheet.css" media-type="text/css"/>
  </manifest>
  <spine toc="ncx">
    <itemref idref="cover" linear="no"/>
    <itemref idref="content"/>
  </spine>
  <guide>
    <reference href="title.html" type="cover" title="Cover"/>
  </guide>
</package>

Esquemas y espacio de nombres OPF

El propio documento OPF debe utilizar el espacio de nombres http://www.idpf.org/2007/opf, y los metadatos deberán estar en el espacio de nombres Dublin Core Metadata Initiative (DCMI), http://purl.org/dc/elements/1.1/.

Este es el momento apropiado para añadir el esquema OPF y DCMI a su editor XML. Todos los esquemas que se usan en EPUB están disponibles en Descargas.

Metadatos

Dublin Core define un conjunto de términos comunes de metadatos que se pueden utilizar para describir una amplia variedad de materiales digitales; no forma parte de la especificación EPUB en sí. Cualquiera de estos términos son permitidos en la sección de metadatos OPF. Al desarrollar su EPUB para distribución, incluya aquí todo el detalle que pueda, aunque el extracto proporcionado en el Listado 4 es suficiente para empezar.

Listado 4. Extracto de metadatos OPF
...
<metadata>
  <dc:title><b>Hello World: My First EPUB</b></dc:title>
  <dc:creator>My Name</dc:creator>
  <dc:identifier id="bookid"><b>urn:uuid:12345</b></dc:identifier>
  <meta name="cover" content="cover-image" />
</metadata>
...

Los dos términos que se requieren son title y identifier. De acuerdo con la especificación EPUB, el identificador debe ser un valor único, aunque es el creador de libro digital quien define ese valor único. Para los editores de libros, este campo normalmente contiene un número ISBN o de la Biblioteca del Congreso. Para otros creadores EPUB, considere el uso de un URL o un ID único de usuario (UUID) generado aleatoriamente y de tamaño grande. Observe que el valor del atributo unique-identifier debe coincidir con el atributo ID del elemento dc:identifier .

Otros metadatos para considerar añadir, si es pertinente para su contenido, incluyen:

  • Idioma (como dc:language).
  • Fecha de publicación (como dc:date).
  • Editorial (como dc:publisher). (Esto puede ser su empresa o nombre de persona.)
  • Información de Copyright (como dc:rights). (Si el release de la obra es bajo licencia de Creative Commons, ponga aquí el URL de la licencia.)

Consulte Recursos para información adicional sobre DCMI.

Incluir un elemento meta con el atributo de nombre que contenga la portada no es parte de la especificación de EPUB directamente, pero es el método recomendado para hacer las portadas e imágenes más portátiles. Algunos presentadores EPUB prefieren usar un archivo de imagen como portada, mientras que otros utilizan un archivo XHTML que contiene una imagen insertada de la portada. Este ejemplo ilustra ambas maneras. El valor del atributo contenido del elemento meta debería ser el ID de la imagen de la portada del libro en el manifiesto, que es la parte siguiente del archivo OPF.

Manifiesto

El manifiesto OPF lista todos los recursos encontrados en el EPUB que forman parte del contenido (y excluye los metadatos). Esto normalmente significa una lista de archivos XHTML que componen el texto del eBook, además de una cantidad de medios relacionados, como las imágenes. EPUB recomienda el uso de CSS para dar estilo a contenido del libro, por lo que también se incluyen archivos CSS en el manifiesto. Todos los archivos que van en su libro digital deben estar listados en el manifiesto.

El Listado 5 ilustra la sección extraída del manifiesto.

Listado 5. Extracto del manifiesto OPF
...
<manifest>
  <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
  <item id="cover" href="title.html" media-type="application/xhtml+xml"/>
  <item id="content" href="content.html" media-type="application/xhtml+xml"/>
  <item id="cover-image" href="images/cover.png" media-type="image/png"/>
  <item id="css" href="stylesheet.css" media-type="text/css"/>
</manifest>
...

Manifiesto OPF avanzado

Una muestra más avanzada de un archivo de manifiesto incluirá varios archivos XHTML, así como imágenes y un CSS. Obtenga un EPUB completo con ejemplos de tipos comunes desde Descargas.

Debe incluir el primer elemento, toc.ncx (discutido en la sección siguiente). Observe que todos los elementos tienen un valor apropiado de media-type y que el media-type para el contenido XHTML es application/xhtml+xml. Se requiere exactamente este valor y no puede ser text/html o algún otro tipo.

EPUB da soporte a cuatro formatos de archivos de imagen, como tipos principales: Joint Photographic Experts Group (JPEG), Portable Network Graphics (PNG), Graphics Interchange Format (GIF) y Scalable Vector Graphics (SVG). Usted puede incluir tipos de archivos que no reciben soporte si proporciona un retroceso a un tipo principal. Consulte la especificación OPF para información adicional sobre elementos de retroceso.

Los valores de los atributos href deben corresponder a un Uniform Resource Identifier (URI) que se relacione al archivo OPF. (Esto fácilmente se confunde con la referencia al archivo OPF en el archivo container.xml, donde debe estar en relación con el EPUB como un todo.) En este caso, el archivo OPF está en el mismo directorio OEBPS como su contenido, entonces aquí no se requiere información de ruta.

Espina dorsal

Aunque el manifiesto le dice al lector EPUB qué archivos son parte del archivo, la espina dorsal indica el orden en que aparecen, o—en términos de EPUB,—el orden de lectura lineal del libro digital. Una manera de pensar la espina dorsal del OPF es que define el orden de las "páginas" del libro. La espina dorsal se lee en el orden del documento, de arriba a abajo. El Listado 6 ilustra un extracto del archivo OPF.

Listado 6. Extracto de espina dorsal OPF
...
<spine toc="ncx">
  <itemref idref="cover" linear="no"/>
  <itemref idref="content"/>
</spine>
...

Cada elemento itemref requiere un atributo idref, que debe coincidir con uno de los IDs del manifiesto. El atributo toc también se requiere. Hace referencia a un ID en el manifiesto que debe indicar el nombre del archivo de la tabla NCX de contenidos.

El atributo linear en la espina dorsal indica si el elemento se considera parte del orden de lectura lineal versus ser materia extraña delantera o al final. Recomiendo que defina cualquier página de portada como linear=no. De acuerdo al EPUB, los sistemas de lectura abren el libro en el primer elemento de la espina dorsal que No se ha definido como linear=no.

Guide

La última parte del archivo OPF de contenido es la sección guide. Esta sección es opcional pero se recomienda. El Listado 7 ilustra un extracto de una sección guide de un archivo.

Listado 7. Extracto de una sección guide de un archivo OPF
...
<guide>
  <reference href="cover.html" type="cover" title="Cover"/>
</guide>
...

La sección guide es una manera de proveer información semántica a un sistema de lectura EPUB. Mientras que el manifiesto define los recursos físicos en el EPUB y la espina dorsal provee información sobre su orden, la sección guide explica lo que las secciones significan. Aquí se presenta una lista parcial de los valores que se permiten en la sección guide de OPF:

  • cover: La portada del libro
  • title-page: Una página con información del autor y de la editorial
  • toc: La tabla de contenidos

Para una lista completa, consulte la especificación OPF 2.0, disponible en Recursos.

Tabla NCX de contenidos

Sobreposición entre metadatos NCX y OPF

Debido a que NCX ha sido tomado de otro estándar, hay cierta sobreposición entre la información codificada en el NCX y en el OPF. Esto rara vez es un problema al generar EPUBs mediante programación, donde el mismo código puede enviar resultados a dos archivos diferentes. Tenga cuidado de poner la misma información en ambos lugares, ya que diferentes lectores EPUB pueden utilizar los valores de uno o de otro.

Aunque el archivo OCF se define como parte del propio EPUB, el último archivo de metadatos importante ha sido tomado de un diferente estándar de libro digital. DAISY es un consorcio que desarrolla formatos de datos para lectores que no pueden utilizar libros tradicionales, a menudo debido a deficiencias visuales o a incapacidad para manipular obras impresas. EPUB ha tomado prestado NCX DTD de DAISY. El NCX define la tabla de contenidos del libro digital. En libros complejos, normalmente es jerárquica y contiene piezas anidadas, capítulos y secciones.

Utilizando el editor XML, crear OEBPS / toc.ncx, e incluir el código en el Listado 8.

Listado 8. Archivo NCX sencillo
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
                 "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">
  <head>
    <meta name="dtb:uid"
content="urn:uuid:0cc33cbd-94e2-49c1-909a-72ae16bc2658"/>
    <meta name="dtb:depth" content="1"/>
    <meta name="dtb:totalPageCount" content="0"/>
    <meta name="dtb:maxPageNumber" content="0"/>
  </head>
  <docTitle>
    <text>Hello World: My First EPUB</text>
  </docTitle>
  <navMap>
    <navPoint id="navpoint-1" playOrder="1">
      <navLabel>
        <text>Book cover</text>
      </navLabel>
      <content src="title.html"/>
    </navPoint>
    <navPoint id="navpoint-2" playOrder="2">
      <navLabel>
        <text>Contents</text>
      </navLabel>
      <content src="content.html"/>
    </navPoint>
  </navMap>
</ncx>

Metadatos NCX

El DTD requiere cuatro elementos meta dentro del NCX <head> tag:

  • uid: Es el ID único para el libro digital. Este elemento debe coincidir con el dc:identifier en el archivo OPF.
  • depth: Corresponde al nivel de jerarquía en la tabla de contenidos. Este ejemplo solo tiene un nivel, por lo tanto este valor es 1.
  • totalPageCount y maxPageNumber: Se aplica solo a libros en papel y puede dejarse en 0.

El contenido de docTitle/text es el título del libro, y coincide con el valor de dc:title en el OPF.

NCX navMap

¿Cuál es la diferencia entre el NCX y la espina dorsal OPF?

Es normal confundirse, ya que ambos archivos describen el orden y los contenidos del documento. La manera más sencilla de explicar la diferencia es a través de la analogía con un libro impreso: La espina dorsal OPF describe cómo las secciones del libro están físicamente unidas entre sí, de modo que al dar vuelta la página al final de un capítulo se revela la primera página del segundo capítulo. El NCX describe la tabla de contenidos al comienzo del libro. La tabla de contenidos incluye siempre todas las secciones principales del libro, pero también podría enumerar subsecciones que no se producen en sus propias páginas.

Una buena regla es que el NCX a menudo contiene más elementos navPoint que los elementos itemref existentes en la espina dorsal OPF. En la práctica, todos los elementos en la espina dorsal aparecen en el NCX, pero el NCX puede ser más detallado que la espina dorsal.

La sección navMap es la parte más importante del archivo NCX, ya que define la tabla de contenidos del libro actual. La sección navMap contiene uno o mas elementos navPoint . Cada sección navPoint debe contener los siguientes elementos:

  • Un atributo playOrder , que corresponde al orden de lectura del documento. Esto sigue el mismo orden que la lista de elementos itemref en la espina dorsal OPF.
  • Un elemento navLabel/text , que describe el título para esta sección del libro. Esto normalmente es un título o número de capítulo, como "Capítulo Uno", o—como en este ejemplo—"Página de portada".
  • Un elemento content cuyo atributo src apunta al recurso físico que incluye el contenido. Este será un archivo declarado en el manifiesto OPF. (También es aceptable utilizar aquí identificadores de fragmentos para apuntar a los anclajes en el contenido XHTML—por ejemplo, content.html#footnote1.)
  • Opcionalmente, uno o más elementos navPoint hijos. Puntos anidados son cómo los documentos jerárquicos se expresan en el NCX.

La estructura del libro de muestra es sencilla: Tiene solo dos páginas que no están anidadas. Esto significa que tendrá dos elementos navPoint con valores playOrder ascendentes, que empiezan en 1. En el NCX, usted tiene la oportunidad de denominar estas secciones, lo que permite a los lectores saltar a diferentes partes del eBook.

Añadir el contenido final

Ahora usted conoce todos los metadatos que se requieren en EPUB, entonces es el momento de incluir el contenido del libro real. Usted puede usar la muestra de contenido suministrado en Descargas o crear su propio contenido, siempre que los nombres de los archivos coincidan con los metadatos.

A continuación, cree estos archivos y carpeta:

  • title.html: Este archivo será la página título del libro. Cree este archivo e incluya un elemento img que haga referencia a una imagen de portada, con el valor del atributo src equivalente a images/cover.png.
  • images: Cree esta carpeta dentro de OEBPS, en seguida copie la imagen de muestra (o cree una propia), denominándola cover.png.
  • content.html: Este será el texto real del libro.
  • stylesheet.css: Ponga este archivo en el mismo directorio OEBPS en el que están los archivos XHTML. Este archivo contiene las declaraciones CSS que le gusten, como configurar el color del texto o font-face. Consulte el Listado 10 para un ejemplo de un archivo CSS.

XHTML y CSS en un libro EPUB

El Listado 9 contiene un ejemplo de una página EPUB de contenido válido. Utilice esta muestra para su página de título (title.html) y una similar para la página de contenido principal (content.html) de su libro.

Listado 9. Muestra de página de título (title.html)
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Hello World: My First EPUB</title>
    <link type="text/css" rel="stylesheet" href="stylesheet.css" />
  </head>
  <body>
    <h1>Hello World: My First EPUB</h1>
    <div><img src="images/cover.png" alt="Title page"/></div>
  </body>
</html>

El contenido XHTML en EPUB sigue algunas reglas que pueden parecerle desconocidas desde un punto de vista del desarrollo web en general:

  • El contenido debe validarse como XHTML 1.1: La única diferencia significativa entre XHTML 1.0 Strict y XHTML 1.1 es que el atributo name ha sido eliminado. (Utilice IDs para referirse a las anclas dentro del contenido.)
  • Los elementos img solo pueden hacer referencia a imágenes que sean locales para el eBook: Los elementos no pueden hacer referencia a imágenes en la web.
  • Los bloques de script deben evitarse: No hay requerimientos para que los lectores EPUB den soporte al código JavaScript.

Existen algunas pequeñas diferencias en la manera como EPUB da soporte a CSS, pero ninguna que afecte a los usos comunes de estilos (consulte la especificación OPS para más detalles). El Listado 10 ilustra un archivo CSS sencillo que puede aplicar al contenido para establecer directrices básicas de fuentes y pintar encabezados de rojo.

Listado 10. Estilos de muestra para el eBook (stylesheet.css)
body {
  font-family: sans-serif;     
}
h1,h2,h3,h4 {
  font-family: serif;     
  color: red;
}

Un punto interesante es que EPUB específicamente da soporte a CSS 2 Regla @font-face , que permite fuentes incorporadas. Si usted crea documentación técnica, esto probablemente no es relevante, pero los desarrolladores de EPUBs en varios idiomas o para dominios especializados apreciarán la capacidad de especificar datos exactos de fuentes.

Ahora usted dispone de todo lo necesario para crear su primer libro EPUB. En la sección siguiente, usted empaquetará el libro de acuerdo a las especificaciones OCF y descubrirá la manera de validarlo.


Empaquetar y revisar su EPUB

En este punto, usted debería tener un lote de EPUB listo para empaquetar. Este paquete podrá ser un nuevo libro creado por usted mismo o uno que utiliza los archivos primarios disponibles en Descargas.

Empaquetar su archivo EPUB como un archivo ZIP

La parte OEBPS Container Format de la especificación EPUB tiene bastante que decir sobre EPUB y ZIP, pero lo más importante es:

  • El primer archivo en el fichero debe ser el archivo mimetype (consulte Mimetype es este tutorial). El archivo mimetype no debe estar comprimido. Esto permite a los recursos no ZIP descubrir el mimetype al leer los bytes sin formato a partir de la posición 30 en el paquete EPUB.
  • El archivo ZIP no se debe cifrar. EPUB da soporte al cifrado excepto en nivel de archivos ZIP.

Al utilizar ZIP versión 2.3 en un sistema operativo tipo UNIX,®cree el archivo ZIP de EPUB en dos comandos, como en el Listado 11. (Estos comandos suponen que el directorio de trabajo actual es su proyecto EPUB.)

Listado 11. Empaquetar el EPUB en un archivo epub+zip válido
$ zip -0Xq  my-book.epub mimetype
$ zip -Xr9Dq my-book.epub *

En el primer comando se crea el nuevo archivo ZIP y se añade el archivo mimetype no comprimido. En el segundo, se añaden los demás elementos. Las banderas -X y -D minimizan la información extraña en el archivo .zip; -r incluirá de manera repetitiva los contenidos de META-INF y directorios OEBPS.

Validación de EPUB

Aunque el estándar EPUB no es especialmente difícil, sus archivos XML deben validarse según esquemas específicos. Si utiliza un editor XML compatible con esquemas para generar los metadatos y XHTML, aquí usted está a más de la mitad del camino. Haga una revisión final con el paquete EpubCheck (consulte Recursos).

Adobe mantiene el paquete EpubCheck que se encuentra disponible como fuente abierta bajo licencia de Berkeley Software Distribution (BSD). Es un programa Java que puede ejecutarse como una herramienta autónoma o como una aplicación web, o puede integrarse a una aplicación que se ejecute en Java Runtime Environment (JRE) versión 1.5 o posterior.

Ejecutarla desde la línea de comandos es sencillo. El Listado 12 ofrece un ejemplo.

Listado 12. Ejecutando la herramienta EpubCheck
$ java -jar /path/to/epubcheck.jar my-book.epub

Si no ha podido crear algunos archivos auxiliares o introdujo un error en los archivos de metadatos, puede recibir un mensaje de error como el del Listado 13.

Listado 13. Errores de muestra de EpubCheck
my-book.epub: image file OEBPS/images/cover.png is missing
my-book.epub: resource OEBPS/stylesheet.css is missing
my-book.epub/OEBPS/title.html(7): 'OEBPS/images/cover.png': 
     referenced resource missing in the package

Check finished with warnings or errors!

Es posible que necesite configurar su variable CLASSPATH aquí para apuntar a la ubicación de la instalación EpubCheck, ya que tiene algunas bibliotecas externas para importar. Probablemente necesita configurar la variable CLASSPATH si recibe un mensaje como:

org.xml.sax.SAXParseException: no implementation available for schema language 
   with namespace URI "http://www.ascc.net/xml/schematron"

Si la validación se realiza correctamente, usted verá "No errors or warnings detected". En ese caso, ¡felicitaciones por producir su primer EPUB!

Visualización de EPUB

Las pruebas no son solo sobre la validación: Se trata también de asegurarse de que el libro parezca correcto. ¿Funcionan correctamente las hojas de estilo? ¿Están las secciones realmente en el orden lógico correcto? ¿Incluye el libro todo el contenido esperado?

Varios lectores de EPUB se encuentran disponibles para realizar pruebas. La Figura 1 muestra una captura de pantalla de Adobe Digital Editions (ADE), el lector de EPUB más comúnmente utilizado.

Figura 1. El EPUB en ADE
El EPUB en ADE

Sus fuentes de colores y las imágenes aparecen, lo que es bueno. ADE no presenta correctamente el título en una fuente sans serif, aunque puede ser un problema con el CSS. Es útil aquí comprobar en otro lector. La Figura 2 muestra el mismo libro presentado en mi fuente abierta, lector de EPUB basado en web, Bookworm.

Figura 2. El EPUB en Bookworm
El EPUB en Bookworm

En este caso, es solo que ADE no da soporte a esa declaración en particular. Saber las peculiaridades del software de lectura individual es esencial si el formato exacto es importante en su libro digital.

Ahora que que ha completado, desde el inicio, el laborioso proceso de creación de un EPUB sencillo, vea lo que se necesita para convertir DocBook, un esquema XML común de documentación, a EPUB.


Desde el DocBook al EPUB

DocBook es una opción popular para los desarrolladores que necesitan mantener documentación técnica de formato largo. A diferencia de los archivos generados por los programas tradicionales de procesamiento de texto, usted puede administrar las salidas de DocBook con sistemas de control de versión basados en texto. Debido a que DocBook está en formato XML, usted fácilmente puede transformarlo en múltiples formatos de salida. Desde el verano de 2008, usted puede encontrar soporte nativo de EPUB como formato de salida desde el proyecto oficial de DocBook XSL.

Ejecución del proceso básico DocBook a EPUB con XSLT

Se inicia con un documento DocBook sencillo, en el Listado 14. Este documento se define como tipo book e incluye un prefacio, dos capítulos y una imagen insertada que se exhibe en la página de título. Esta imagen se encuentra en el mismo directorio que el archivo fuente DocBook. Cree usted mismo este archivo y la imagen de la página de título, o descargue muestras desde Descargas.

Listado 14. Un libro DocBook sencillo
<?xml version="1.0" encoding="utf-8"?>  
<book>
  <bookinfo>
    <title>My EPUB book</title>
    <author><firstname>Liza</firstname>
            <surname>Daly</surname></author>
    <volumenum>1234</volumenum>
  </bookinfo>
  <preface id="preface">  
    <title>Title page</title>
    <figure id="cover-image">
      <title>Our EPUB cover image icon</title>
      <graphic fileref="cover.png"/>
    </figure>
  </preface>
  <chapter id="chapter1"> 
    <title>This is a pretty simple DocBook example</title>
    <para>
      Not much to see here. 
    </para>
  </chapter>
  <chapter id="end-notes"> 
    <title>End notes</title>
    <para>
      This space intentionally left blank.
    </para>

A continuación, acceda a Recursos para descargar la última versión de las hojas de estilo DocBook XSL y asegúrese de que tiene instalado un procesador XSLT como xsltproc o Saxon. Este ejemplo utiliza xsltproc, que se encuentra disponible en la mayoría de los sistemas tipo UNIX. Para convertir el archivo DocBook, simplemente ejecute ese archivo contra el módulo EPUB incluido en DocBook XSL, como en el Listado 15.

Listado 15. Conversión de DocBook a EPUB
$ xsltproc /path/to/docbook-xsl-1.74.0/epub/docbook.xsl docbook.xml
Writing OEBPS/bk01-toc.html for book
Writing OEBPS/pr01.html for preface(preface)
Writing OEBPS/ch01.html for chapter(chapter1)
Writing OEBPS/ch02.html for chapter(end-notes)
Writing OEBPS/index.html for book
Writing OEBPS/toc.ncx
Writing OEBPS/content.opf
Writing META-INF/container.xml

Personalizar DocBook XSL

El proceso de conversión de DocBook a EPUB aún es relativamente nuevo, y puede que necesite personalizar el XSLT para conseguir el resultado deseado.

A continuación, añada el archivo mimetype y genere usted mismo el archivo epub+zip. El Listado 16 muestra los tres comandos rápidos y el resultado de una pasada a través del validador EpubCheck

Listado 16. Creando el archivo EPUB a partir de DocBook
$ echo "application/epub+zip" > mimetype
$ zip -0Xq  my-book.epub mimetype
$ zip -Xr9D my-book.epub *
$ java -jar epubcheck.jar my-book.epub 
No errors or warnings detected

¡Muy fácil! La Figura 3 muestra su creación en ADE.

Figura 3. DocBook EPUB convertido en ADE
DocBook EPUB convertido en ADE

Conversión automática DocBook a EPUB con Python y lxml

El XSL DocBook recorre un largo camino para generar el EPUB sin dificultades, pero usted debe realizar algunos pasos fuera del XSLT En esta última sección se muestra un ejemplo de programa Python que completa la creación de un paquete EPUB válido. Yo muestro métodos individuales en el tutorial; usted puede obtener el programa docbook2epub.py completo desde Descargas.

Varias bibliotecas de Python XSLT es encuentran disponibles, pero mi preferencia es lxml. Ofrece no sólo funcionalidad XSLT 1.0, sino también análisis de alto desempeño, soporte completo de XPath 1.0, y extensiones especiales para el manejo de HTML. Si prefiere una biblioteca diferente o utilizar un lenguaje de programación diferente de Python, esos ejemplos deben ser de fácil adaptación.

Llamando el DocBook XSL con lxml

El método más eficiente para llamar XSLT mediante lxml es analizar el XSLT por adelantado, a continuación, crear un transformador para uso repetido. Esto es útil, ya que mi script de DocBook a EPUB acepta varios archivos DocBook para convertir. El Listado 17 ilustra este método.

Listado 17. Ejecutando el DocBook XSL mediante lxml
import os.path
from lxml import etree

def convert_docbook(docbook_file):
    docbook_xsl = os.path.abspath('docbook-xsl/epub/docbook.xsl')
    # Give the XSLT processor the ability to create new directories
    xslt_ac = etree.XSLTAccessControl(read_file=True, 
                                      write_file=True, 
                                      create_dir=True, 
                                      read_network=True, 
                                      write_network=False)
    transform = etree.XSLT(etree.parse(docbook_xsl), access_control=xslt_ac)
    transform(etree.parse(docbook_file))

El módulo EPUB en DocBook XSL crea los propios archivos de salida, así nada se devuelve desde la evaluación de la transformación aquí. En su lugar, DocBook crea dos carpetas (META-INF y OEBPS) en el directorio de trabajo actual que contienen los resultados de la conversión.

Copiando las imágenes y otros recursos en el archivo

DocBook XSL no hace nada acerca de las imágenes que usted puede proporcionar para utilización con su documento; solo crea los archivos de metadatos y el XHTML presentado. Debido a que la especificación EPUB requiere que todos los recursos sean enumerados en el manifiesto content.opf, usted puede inspeccionar el manifiesto para buscar las imágenes a las que se hace referencia en el archivo DocBook original. El Listado 18 muestra esta técnica, que supone que la variable path contiene la ruta a su EPUB en curso, como creado por el DocBook XSLT.

Listado 18. Análisis del archivo de contenido OPF para descubrir los recursos que faltan
import os.path, shutil
from lxml import etree

def find_resources(path='/path/to/our/epub/directory'):
    opf = etree.parse(os.path.join(path, 'OEBPS', 'content.opf'))

    # All the opf:item elements are resources
    for item in opf.xpath('//opf:item', 
                          namespaces= { 'opf': 'http://www.idpf.org/2007/opf' }):

        # If the resource was not already created by DocBook XSL itself, 
        # copy it into the OEBPS folder
        href = item.attrib['href']
        referenced_file = os.path.join(path, 'OEBPS', href):
        if not os.path.exists(referenced_file):
            shutil.copy(href, os.path.join(path, 'OEBPS'))

Creando automáticamente el archivo mimetype

DocBook XSL no va a crear su archivo mimetype, tampoco, pero un pedacito de código desde el Listado 19 puede encargarse de eso.

Listado 19. Crear el archivo mimetype
def create_mimetype(path='/path/to/our/epub/directory'):
    f = '%s/%s' % (path, 'mimetype')
    f = open(f, 'w')
    # Be careful not to add a newline here
    f.write('application/epub+zip')
    f.close()

Creando el paquete EPUB con Python

Lo único que falta ahora es empaquetar los archivos en un archivo ZIP EPUB válido. Esto requiere dos pasos: añadir el archivo mimetype como el primero en el archivo sin compresión, a continuación, agregar los directorios restantes. El Listado 20 muestra el código para este proceso.

Listado 20. Utilizar el módulo zipfile de Python para crear un paquete EPUB
import zipfile, os

def create_archive(path='/path/to/our/epub/directory'):
    '''Create the ZIP archive.  The mimetype must be the first file in the archive 
    and it must not be compressed.'''

    epub_name = '%s.epub' % os.path.basename(path)

    # The EPUB must contain the META-INF and mimetype files at the root, so 
    # we'll create the archive in the working directory first and move it later
    os.chdir(path)    

    # Open a new zipfile for writing
    epub = zipfile.ZipFile(epub_name, 'w')

    # Add the mimetype file first and set it to be uncompressed
    epub.write(MIMETYPE, compress_type=zipfile.ZIP_STORED)
    
    # For the remaining paths in the EPUB, add all of their files
    # using normal ZIP compression
    for p in os.listdir('.'):
        for f in os.listdir(p):
            epub.write(os.path.join(p, f)), compress_type=zipfile.ZIP_DEFLATED)
    epub.close()

¡Eso es todo! No olvide validar.


Resumen

El script de Python en la sección anterior es sólo un primer paso para automatizar completamente cualquier tipo de conversión de EPUB. Por razones de brevedad, no maneja muchos casos comunes, como rutas arbitrariamente anidadas, hojas de estilo, o fuentes incorporadas. Los partidarios de Ruby pueden consultar dbtoepub, incluida en la distribución de DocBook XSL, para un enfoque similar en ese lenguaje.

Debido a que EPUB es un formato relativamente joven, muchas rutas de conversión útiles aún esperan ser creadas. Afortunadamente, casi todos los tipos de marcado estructurado, como reStructuredText o Markdown, tienen procesos que ya producen HTML o XHTML; la adaptación para producir EPUBs debería ser bastante sencilla, especialmente mediante los scripts DocBook-to-EPUB Python o Ruby como una guía.

Debido a que EPUB es mayormente ZIP y XHTML, hay pocas razones para no distribuir paquetes de documentación como archivos EPUB en lugar de simples archivos .zip. Los usuarios con lectores EPUB se benefician de la tabla automática de contenidos y metadatos adicionales, pero aquellos que no lo tienen sencillamente pueden tratar el archivo EPUB como un archivo ZIP normal y ver el contenido XHTML en un navegador. Se debe considerar añadir el código de generación de EPUB a cualquier tipo de sistema de documentación, como Javadoc o Perldoc. EPUB ha sido diseñado para documentación de longitud de libro, por lo que es un formato de distribución perfecto para la creciente cantidad de libros de programación online o en curso.


Descargas

DescripciónNombretamaño
Resources to build the EPUB in this tutorialepub-raw-files.zip8KB
DocBook to EPUB tools1docbook-to-epub.zip7KB

Nota

  1. Este archivo .zip contiene el archivo de muestra DocBook XML, que se ilustra en el tutorial, y un script docbook2epub.py completo. Usted debe descargar lxml y el DocBook XSL separadamente; ver los enlaces en Recursos.

Recursos

Aprender

Obtener los productos y tecnologías

  • EpubCheck: EpubCheck de Adobe es una valiosa herramienta para la creación de EPUB. Descárguela y ejecútela como un programa autónomo, una aplicación web o como una biblioteca (se requiere Java versión 1.5 o posterior).
  • DocBook XSL: Descargue la última versión de las hojas de estilo para el procesamiento de DocBook en EPUB. El paquete DocBook XSL también incluye un script de Ruby para el procesamiento de un archivo EPUB completo, similar al script de Python que se ilustra en este tutorial.
  • lxml: Si no la tiene instalada actualmente, lxml es la más completa biblioteca XML disponible para Python. Para más información sobre lxml, consulte el artículo del autor High-performance XML parsing in Python with lxml (Liza Daly, developerWorks, octubre de 2008).
  • Adobe Digital Editions y Bookworm: Para probar EPUB, los e-readers que siguen más de cerca la especificación son ADE, una aplicación de escritorio entre plataformas, y Bookwork, el e-reader del autor basado en la web, que utiliza el navegador para la presentación de EPUB.
  • Software IBM de prueba para evaluación de producto: Desarrolle su próximo proyecto con software de evaluación de IBM, disponible para descarga directamente desde developerWorks, incluyendo herramientas de desarrollo de aplicaciones y productos middleware desde DB2®, Lotus®, Rational®, Tivoli® y WebSphere®.

Comentar

Comentarios

developerWorks: Ingrese

Los campos obligatorios están marcados con un asterisco (*).


¿Necesita un IBM ID?
¿Olvidó su IBM ID?


¿Olvidó su Password?
Cambie su Password

Al hacer clic en Enviar, usted está de acuerdo con los términos y condiciones de developerWorks.

 


La primera vez que inicie sesión en developerWorks, se creará un perfil para usted. La información en su propio perfil (nombre, país/región y nombre de la empresa) se muestra al público y acompañará a cualquier contenido que publique, a menos que opte por la opción de ocultar el nombre de su empresa. Puede actualizar su cuenta de IBM en cualquier momento.

Toda la información enviada es segura.

Elija su nombre para mostrar



La primera vez que inicia sesión en developerWorks se crea un perfil para usted, teniendo que elegir un nombre para mostrar en el mismo. Este nombre acompañará el contenido que usted publique en developerWorks.

Por favor elija un nombre de 3 - 31 caracteres. Su nombre de usuario debe ser único en la comunidad developerWorks y debe ser distinto a su dirección de email por motivos de privacidad.

Los campos obligatorios están marcados con un asterisco (*).

(Por favor elija un nombre de 3 - 31 caracteres.)

Al hacer clic en Enviar, usted está de acuerdo con los términos y condiciones de developerWorks.

 


Toda la información enviada es segura.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=90
Zone=WebSphere
ArticleID=821187
ArticleTitle=Construya un libro digital con EPUB
publish-date=06182012