Cómo insertar imágenes en DocBook

Mientras preparaba un documento en DocBook me encontré con un problema bastante desconcertante.

Intentaba insertar una imagen en formato PNG y simplemente no aparecía en el documento generado.

Al principio supuse que el problema estaba en las rutas de los archivos o en la estructura del proyecto. Después de revisar varias veces terminé descartando esa posibilidad. En mi caso el inconveniente desapareció al utilizar imágenes JPEG.

Afortunadamente la conversión resulta muy sencilla utilizando convert, la herramienta incluida en ImageMagick.

convert imagen.png imagen.jpg

Una vez convertida la imagen, pude incluirla en el documento utilizando un objeto multimedia como el siguiente.

<mediaobject>
    <imageobject>
        <imagedata
            fileref="img/compilador-1-2.jpg"
            format="JPEG"
            scale="20"
            align="center"/>
    </imageobject>

    <imageobject>
        <imagedata
            fileref="img/compilador-1-2.eps"
            format="EPS"/>
    </imageobject>
</mediaobject>

En este ejemplo se incluyen dos versiones de la misma imagen.

La primera corresponde al formato JPEG, utilizada durante la generación habitual del documento.

La segunda es una versión EPS, que puede ser utilizada por algunas herramientas de publicación que trabajan mejor con formatos vectoriales o PostScript.

Si te encuentras con un problema similar al mío y las imágenes PNG simplemente no aparecen en el resultado final, vale la pena probar primero convirtiéndolas a JPEG antes de seguir buscando otras causas.