De LaTeX a EPUB. Parte 1.

En relación a la composición de textos con notación matemática, mi objetivo en el pasado ha sido que los documentos creados cumplieran de forma estricta los estándares disponibles, MathML y EPUB; dejando a los usuarios, la responsabilidad de hacerse con las herramientas de software adecuadas para su visualización y lectura.

Como ya he comentado en alguna otra entrada, se trata de un objetivo harto infructuoso, puesto que apenas existen herramientas de software que permitan leer correctamente los documentos así creados.

Va ser necesario cambiar de estrategia y abordar la creación de documentos científicos de forma más flexible respecto de los estándares.

  1. Por un lado, no exigiremos que el contenido matemático esté expresado en MathML (el estándar WEB), bastará que esté formulado en cualquier formato admitido por la especificación EPUB: imágenes de las fórmulas, formulas en LaTeX junto con MathJax, etc.
  2. No vamos a exigir que el documento esté diseñado estrictamente conforme a la especificación: vamos a permitirnos ciertas licencias, siempre que, a la hora de verificarlo, éstas se traduzcan sólo en Warnings; con que no haya errores de validación será suficiente.
  3. Puesto que LaTeX es el estándar (aunque no reconocido oficialmente) para la escritura de documentos científicos, es preferible que el documento original de partida esté redactado en formato LaTeX, o, que al menos, las fórmulas matemáticas estén escritas en dicho formato.

Introducción

Para ser lo más coherente posible con esta nueva metodología, creo que es conveniente adoptar el enfoque más conservador: el objetivo va a ser que los documentos creados sean prácticamente compatibles con cualquier ebook reader que soporte mínimamente los formatos EPUB 2 Y EPUB 3. Para ello se utilizarán las herramientas más comunes y accesibles para la transformación de los documentos LaTeX, y los formatos con mayor soporte para la representación del contenido matemático.

Las aplicaciones empleadas para realizar la transformación van a ser Tex4ht, Make4ht y Tex4ebook. Los formatos para las fórmulas matemáticas serán imágenes SVG, plantillas CSS y librerías javascript (como MathJax o KaTeX).

En esta primera parte, vamos a presentar el comando principal de Tex4ht, sus opciones y algunos ejemplos típicos para transformar los documentos LaTeX a HTML. La segunda parte se centrará en los archivos de configuración y el comando \Configure para Tex4ht. La parte tres estará dedicada a la herramienta Make4ht, un sistema de compilación para Tex4ht, que proporciona una mayor capacidad y flexibilidad. Y, por último, en la cuarta parte se describirá el uso de Tex4ebook para construir, finalmente, el documento EPUB.

Las principales distribuciones LaTeX, MikTeX para Windows y TexLive para Linux, incluyen el paquete Tex4ht para la conversión a formatos basados en SGML (como HTML, XHTML o DocBook, ...).

Por desgracia, la documentación que se puede encontrar sobre éste paquete no es muy amigable ni lo suficientemente exhaustiva. Como introducción, recomiendo el tutorial sobre Tex4ht elaborado por Michal Hoftich (en el que yo me voy a basar para esta introducción) en lugar documentación oficial, que resulta un tanto áspera y anacrónica. Voy a intentar describir brevemente el funcionamiento del comando.

Tex4ht consiste en tres bloques de construcción básicos, junto con una serie de scripts que los enlazan conjuntamente. Los bloques son

  • Tex4ht.sty: archivo de estilo TeX que inserta códigos de salida configurados (como etiquetas HTML), dentro del archivo archivo DVI de salida. Tan sólo es necesario cargar dicho paquete en el preámbulo del documento LaTeX (mediante /usepackage{}), si existe la necesidad de insertar alguna etiqueta HTML de forma explícita; además, hay que tener en cuenta que si se carga el paquete, el compilado usual mediante pdflatex no se realizará de forma correcta.
  • Tex4ht: es un programa ejecutable, que extrae la información guardada en el archivo DVI, incluyendo texto y códigos de salida, y prepara archivos auxiliares para la conversión de imágenes y otras tareas. Aunque el sistema completo se denomina Tex4ht, este comando no puede ser ejecutado sobre un archivo LaTeX, sólo sobre archivos DVI.
  • t4ht: es el programa que convierte imágenes, genera el archivo CSS y ejecuta varios comandos solicitados en el archivo LaTeX.

