DOCBOOK-APPS: Summary: Visio Vector Graphics -> DocBook XSL

["Rankine, Alastair J (Alastair)" <arankine@avaya.com>]

Thanks to all who responded on the vector graphics question.

Here's a summary of the options for including Visio diagrams in DocBook using the XSL stylesheets (on Windows). This information may well apply to other drawing packages as well. DaveP, is this FAQable?

The supported vector graphics formats depend on your FO processor. For the purposes of this summary, I consider only two such processors: FOP 0.20.3 (which supports SVG only) and PassiveTeX (supports PDF (only?)). 


What works
----------

- Adobe Postscript printer driver -> ghostscript -> epstopdf -> PDF

There are some instructions here (http://www.cs.uq.oz.au/~emmerik/visioeps.html) on how to convert Visio files to EPS for use in LaTeX, and these instructions seem to apply also for PassiveTeX. Basically it involves printing to a postscript file using the Adobe postscript printer driver, then using ghostscript (actually GSview) to convert this to EPS with a correct bounding box.

The one additional thing you need to do after fixing the bounding box is convert to PDF. The "epstopdf" tool can be used for this purpose. This is a tool which is included in the tetex distribution (at least it is in cygwin's tetex), and is not to be confused with the "ps2pdf" tool which is part of ghostscript.

The output quality is generally pretty good, but you need to ensure that you use postscript-friendly fonts in your Visio diagrams (or set up suitable substitutions).


What doesn't work (yet)
-----------------------

- Visio EPS export -> ghostscript ps2pdf -> PDF

You can export EPS from Visio, then using the eps2pdf converter in ghostscript convert to PDF. Unfortunately I was never able to get this to work (tried ghostscript on cygwin and linux, can't remember the versions). I tried many different options in the EPS export function of Visio, and it would either confuse the ps2pdf tool, or the pdf viewer, or produce a blank image. This could possibly be made to work with the correct set of options, but if you're going down this path you might as well just install the Adobe printer driver (it's free) and use the technique above


- SVGMaker (www.svgmaker.com) -> SVG

This is a printer driver which outputs SVG. Looks like a good tool - the output is great using the Adobe SVG viewer. Unfortunately:
- it produces compressed svg by default, which need to be uncompressed so that FOP (actually Batik) can understand it
- FOP generates an invalid PDF (at least on the images I tried). Maybe I need to upgrade Batik?
- (minor annoyance only) On my test images it generated a folder full of wierd little 3x2 pixel bitmaps. This maybe had something to do with the Visio stencils I was using though.


- SVGExport (http://www.csse.monash.edu.au/~tardif/SVGExport.html) -> SVG

A DLL which is supposed to export SVG directly from Visio. I couldn't get it to work with my Visio 2002. Also has many limitations (see webpage).


- Visio EPS Export -> ps2web/ps2vector (http://www.square1.nl/index.htm) -> SVG

These look promising: commandline tools to convert postscript into SVG. It's relatively expensive (compared to the price of Visio itself!) at $149. I haven't tried it, but I'm worried: this tool is obviously at the mercy of Visio's postscript export functions (more above).


- Visio 2003(?) -> SVG

I'm sure I came across a page at microsoft.com which said "the next version of Visio _will_ support SVG natively". Maybe I was just dreaming?


- Visio AI/WMF export -> Mayura Draw (http://www.mayura.com) export -> SVG

Mayura Draw looks like a good tool for authoring, but I could not get it to play nicely with Visio using either AI or WMF as a common file format for import into Mayura.


- Adobe postscript printer driver -> ghostscript ps2ai -> Mayura Draw export -> SVG

This is recommended by the Mayura site as one way of converting postscript into a form suitable for import in Mayura Draw. Unfortunately my ghostscript would not do the conversion, I got an "unrecoverable error" using the ps2ai script.


Gratuitous Opinion
------------------

It's disappointing to me that the only serious (and free) contender for vector graphics inclusion in a DocBook XML document is the PDF format via PassiveTeX. The tools are complicated to install, and rely on much manual intervention to get working. (I suspect this stuff _could_ all be scripted but it would be very fragile...)

Even more concerning are the number of limitations and non-conformances of PassiveTeX with the latest XSL-FO draft, and DocBook XSL stylesheets, that may require manual intervention for some documents. (example: PassiveTeX does not support the font-size="90%" attribute, which is emitted by the latest XSL stylesheets for footnote markers). Of course FOP has similar limitations, but for my these are less severe.

So the choices (at least for me) are:
- use FOP to get the correct formatting of text, but use GIFs for images, or
- use PassiveTeX to get vector graphics, but work around bugs/limitations in the text formatting, or
- use OpenJade, but live without my XSL stylesheet extensions... 

[Aside: it seems that also OpenJade has it's own problems - finding the correct combination of imagedata attributes, stylesheet customisations, and OpenJade commandline options has so far eluded me. And the recommendation to omit the filename extension and let TeX work it out does NOT seem to work for me, dammit!]