Joachim Breitner

Releasing zpub as Free Software

Published 2009-11-06 in sections English, Digital World.

Earlier this year, my brother and I developed a “documentation management server” for a small software developing company. They were sick of creating their documentation by sending around Word documents, having to manually merge them, losing changes and not getting a clean, consistent layout.

So we created zpub for them: It is based on DocBook and Subversion, and adds a fairly nice web interface to it. Now their work flow is

  1. The editor checks out the DocBook source document via Subversion. With a client like TortoiseSVN, this is possible even for the less tech-savvy editor.
  2. He works on the document using the editor of his choice. We recommended an editor with a proper DocBook mode such as the XMLMind XML Editor or Serna Free, which was recently published as Free Software, to our customer.
  3. When satisfied, he commits his changes via  Subversion, adding a comment describing his modifications.
  4. On the server, zpub renders the document in the various output formats (.html, .pdf, .chm), and makes the result available via the web interface. The commit messages are put there, and all previous revisions of the document can still be accessed.
  5. Optionally, an e-mail about the change is sent out to a per-document configurable list of recipients.
  6. Optionally, the documents are rendered with a “DRAFT”-Watermark on the pages, to avoid leaking wrong revisions to the outside. Only users with extended rights are allowed to release a document, thus causing a version without that watermark to be rendered.

For more details on the feature and usage of zpub, check out the documentation that you can find on the demo instance.

We are actually quite satisfied by zpub, and it would be a petty if that was just it. Of course, there are quite a view programs out that that can provide these features – plus many more, much more than a company the size of our customer would want to have (or even to worry about). So there is a niche between „sending Word documents by mail“ and „buying a very expensive, complicated product“ where zpub fits in.

Being a fan of Free Software myself, and since zpub is based on Free Software, we decided that we want to release zpub itself under a Free License. We chose the EUPL, which is a GPL compatible license created by the European Commission, since our customer comes from a municipal environment. The code is hosted on gitorious now, so if you have a need for zpub, just give it a try.

Also, if you run a Free Software project, manage your documentation in DocBook (or want to start to do so) and think that zpub might be a neat idea to allow more documentation writers to contribute, talk to me. I might well offer free hosting in that case. If you are a commercial user, I’m still offering hosting (and support or feature development), just not for free any more. Note that the zpub user interface and documentation is currently only available in German.

Comments

Why did you use Subversion? Didn't like Darcs, Mercurial, Git, Bazaar or any of the other modern RCSes?
#1 Programmer am 2009-11-07
Good question. In fact, I do like darcs very much, and I use git when it’s suitable (e.g. for the zpub source code).



But in this case, the point of zpub is to have a central repository (that’s where the z in zpub comes from – German word zentral). Also, the target group were technical writers, which are not necessary techy. A decentralized system like git is just too much unneeded complexity here.



Another killer feature of SVN is the good graphical clients on Windows. Not that I would use them (or Windows in the first place), but the expected users of the system will be rather happy about this.



Ideally, the XML editor would integrate and hide the Subversion completely, but that would require additional development efforts.
#2 Joachim Breitner (Homepage) am 2009-11-07
We use docbook to create release notes for our products and convert them to PDF using dblatex utilities.

I would love to try zpub as it will make managing all the release notes a bit easier. Can you please provide the setup instructions in English?
#3 Onkar (Homepage) am 2009-11-09
Hi Onkar, thanks for your interest.



I have written some (not very well tested) instructions in INSTALL.en, you can see that file online at http://gitorious.org/zpub/zpub/blobs/raw/master/INSTALL.en. If you have any questions or problems, please ask. You can also contact me by mail (mail@joachim-breitner.de) and XMPP (a.k.a. Jabber/Google Talk) at nomeata@joachim-breitner.de.
#4 Joachim Breitner (Homepage) am 2009-11-09
Hello Joachim.



I would be interested in helping translate the rest of the documentation into English (and if the UI is set up to allow easy translations, that too).
#5 Gavin Westwood (Homepage) am 2010-01-03

Have something to say? You can post a comment by sending an e-Mail to me at <mail@joachim-breitner.de>, and I will include it here.