Graphic Map Generation

The map-driven processing generates an Ant script that copies graphics or other resources from their source locations to the output location.

Because the map-driven processing allows you to change the output organization of the generated files, references to graphics and other resources in the source DITA XML do not translate directly to references in the output. To address this, the map-driven process finds all graphic references in the input data (including graphics referenced from DITAVAL files), constructs an input-to-output location map, and generates an Ant script that copies the source graphics to their output location. As part of output generation, references to graphics are rewritten to reflect their output location. This process can be extended to include any kind of resource, such as Javascript, CSS, static graphics, etc. However, it does not modify references in non-DITA files, such as CSS style sheets. (This is most useful for EPUB output. For HTML5 output there is a separate feature for managing all the Web-specific theme components.)

The graphic map generation is implemented in the module org.dita4publishers.common.xslt/xsl/map2graphicMap.xsl. You can extend the default processing to provide mapping for any graphics that are not represented by normal DITA markup, such as covers determined by run-time parameters or branding graphics defined separately or whatever.

The map generation is done in two phases.

The first phase is mode "get-graphic-refs", which is applied to the map, all topics, the OT-generated "image.list" file and the DITAVAL file, if specified. It results in a set of graphic reference elements of the form:

 <gmap:graphic-ref 
   href="{absoluteUrl of source graphic}" 
   filename="{filename of the graphic}"
 />

One <graphic-ref> element should be generated for each graphic reference in the source.

You can add additional graphic map items using the mode "additional-graphic-refs", which is applied to the root map. Templates in this mode must produce <gmap:graphic-ref> elements that point to the source location of the item to be included. See the templates in the map2epubEmbedFonts.xsl in the org.dita4publishers.epub plugin for example code.

You can override or extend the image.list processing using the mode "map2graphicmap:handleImageListFile". The context items for the templates in this mode are text nodes, one for each line of the image.list file. The result of a match on an image list item must be a <gmap:graphic-map-item> element that specifies the input and output URIs for the image. See the base template in map2graphicMap.xsl. You can use this mode to map source graphic filenames to some other name or to otherwise augment the set of graphics to copy based on details of the image list.

The second phase processes all the <graphic-ref> elements to determine the set of unique graphics used. This process results in the graphic map, which looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<gmap:graphic-map
  xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl"
  xmlns:gmap="http://dita4publishers/namespaces/graphic-input-to-output-map">
  <gmap:graphic-map-item
    input-url="/Users/ekimber/workspace_37/dita4publishers_0.9.19_clean/sample_data/flagging-test/ditavals/graphics/windows-icon.jpg"
    output-url="file:/Users/ekimber/workspace_37/dita4publishers_0.9.19_clean/sample_data/flagging-test/html5/images/windows-icon.jpg"
    id="d82e1"/>
  <gmap:graphic-map-item
    input-url="file:/Users/ekimber/workspace_37/dita4publishers_0.9.19_clean/sample_data/flagging-test/ditavals/graphics/windows-icon.jpg"
    output-url="file:/Users/ekimber/workspace_37/dita4publishers_0.9.19_clean/sample_data/flagging-test/html5/images/windows-icon-2.jpg"
    id="d82e2"/>
  <gmap:graphic-map-item
    input-url="file:/Users/ekimber/workspace_37/dita4publishers_0.9.19_clean/sample_data/flagging-test/ditavals/graphics/osx-icon.jpg"
    output-url="file:/Users/ekimber/workspace_37/dita4publishers_0.9.19_clean/sample_data/flagging-test/html5/images/osx-icon.jpg"
    id="d82e3"/>
</gmap:graphic-map>

The graphic map may then be passed as a parameter to subsequent processing and is used to generate the copy-graphics.xml Ant script (mode "generate-graphic-copy-ant-script" implemented in module org.dita4publishers.common.xslt/xsl/graphicMap2AntCopyScript.xsl).

Image URLs are rewritten during initial topic processing using the mode "href-fixup" implemented in the module org.dita4publishers.common.xslt/xsl/topicHrefFixup.xsl. URLs are rewritten to reflect the output location of the images so that the default HTML output processing will automatically construct the correct URL for the images.