Si se desea información más pormenorizada acerca de las diferentes etapas en el proceso de conversión, puede consultarse la documentación oficial.

Comando

Para no tener que ejecutar dichos comandos manualmente, y facilitarle la vida al usuario, existen una serie de scripts que agrupan todas estas tareas. El más destacado de tales scripts es el comando htlatex, que por defecto convierte los archivos LaTeX a HTML y se aplica de la siguiente forma:

$ htlatex <nombre-de-archivo.tex> "ops-1" "ops-2" "ops-3" "ops-4"

Cómo se puede ver, htlatex admite cinco parámetros de entrada; el único obligatorio es el primero, el que corresponde al nombre del archivo. Generalmente las opciones son encerradas entre comillas para que puedan ser pasadas literalmente a los comandos subyacentes (t4ht, pdflatex, ...).

El conjunto de opciones "ops-1" son para las plantillas de estilos tex4ht.sty y *.4ht (como ooffice.4ht, html-mml.4ht o article.4ht, por ejemplo) que se emplean en la primera etapa durante la creación del archivo DVI; cada uno de los campos de "ops-1" se deben separar con comas.

Con las "ops-2" y "ops-3" se especifican las opciones para los postprocesadores tex4ht, y t4ht respectivamente; finalmente el conjunto "ops-4" son opciones para LaTeX (para el comando pdflatex); cada campo de estos conjuntos de opciones se deberá separar mediante espacios, en lugar de mediante comas. Además, todas estas opciones son menos diversas y menos habituales que las correspondientes a "ops-1", por lo que no les vamos a dedicar ningún apartado independiente.

En la sección siguiente, listaré algunas de las opciones "ops-1" que considero más relevantes, o que podrían serlo si funcionaran correctamente; no pretende ser una relación exhaustiva, puesto que prefiero haber experimentado suficientemente con cada una de las opciones que describo, antes que limitarme a copiar la escueta explicación que se ofrece por parte del autor. Es posible especificar las opciones de "ops-1" cuando se carga (si se hace) el paquete Tex4ht en el preámbulo, mediante la instrucción \usepackage[ops-1]{tex4ht}. Hay que tener en cuenta que algunas opciones sólo funcionan con un determinado formato de salida del documento (xhtml, html, doc ...); otras simplemente no funcionan porque no quieren o se comportan de manera anómala; por último existen opciones para las que no he conseguido averiguar o entender cual es (o era) su objetivo, como hidden-ref, refcaption o index.

Para que se puedan ilustrar este tipo de dificultades, vamos a exponer un caso particular: por ejemplo, si se utilizan conjuntamente las opciones svg y html en el comando

$ htlatex prueba.tex "html,svg"

se producirá el siguiente error

