Archive for November, 2009

Why Thank You!

November 13, 2009

Yesterday, a co-worker alerted me to the fact that my name had been listed as one of the Top Open Source Technical Writers on the web. I was blown away! I am seriously over the moon about it all, and wanted to sincerely thank both Aaron Davis and Scott Nesbitt of DMN Communications for the vote of confidence.

Technical writing is a funny kind of industry to be in. The people who are in it are for the most part seriously excited about where tech writing is going, and what we can do along the way. Of course, combined with the type of people who are involved in open source generally, it means you end up working with crazy-smart people who are really seriously passionate about what they do, and how what they do can make the technical world a better place.

I’m very privileged to be able to write free/libre and open source technical documentation for a living. Not many get to have that experience. The things that the open source community has taught me, and the experiences I’ve been able to have doing so, are something that working anywhere else just wouldn’t offer you.

My passion is creating the best technical documentation I possibly can, and making it available to as many people as possible. More often than not in open source, the deadlines are tight, the scope is big, and the resources limited. The challenge that situation creates is, as expected, pretty huge. Being given the opportunity to attempt to create documentation that shines within that environment is one of the biggest challenges I’ve ever encountered. It’s a challenge that I wake up every morning to, and while there are days that I think I can’t do it, there are many more days where all I want to do is inch a little closer to that goal. Having people like Aaron and Scott publically recognise that effort is what makes the hard work all worth it.

To follow on from Aaron and Scott’s list, I’d like to shout out to all those people who write, contribute, edit, review, and use open source technical documentation – even if it’s only spotting typos and raising a bug. You are the ones who deserve the recognition, because without you, I wouldn’t have the opportunity to do what I love. I hope you all enjoy creating and using open source technical documentation as much as I do.

Cross-posted to On Writing, Tech, and Other Loquacities

Building Publican DocBook Projects in Maven using jDocBook

November 5, 2009

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;
]>

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 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 athttp://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.


Cross-posted to: Oh Look A Shiny Sparkly Thingy!