Situation: I have a Docbook project that builds in Publican. However the same book also needs to be able to be built by a different team using Maven and jDocbook. How do I make this happen.
1 – You’ll need a Maven POM (pom.xml)
Publican 1.0 currently no longer includes POM creation. The previous generation of Publican, ie 0.45 and earlier, would produce a Maven POM (pom.xml) with the command make pom. Either generate one with a pre-1.0 version of Publican or make a copy of a pre-existing one.
2 – Add the jboss.org Maven repository configuration to the POM
The POM produced by Publican lacks the repository configuration to actually make it work.
EDIT: Apparantly this is because users were being instructed to add this configuration to their ~/.m2/settings.xml. In my opinion this is counter to the design of Maven. Projects should be self contained and not rely on local configuration.
The missing sections are:
<repositories>
<repository>
<id>repository.jboss.org</id>
<name>JBoss Repository</name>
<layout>default</layout>
<url>http://repository.jboss.org/maven2/</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>repository.jboss.org</id>
<name>JBoss Repository</name>
<layout>default</layout>
<url>http://repository.jboss.org/maven2/</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
These are the repositories that contain the jDocBook Maven plugins as well as the default JBoss style plugins. Just add this XML to the POM within the scope of the <project> tag, e.g. just before the <build> element.
3 – Make sure the POM matches the book.
If you didn’t use Publican to generate a new POM and are reusing a POM from another project then the <properties> section will probably not match your book and will need to be edited.
<properties>
<translation>en-US</translation>
<docname>A_User_Guide</docname>
<bookname>A User Guide</bookname>
</properties>
<docname> needs to have the same value as the file name (minus the .xml) of the starting XML file of your book, i.e. the one containing the <book> or <article> element.
<bookname> is only used in the <name> element of the <project> … and nothing in this POM makes use of it, so it doesn’t really matter what you put here. I’d set this to whatever the title of the book is.
4 – Add entity declarations to the top of each of your XML files.
Publican enforces some good habits, like having all your entities declared in one file. However entities actually need to be declared in every file that they are referenced from. Publican as a part of it’s “pre-build” process inserts the declarations into each file for you. jDocBook doesn’t do this however so you need to add a reference to your entities file (A_User_Guide.ent) in the header of every XML file that uses those entities. If you don’t do this, the entities will not populate in your book.
<?xml version='1.0'?> <!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "A_User_Guide.ent"> %BOOK_ENTITIES; ]>
EDIT: The filename of your entities file is a relative path. This means that if the entity file is not in the same directory as the XML file that you are editing then you must supply the relative path. In the example above, if the XML file is in a sub-directory, and the entity file is in the parent directory then you would need to specify the file as “../A_User_Guide.ent”.
Note Publican is smart enough not to duplicate this during its own build process.
4 – Specify both role and language for <programlisting>
In Publican, to make use of language syntax highlighting in <programlisting>, you specify the attribute language with the value of the language that the <programlisting> contains. This is actually the correct behavior according to the Docbook specification.
<programlisting language="xml">
However the underlying highlighting library that jDocBook uses requires that the language be specified with the attribute role.
<programlisting role="XML">
You can simply specifying both attributes so it works in both systems.
<programlisting language="xml" role="XML">
Note that Publican 0.45 requires the value to be lowercase, and jDocBook requires it to be uppercase.
EDIT: For Publican 1.0, the capitalization of the language value needs to match the LANGUAGE column at http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS.
That’s the easy stuff. Dealing with Publican’s Common Content is a little trickier. In many cases you can simply supply a Feedback.xml, Conventions.xml and Legal_Notice.xml to satisfy the fallbacks. But that isn’t really a good long term solution for a couple of reasons which I’ll deal with that another time.
Maven will build this book with the command mvn compile. The Publican supplied POM will build html, html-single and PDF versions of the book using the default JBoss documentation styles.
If you do not want to use the default JBoss documentation styles then you will need to create your own jDocBook style Maven plugin. This isn’t terribly difficult but is also a topic for another time.
The Linux version has two downloads, one named something like jdk-6u16-linux-i586.bin, and the other one jdk-6u16-linux-i586-rpm.bin. You want the first one, not the ‘rpm’ one.
Don’t worry about the Sun Download Manager, just click on the file link and it will being downloading immediately. Save this file in your home directory.
