My first thoughts on Publican

So as part of my work with the Fedora Documentation team, I’ve started playing around with Publican. For those of you who aren’t aware, Publican is a documentation tool chain that started out being used internally at Red Hat (where it was called documentation-devel), and is now being opened up and hosted by Fedora. I won’t bore you with all the details yet, but needless to say it makes it easy to get started with writing documentation in DocBook format and getting that documentation packaged up correctly. Continue reading below if you’d like to know more. (If you could care less about documentation, just be on your toes — the docs team is gonna be a lot more efficient in the near future!)

So, to make a short story long, I do a lot of writing. (Much more than I’d honestly like, but people tell me they like my writing style — go figure.) I do most of my technical writing using the DocBook format. If you’re new to DocBook, I suggest you take ten minutes, read this article written by the intrepid Paul W. Frields. It’ll give you the background you need on what DocBook is and how it works. Then come back and finish this article. (You’ll thank me later.) And to answer your questions: Yes, I actually take the time to write out all those XML tags. By hand. In vim. Yes, I actually write books in vim. Go figure.

So one of the toughest parts of getting started in DocBook (like most IT-related projects) is setting up the infrastructure. This is where Publican comes along… it takes care of all that for you. It builds you a skeleton that you can then flesh out, and takes care of all the things you’d rather not have to worry about, like packaging, translation, and building various versions of the output (say in HTML, chunked HTML, and PDF versions). I probably spent at least a good twenty or thirty hours (or more) setting up the infrastructure for the last DocBook project I started… mostly setting up files (and the various links between them), tweaking the Makefiles, etc. It was not exactly my definition of the word “fun”.

So on a whim last night, I figured I’d start checking out Publican and see how long it would take. In less than 15 minutes, I had Publican installed and an existing DocBook document ported over to it (the new revision of the Software Management Guide, as part of the Fedora Documentation Project). You can see the HTML output of my endeavor here, complete with Fedora branding and everything. Now I don’t know that Publican is going to be a perfect fit, especially given some of the unique requirements of the Fedora Documentation Project, but I have to hand it to Jeff Fearn and the others on the Red Hat documentation team — they’ve created a lean mean doc-building machine! I tip my hat to you!

If you’re already running rawhide, you should be able to simply install the “publican” and “publican-fedora” packages. If you’re running Fedora 8, you can simply point to Bob Jensen’s personal docs repo and install the packages from there.

Published by

jsmith

Jared Smith is very enthusiastic about free and open source software. To learn more about Jared, visit http://www.jaredsmith.net/about/

7 thoughts on “My first thoughts on Publican”

  1. Can you reformat the entry with some paragraph breaks ? That huge chunk of text on Firefox3 is an eyesore. And for those who will not be familiar with the required stuff in the last paragraph, a set of commands would help

  2. hate to be the second guy to criticize your post but the links in your post are impossible to see (i’m using epiphany) unless i hover the mouse over the text word by word link hunting.

    cheers,

  3. Great info! I recently came across your blog and have been reading along. I thought I would leave my first comment. I don’t know what to say except that I have enjoyed reading. Nice blog. I will keep visiting this blog very often.

  4. An outstanding share! I’ve justt forwarded this onto a coworker who was doing a little research on this.
    And he actually ordered me dinner because I stumbled upon it for him…

    lol. So let me reword this…. Thanks for the meal!!
    But yeah, thanks for spending somje time to discuss this subject here on your web site.

Leave a Reply

Your email address will not be published. Required fields are marked *