Making docbook 5.0 work

[Marshall]

I converted a working docbook 4.4 source to 5.0 and got it to work,
but it was a struggle - so perhaps I'm doing something wrong.

I did the following changes to the source(s) (I have some xincluded
files):
Change
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://
www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
to
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN" "http://
www.oasis-open.org/docbook/xml/5.0/dtd/docbook.dtd"

Note: this is more than changing 4.4 to 5.0 - the "V" is dropped, and
after the 5.0 comes an extra directory "dtd".

I added this to the top xml element in each file (this example:
<book>):
<book xmlns="http://docbook.org/ns/docbook" version="5.0">

I changed the dependency that is part of the Maven plugin invocation
of docbkx from

<dependency>
<groupId>org.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.4</version>
<scope>runtime</scope>
</dependency>

to the version for 5.0. But I could not find a suitable 5.0 version
at first. There is a <relocation> element for org.docbook:docbook-xml:
5.0 in the Maven central repository, that relocates this to
net.sf.docbook:docbook-xml:5.0. The repo contents there does not have
any jars, it only has zips, and their names have a classifier
"resources". There's one for dtd, rng, sch, and xsd. I thought I'd
give the dtd one a try.

I unzipped it and found it was internally corrupt, in the following
way: The top level directory has a catalog.xml file, which has the
line:
<public publicId="-//OASIS//DTD DocBook XML 5.0//EN" uri="dtd/
docbook.dtd"/>

This looks correct, but unfortunately, the folder in this zip which
has the docbook.dtd is misnamed - instead of being called "dtd", it is
called "xsd". So the catalog fails...

I then noticed there's an alternative version available in the maven
repo, at net.sf.docbook:docbook-xml: version "5.0-all". So I took a
look at that. It has a zip file, which contains the catalog, and this
time, the correctly named subdirectory. However, the zip file has
another flaw - it has an extra top level directory (called "docbook").

So - I unzipped it, and made a new Jar containing all of the contents,
without the top level extra directory, and called it docbook-xml-5.0-
all.jar - no "classifier" name, and using "jar" instead of "zip", and
put it in my local .m2 repository.

Having now created a proper Jar for this (locally), I changed the
dependency from what was shown above to

<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.0-all</version>
<!--classifier>resources</classifier-->
<scope>runtime</scope>
</dependency>

With that, the docbook processed ok.

I tested to see if using a zip would work instead of a jar, and it
seemed to work, too.

I also tested again to see if leaving the name with -resources
included would work - and that works too, provided you use the
<classifier> element.

So, the whole difficulty seems to be due just to that extra top-level
directory.

Has anyone been able to find a better way to get docbook 5.0 version
to work with docbkx?

-Marshall

--
You received this message because you are subscribed to the Google Groups "Docbkx Tools Users" group.
To post to this group, send email to docbkx-to...@googlegroups.com.
To unsubscribe from this group, send email to docbkx-tools-us...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/docbkx-tools-users?hl=en.

[Mimil Mimil]

Hello,

yes the docbook 5.0-dtd ... was not working (shame on me), they were released before being tested in real life. The 5.0-all is supposed to work, as I could see from your tests it is the case.

Concerning the zip extension this is a choice I made because it is not a jar from my point of view (I was either new to maven). Concerning the resources classifier if I remember good it was implied by the assembly plugin. But as far as I could see from your tests too it is not a problem.

About the docbook/ directory? Also a choice I made in trying to keep things well organized to not put everything on the root directory. On this point I guess the problem is only related on docbkx plugin side which wasn't loading the catalog.xml in the directory docbook/. I think it is corrected on subversion as I try to load the catalogs from different places (I wasn't yet able to write a test for this - maven plugin tests sound really painful - so I did it dirty).

Is there a way you could test with the svn version? Either your modified or original artifacts should work.

Regards,

Cedric,