3. Local (document specific) graphics
Prev Chapter 4. Customization Next

oXygen XML Editor

3. Local (document specific) graphics

The next group of graphics are those which are specific to a particular docbook document. I.e. they are not common to all docbook documents. I'd go so far as to say that even if a graphic is shared between a small number of documents it may be kept locally with each document rather than stored in /styles. I'll assume that all XML docbook sources are stored in <here>, some directory somewhere on your disk. As the document is built up and graphics or images (photographs, gifs, tifs etc) are added, they are collated in an immediate sub-directory <here>/graphics. That way they they are all in a known (relative) position and many be collected for uploading to the website (or anywhere else) by the build script.

[Caution]Look out

In order that the files may be viewed and found, the source XML will have such as

 <imageobject>
    <imagedata fileref="graphics/pig.gif" format="GIF"/>
  </imageobject>

which is an accurate, relative file position. Only when the html is viewed the graphic will be in <here>/html/graphics, a directory relative to the html file! Be aware of this.

So, how is this done? Initially, using Apache ant. The sequence is:

run an xslt stylesheet which trawls through the docbook xml source looking for any referenced images (simple search for elements imagedata or graphic (@@FIXME, complete the list) in the docbook 5 namespace. That causes a simple copy command which ant understands to be output. Above and below this (in XML document order), are the top and tail of a file which together form an (almost) complete ant build script. What are missing are the variables used in the main build script. In order to bring these into use (don't re-invent the wheel), this script must be called from the main build script. That way all the variables are inherited. So the actual task, in the main build script is a sequence of two parts. Firstly this xslt task
Then an ant task, i.e. calling an ant sub-task, with the build file just created, which by default inherits all the calling tasks variables, which is just what is needed.

As an example of what is built, below is the ant file built for this example


 <?xml version="1.0" encoding="utf-8"?><!--
This is part of an ant build file for use with  
docbook v5 rng schema and stylesheets.
It is imported into build.xml

for use with the Apache resolver classes 
Revision: 1.0
Date    : 2009-05-12T11:45:52Z
Author  : DaveP
To work with ant 1.7 and new resolver from Apache

Built as part of a small tutorial. 
Copyright Dave Pawson 2009


Note: Variable validation uses:

 <property name="prop.message" 
   value="must be defined, preferably in ${{basedir}}/${{properties.file}}!"/>
 <fail message="VariableName ${{prop.message}}" unless="VariableName"/>
 Outputs a message and fails if the variable is undefined
 This is an imported file called from build.xml        
      -->
<project name="copyimages" basedir="." default="copy">
   <description>Copy images from local, document specific directory, to
  the target directory</description>
   <property file="build.properties"/>
   <target name="copy">
      <property name="prop.message" value="must be defined, preferably in ${basedir}/${properties_file}!"/>
      <fail message="global_styles ${prop.message}" unless="global_styles"/>
      <property name="prop.message" value="must be defined, preferably in ${basedir}/${properties_file}!"/>
      <fail message="local_graphics_src ${prop.message}" unless="local_graphics_src"/>
      <property name="prop.message" value="must be defined, preferably in ${basedir}/${properties_file}!"/>
      <fail message="local_graphics_html_tgt ${prop.message}" unless="local_graphics_html_tgt"/>
      <echo>Delete images in ${local_graphics_html_tgt}</echo>
      <delete>
         <fileset dir="${local_graphics_html_tgt}" includes="**/*"/>
      </delete>
      <echo>Copying CSS stylesheet ${css_stylesheet} to ${out_dir}/dpawson.css</echo>
      <copy file="${css_stylesheet}" tofile="${out_dir}/dpawson.css"/>
      <echo>Copying local images from ${local_graphics_src} to ${local_graphics_html_tgt}</echo>
      <copy todir="${out_html_dir}" verbose="true">
         <fileset dir="${basedir}">
            <include name="graphics/pig.gif"/>
         </fileset>
      </copy>
   </target>
</project> 

As you can see, only one image is found, graphics/pig.gif, which is included right at the back of this file, simply as an example to be found! That file results in a command to ant to copy it to the html/graphics directory, ready for use locally, or to be copied to wherever the main html output is going.

The next step is to run the ant task. This is done within the main build.xml file, as part of the task 'listimages'. It is a simple line:

  <!--  Now run the ant task from here. Must pick up these global variables -->
<ant antfile="${imagelist.anttask}" target="copy"/>

This calls on ant to run, with the build script obtained from the variable imagelist.anttask, which is the file created by the XSLT task, and to run the (only) task within that build script, which is named copy. A little messy, but it works. Once run, all local (to this document) graphics are ready for use with the html files. Just remember where they are relative to the html though!

I think that's it, unless you think I've forgotten something?

Prev Up Next
2. Principles Home 4. The Oasis XML catalog