(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/tex4ht.sty
--- needs --- tex4ht prueba ---
(./prueba.tmp) (./prueba.xref)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/html4.4ht)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/html4-math.4ht)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/svg.4ht)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/html4-svg.4ht)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/html4.4ht)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/html4-math.4ht)
(/usr/share/texlive/texmf-dist/tex/generic/tex4ht/svg.4ht
l.47 --- TeX4ht warning --- \Configure{@DOCTYPE}? ---
! LaTeX Error: Missing \begin{document} in `'.
See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.       
l.48   {<

Esto es debido a que las opciones html (HTML4) y svg son incompatibles; debe utilizarse svg con xhtml. No obstante, incluso haciéndolo de forma correcta, los resultados no solían ser los esperados: en versiones anteriores del software (hace ya unos cuantos años) el resultado no era muy convincente; en realidad la imagen no estaba diseñada en formato .svg, sino que (como se puede apreciar en la siguiente imagen) se trataba de una imagen PNG, embebida en un contenedor SVG, mediante una etiqueta <image>.

PNG embebido en SVG

Por tanto, se mantenía el mismo problema con la resolución y el dimensionado de las imágenes de las expresiones matemáticas. Para colmo, en versiones algo más recientes (texlive 2015-2016), esta característica no funcionaba debido a un bug con el paquete pstoedit que era el encargado de realizar la conversión a svg. Actualmente (versiones de texlive 2017 y posteriores), parece que han solventado el problema (como se puede ver en las imágenes siguientes), habiendo implementado otro sistema para crear las imágenes SVG mediante el paquete dvisvg.

Prueba SVG 1

Prueba SVG 2

Opciones para Tex4ht.sty

Aunque no existe una relación completa de dichas opciones, ni en la documentación oficial ni en la ayuda del comando, algunas de éstas son listadas en el archivo .log que se genera al ejecutar htlatex. Cómo se ha indicado más arriba el único parámetro requerido por el comando, es el nombre del archivo; y de esta forma, el formato de salida será HTML. Sin embargo si se va a especificar alguna opción para ops-1, entonces es obligado indicar, como primer parámetro dentro de las opciones, el tipo de documento de salida que se va a generar; de lo contrario, si por ejemplo se introduce el comando

$ htlatex prueba.tex "NoFonts,charset=utf-8,xhtml" " -cunihtf -utf8" \
"-d./tmp/"

producirá un error como el siguiente:

(/usr/share/texlive/texmf-dist/tex/generic/oberdiek/ifpdf.sty)
(/usr/share/texlive/texmf-dist/tex/generic/oberdiek/ifvtex.sty)
(/usr/share/texlive/texmf-dist/tex/generic/ifxetex/ifxetex.sty)))
! I can't find file `NoFonts.cfg'.
<to be read again> 
\relax
l.16 \begin{document}
(Press Enter to retry, or Control-D to exit)
Please type another input file name:

Opciones para el tipo de documento de salida:

  • html: El documento de salida tendrá formato HTML 4.
  • xhtml: El documento resultante seguirá la especificación XHTML.
  • xhtml,ooffice: El documento de salida estará en formato ODT.
  • xhtml,docbook: El documento de salida cumplirá la especificación DocBook.

  • xhtml,html5: Se formateará el encabezado cumpliendo la especificación HTML5, para el documento de salida. Esta opción se encuentra disponible en versiones más recientes de TeX4ht (TeX Live 2017 ya lo incorpora), aunque parece que todavía se encuentra en una estado algo precario.

    Cabecera en formato HTML4
    Cabecera en formato XHTML
    Cabecera en formato HTML5

Opciones para la composición y estructura del documento

  • <num>: Se indica la forma en que Tex4ht debe paginar, de forma automática, el texto por secciones: todo el texto en una página, cada sección en una página independiente, cada subsección en una página, etc. num debe ser un valor comprendido entre 1 y 7.
  • charset: Especifica la codificación de caracteres que se declarará en en la cabecera de la página HTML. Dicha codificación debe de concordar con la codificación con la que se crea el archivo y las fuentes adecuadas (que se pueden especificar en "ops-2" para t4ht), para evitar incorrecciones en el visualizado del documento por parte del navegador.
  • -css: No aplica la hoja de estilos css por defecto, que sí suele especificar cuando no se indica la opción.
  • css-in: No crea una hoja de estilos .css, y se inserta el código CSS necesario en la cabecera del documento .html.
  • NoFonts: Deshabilita, en todo el documento, la inserción automática de ciertas etiquetas <span> para la decoración del texto. Por ejemplo, algunas palabras con acento en español situadas en títulos, son separadas arbitraria e innecesariamente mediante etiquetas <span>; aunque no repercute en el visualizado de la página, a nivel de código resulta poco estético y nada apropiado. Sin embargo, esta opción NO se recomienda. Veremos cómo se puede solventar esta circunstancia en la segunda parte del artículo, mediante las Configuraciones.
  • font=<num>: En teoría debería cambia el tamaño por defecto de la fuente usada en el documento; no parece funcionar correctamente.
  • frames: Separa el contenido de la tabla de contenidos en dos marcos HTML diferentes.
  • frames-fn: Separa el contenido, la tabla de contenidos y el pié de página en tres marcos HTML diferentes.
  • html+: Formatea el código HTML de forma más estricta.
  • imgdir:<dir>: ¡Utilizado de forma aislada no funciona adecuadamente! Referencia las imágenes de las fórmulas matemáticas en el documento HTML, como si estuvieran en el subdirectorio dir; sin embargo las imágenes las sigue creando en el directorio raíz en el que se encuentra el documento latex, con lo que se producirá un error de visualizado.

  • info: Añade información adicional al archivo .log que se genera durante la ejecución de htlatex. No sólo añade detalles adicionales relativos a la transformación concreta que se acaba de realizar, sino que incorpora cierta documentación general y describe algunas de las opciones disponibles para el comando:

    [...]
Support for Sectioning Commands
-------------------------------

\Configure{unit-name} ......................4

   #1 start
   #2 end
   #3 before title
   #4 after title

   Example:

        \Configure{section}
           {\HCode{<section>}}    {\HCode{</section>}}
           {\HCode{<title>}}      {\HCode{</title>}}

\ConfigureMark{unit-name}...................1

   Defines a macro \<<unit-name>>HMark to hold the given argument.
   Upon entering the unit, \TitleMark gets the content of this macro.

   Some built-in configurations of TeX4ht require an argument for the
   \<<unit-name>>HMark commands. For safety, these commands should
   always be followed by a, possiblely empty, argument.  The argument
   should be a separator between the title mark and its content.

   Example:

        \Configure{section}
           {}{}
           {\HCode{ <h3> }\TitleMark\space}    {\HCode{ </h3> }}
        \ConfigureMark{section}{\thesection}
[...]

    Sin embargo, la opción info produce errores en combinación con otras de las opciones; por ejemplo, la siguiente instrucción dará como resultado un error:

    $ htlatex prueba.tex "xhtml,svg,charset=utf-8,info" " -cunihtf -utf8"

  • no-DOCTYPE: Elimina la declaración DOCTYPE de la cabecera del documento de salida.

  • no-VERSION: Elimina la instrucción <?xml version="..."?>, en caso de existir, del documento de salida.
  • nominitoc: No crea las minitablas de contenidos en las subsecciones, pero sí que mantiene la tabla de la página inicial.
  • sec-filename: En teoría, cuando se divide el documento en distintas páginas por secciones, el nombre empleado para los archivos se obtendría del título de las secciones, haciéndolo más agradable a la vista. No he conseguido hacerlo funcionar.
  • sections+: Crea, en los títulos de las secciones,links de vuelta a línea correspondiente de la tabla de contenidos.
  • TocLink: Crea enlaces en las entradas de las tablas de contenidos hacia las secciones/subsecciones. No tiene mucho sentido puesto que ya lo hace por defecto, tanto si en el archivo latex se ha utilizado \tableofcontents, como en las tablas de contenidos que crea si se divide el documento por secciones.

  • xml: Carga el espacio de nombres para el formato XHTML en la cabecera del documento HTML de salida; por ejemplo, si se utiliza la opción "html,xml", la cabecera del documento .html tendrá el aspecto siguiente

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html xml:lang="es" xmlns="http://www.w3.org/1999/xhtml"> 
[...]

    y htlatex formateará el código de forma más estricta, siguiendo la especificación XML. Sin embargo, obsérvese que no declara el tipo de documento como XHTML. Si el formato especificado era XHTML, mediante la opción "xhtml,xml", no se produce ningún cambio al incluir la opción xml.

Opciones para el formato de salida de las fórmulas matemáticas

  • svg, svg-: Extrae las imágenes de las fórmulas matemáticas en formato .svg en lugar de .png, en archivos de imagen aparte. Actualmente la diferencia entre ambas opciones radica en la forma en que las imágenes son incluidas en el código de la página HTML: mientras la opción svg incluye la imagen utilizando únicamente la etiqueta img de HTML, la opción svg- lo hace embebiéndola en la página mediante la etiqueta object, del siguiente modo:

    <object type="image/svg+xml"><img src="prueba0x.svg" class="par-math-display" /></object>

  • pic-m: Todas las fórmulas "inline" se transformarán en imágenes. Hay que tener en cuenta que, por defecto, Tex4ht parece que transforma el contenido matemático encerrado en los entornos \(...\) $$...$$ \[...\] en imágenes; sin embargo con las fórmulas matemáticas contenidas en el entorno $...$, sólo transforma en imágenes aquellas que son más complejas y no puede representar mediante HTML.

  • gif: Extrae las imágenes de las fórmulas matemáticas en formato gif.
  • jpg: Extrae las imágenes de las fórmulas matemáticas en formato jpg.

  • graphics-<num>: Permitiría indicar la calidad de los gráficos, donde el valor de num representaría la densidad de pixels de las imágenes "rasterizadas" de las fórmulas. No parece funcionar correctamente, de hecho especificando cualquier valor, por ejemplo graphics-300, en la salida de consola se puede leer siempre un párrafo como el siguiente

    System call: dvipng -T tight -D 144 -bg Transparent -pp 10:10 prueba.idv -o prueba8x.png
This is dvipng 1.15 Copyright 2002-2015 Jan-Ake Larsson

    lo que indica que dvipng siempre utiliza la misma densidad de píxeles para la imagen: 144.

  • mathml: Utiliza el estándar Presentation MathML 2.0 para representar las fórmulas matemáticas en el documento HTML.

Uso y Ejemplos

En primer lugar, Tex4ht registra un error cuando se utiliza el paquete babel con documentos configurados en español (¡y como no!, recuerdo que LaTeXML también tenía problemas con el paquete Babel para español). Se puede subsanar este error mediante la inserción del siguiente código (que obtuve de la página de Emilio Torres-Manzanera) en el preámbulo del documento .tex:

\makeatletter
\let\ifes@LaTeXe\iftrue
\makeatother

  • Documento HTML, en una sola página, con formato de imagen SVG para las fórmulas matemáticas:

    $ htlatex prueba.tex "xhtml,svg"

    Incidencias: htlatex transforma todas las fórmulas del entorno gather (utilizado ex profeso para juzgar sus capacidades) en una sola imagen SVG y la coloca en una columna de una tabla; sin embargo, las correspondientes numeraciones las coloca como texto en otra columna, de modo que no quedan alineadas.

    Alineación de la numeración de las formulas con el entorno gather

    Además, parece que por defecto htlatex utiliza la codificación ISO-8859-1.

    Codificación Iso por defecto

    Incidencias de este estilo son las que hacen imprescindible tener especial cuidado con el diseño del documento latex en el momento de su creación, si se tiene pensado exportarlo a formatos WEB. De lo contrario, puede ser necesario un tedioso reformateo previo del documento latex, antes de poder exportarlo.

  • Igual que el anterior pero con codificación utf-8:

    $ htlatex prueba.tex "xhtml,svg,charset=utf-8" " -cunihtf -utf8"

    Head utf-8

    Incidencias: Obsérvese que si sólo se especifica la codificación unicode para la cabecera del documento HTML (p.e mediante el comando htlatex prueba.tex "xhtml,svg,charset=utf-8"), y no se especifica para el archivo y las fuentes con que Tex4ht trabaja, se producirán errores de visualizado del documento final (ver figura posterior).

    Error utf-8

  • Documento HTML, separado en páginas por secciones, sin minitablas de contenido en las páginas de secciones, con formato PNG para las fórmulas matemáticas, y utilizando la codificación de caracteres utf-8:

    $ htlatex prueba.tex "html,2,nominitoc,charset=utf-8" " -cunihtf -utf8"

  • Documento XHTML, todo en una página, codificación utf-8 y formato MATHML para las fórmulas matemáticas:

    $ htlatex prueba.tex "xhtml,mathml,charset=utf-8" " -cunihtf -utf8"

    Incidencias: En esta ocasión alinea adecuadamente la numeración de las fórmulas matemáticas. Todas las fórmulas MATHML obtenidas se representan adecuadamente en Firefox, aunque como ya he indicado al comienzo del artículo, ésta quizás sea la representación que menos voy a utilizar por el momento.

    gather mathml

Referencias