Post History

Source: https://writers.stackexchange.com/a/33716
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/33716
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

For the book I am currently writing, which is not written in docbook directly but is written in a markup that will be translated to DocBook for publishing, I use an XML file to capture metadata for each illustration.

    <?xml version="1.0" encoding="UTF-8"?>
    <image>
        <source>assemble.svg</source>
        <fo>
            <href>assemble.svg</href>
            <contentwidth>4.25in</contentwidth>
            <align>center</align>
        </fo>
        <epub>
            <href>assemble.png</href>
        </epub>
        <alt>
            <p>A diagram showing multiple pieces being combined in different ways to produce different outputs.</p>
        </alt>
    </image>

Because the book will be published to both paper and ebook, we need different file formats for each graphic. Here the source graphic is `assemble.svg` and the same file is used for print (`fo` means xsl-fo). But for epub, which does not support SVG, we use `assemble.png`. The XML also provide an `alt` for the graphic and lets you include sizing information as well.

When I include a graphic in the book, the include instruction actually points to the XML file rather than the graphic file directly. The processing code then reads the XML file and generates conditional DocBook markup for use with each version of the book build.

This approach gets around any difficulties with including metadata in the graphic files themselves and allows you a level of abstraction that will let you use different file formats for different media.

Something similar should be workable for your builds. It will simply require either some preprocessing of your source files or some additional rules for processing graphics.

The downside of pointing to the XML file rather than the graphic is that the graphic will not show in a graphical XML editor. But there is a way round this. Rather than pointing to the XML file in the source, point to a graphic file as normal, but rewrite the processing code for the include instruction to strip off the graphic file extension and read an XML file of the same name in the same directory.

Original score: 2