[hibernate-dev] docbook + maven

[Steve Ebersole]

As part of migrating Hibernate to use Maven, one of the big issues I ran
into was the current state of DocBook plugins for Maven.  The current
mojo-codehaus hosted plugin is insufficient.  There is another more
widely used one done by one Wilfred Springer as part of something called
"agilejava".  The "agilejava" one is fairly full featured, but is really
pretty bare bones in terms of configuration (its is mainly a simplistic
wrapper around the defined DocBook xslt parameters).

In my estimation the, "agilejava" one was closer to usability, but Mr.
Springer did not seem interested in accepting my volunteer to help
improve his plugin.  So I began implementing my own.

It works off of a slightly different approach than the other two.  The
biggest difference being that custom stylesheets are packaged as
separate projects and included via the Maven dependency mechanism.  This
allows true reuse of the stylesheets across projects.  The other is
planned better support of translations which is important for Hibernate,
and most projects using DocBook.

This however led to a conceptual question regarding how to best handle
image references.  As background, in DocBook, the way images normally
get resolved is as via xslt templates.  The DocBook supplied templates
do a hard file lookup relative to a xslt parameter named 'img.src.path'
if it is set; and really this is format specific as well.  Regardless,
though, I need a mechanism to access the image files from these "style
projects" and be able to resolve reference to them from the DocBook
source or xsl stylesheets.  I have identified a few potential approaches
to achieve that:
1) force separation of (a) xslt and (b) resources like images/css into
separate projects.  Specifically, #b would need a custom packaging which
would allow me to find resources and unarchive them locally into a
staging dir for use in 'img.src.path'.  A variation on this would be to
bundle them together with a custom packaging and somehow extract just
the "resources".
2) Apply custom graphics resolution templates to the built xsl
transformers, hoping that the custom xslt does not itself do this.

I'm not (necessarily) looking for volunteers (although certainly that is
welcome).  More I just need people's thoughts on the various approaches,
especially those using or familiar with DocBook.

Thanks,
Steve