DOCBOOK: Efficiently including images in DocBook

[Nik Clayton <nik@nothing-going-on.demon.co.uk>]

Hi chaps,

I'm looking for the best way to efficiently include images in DocBook,
preferably using Norm's stylesheets.  This *should* be a simple task,
but I'm bumping in to problems, some of which I think are part of the
way DocBook is currently designed.

Broadly speaking, I have three classes of image format to include, PNG,
EPS, and plain text.  PNG covers HTML and PDF output, EPS covers Postscript
output, and plain text is used for a special case where I know the end
user can not display images (text mode web browser, for example).

What I'm trying to do is define two parameter entities, %output.eps and
%output.png, which will be set to IGNORE or INCLUDE depending on what
image format I need.  A fragment of the DSSSL sheet using these is

    <!ENTITY output.eps "IGNORE">
    <!ENTITY output.png "IGNORE">

    ...

    <![ %output.eps; [ (define %graphic-default-extension% "eps") ]]> 
    <![ %output.png; [ (define %graphic-default-extension% "png") ]]>

Now, imagine that fig1.{eps,png} contains a picture of a box with an 'A'
in it.  What I'd like to write in my document is

   <mediaobject>
     <imageobject>
       <imagedata fileref="fig1">
     </imageobject>

     <textobject>
       <literallayout>
+-------+
|   A   |
+-------+
       </literallayout>
     </textobject>

     <textobject>
       <phrase>This will become the ALT text in the HTML</phrase>
     </textobject>
   </mediaobject>

This is simple to write, and easy to understand and teach to others.

Now what I'd expect to be able to do is

   jade -i output.eps -t tex ... > book.tex
   jade -i output.png -t sgml ... > book.html
   jade -t sgml ... | w3m -dump > book.txt

This almost works.  

Producing the HTML version correctly selects the .png image (as %output.png
is set to INCLUDE, so the .png extension is added to 'fig1').  The phrase
is used as the ALT text.

Producing the plain text version also works -- because 
%graphic-default-extension% isn't set the stylesheets ignore the imageobject
and put in the textobject instead.

Producing the postscript version doesn't work.  For some reason, although
fig1.eps exists in the same directory, the stylesheets don't use fig1.eps,
and instead use the contents of the textobject, so I get ASCII art in my
Postscript output.

From my reading of the documentation that comes with the stylesheets, this
is supposed to work, and I can't figure out why it isn't.

I tried an alternative method, where I include two imageobjects, but wrap
them with the parameter entities so that only one is visible to the processor
when the document is converted;

   <mediaobject>
     <![ %output.png; [
     <imageobject>
       <imagedata fileref="fig1.png" format="png">
     </imageobject>
     ]]>

     <![ %output.eps; [
     <imageobject>
       <imagedata fileref="fig1.eps" format="eps">
     </imageobject>
     ]]>

     <textobject>
       <literallayout>
+-------+
|   A   |
+-------+
       </literallayout>
     </textobject>

     <textobject>
       <phrase>This will become the ALT text in the HTML</phrase>
     </textobject>
   </mediaobject>

Again, this only partially works.  It works for HTML and Postscript, and
correctly selects the correct image to include.

However, it doesn't work for plain text, when both %output.png and 
%output.eps are set to "IGNORE".  This is because DocBook mandates that
mediaobject contains one of {audio,video,image}object, and I then have
a mediaobject that only contains textobjects.

I can work around this by customising the DTD like so;

<!ENTITY % mediaobject.element "IGNORE">
<!ELEMENT MediaObject - - (ObjectInfo?,
                           (VideoObject|AudioObject|ImageObject|TextObject)+,
                           Caption?)>

and then my second example works.

This, at least, is a step forward.  However, I think the second solution is
bad -- it involves a couple of completely non-standard parameter entities,
and it requires an alteration to the DTD itself.

Anyone got any suggestions?

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery