>Highlighting Changes when Single Sourcing

>I’m a big proponent that documentation should be singled sourced. The same information should be generated into multiple formats from one common source. I personally don’t think ODT, Word, or some of the more traditional tools used for writing documentation do this very well. Style and formatting get to tied into the document itself. However one of the features these tools do well is showing what has changed from multiple people working on a document.

I happen to use DocBook for my single sourcing of documentation. We use it at work for generating all of our documentation in HTML and PDF formats. However one of the difficulties is knowing what has changed easily between versions of a document. DocBook has a revision flag but this is a pain to maintain manually. Enter a nice utility (though still beta) from Norman Walsh called diffmk. It will take two XML documents and mark it up with the differences between them. It also includes a docbook.xsl stylsheet to then generate the appropriate revision flags to indicate Add, Change, Delete.

Here is a document before the diffmk run.


Here is one after using diffmk to compare versions of a merged DocBook XML file.


The process will highlight every change, addition, or deletion that has occurred between the two versions.

If you are using Eclipse WikiText to single source, you can leverage diffmk and it’s stylesheets as well. Just include a step in there to generate the differences, and then follow the instructions provided by Robert Stayton’s DocBookXSL: The Complete Guide to generate the appropriate output.

Advertisements
This entry was posted in docbook, eclipse, xml. Bookmark the permalink.

2 Responses to >Highlighting Changes when Single Sourcing

  1. David Carver says:

    >Yep, I expect to see draft docs generated from PDE single sourced highlighted with changes. 🙂

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s