DeltaXML, changebars, and Docbook
Friday, 24 July 2009 21:28
jho
One of the most important things to understand as a Technical Communications manager when you're transitioning your company documentation and documentation process away from being Microsoft Word based and towards a centralized CMS is that you're also transitioning away from being a departmental speedbump and towards being a potential barricade. This transition can be terrifying at certain moments, like the moments when a critical document needs to be published and your CMS is spewing error messages rather than neatly formatted PDFs. This happened to me while ago. When attempting to publish a differenced version of a docbook publication which had been created with the most excellent DeltaXML Core tool, the XEP processor began spewing "com.renderx.xep.lib.InternalException: No matching point found for change-bar" along with details about exactly which change-bar was lacking a companion change-bar-end. Digging into the FO code revealed that there was indeed a matching change bar end for problematic opening tag, and we were off to the races, 'cause a missing closing tag could be a problem in my XSLT, but when the end is there an XEP can't find it, it looks more like a bug in XEP, which is roughly a thousand times more frightening. I can patch my XSLT. I can't patch XEP. Two days worth of troubleshooting later it turned out that the problem was a known bug within XEP interacting with some extra spaces added to the output XSL:FO by the DeltaXML Docbook XSLT. It wouldn't happen everywhere in the document because it only crops up in conjuction with certain kinds of rollbacks that XEP performs to satisfy keep restraints on orphens, etc. The solution was pretty simple. I had to modify the DeltaXML XSLT to add a zero-width character () immediately before and after every change-bar-end. The document published, the screaming stopped, my ears healed, we all moved on.
Last Updated on Monday, 04 January 2010 15:35
Bluestream XDocs CMS 2.1
Tuesday, 21 April 2009 15:14
jho
There's a lot I could write about Bluestream and the XDocs product. The 1.1 version was...not well suited to the setting that we tried to deploy it into. The 2.1 version, however, is nearly as fast, stable, and pleasing as the 1.1 version was slow, buggy, and frustrating. It requires users to learn new ways of doing things. I don't apologize for that; change requires change, and this change is progress. It supports DITA beautifully and is adaptable to other schemas with some fairly minor development. The bundled XMLmind editor combined with the low licensing cost makes this system the undisputed value leader in its space. Any sysadmin who takes the time needed to learn how to leverage the combination of the two tools (XDocs and XMLmind) can't help but be impressed with what this system can do for such a stunningly low price. I don't work for Bluestream, have received no considerations from Bluestream, and have, in fact, directed a large volume of money towards Bluestream. If I have my way, I'll be directing more.
Last Updated on Tuesday, 03 November 2009 23:11
|
File under "My Shameful Secret"
Thursday, 12 November 2009 20:44
jho
One of the drums that I regularly beat when indoctrinating new users to an XML CMS is to stop thinking that layout and formatting matter so much; the content matters most, and the look of it is a detail. Authors who work in tools like Word tend to get lazy and start using formatting tricks to get around the necessity of clear language and clear thought. Writing clearly is difficult, and I'm firmly of the belief that most of the resistance to XML authoring comes from people discovering that they can no longer take the easy way out of writing their content. When one can't run back to funky formatting to make up the shortcomings in one's writing, one needs to actually sit down, think, plan, and write like an adult. This is what I mean when I say that appearance is a detail and content is king. And I believe it, I really do. However... However, the look of a long document that has been produced by the publishing scripts I've created at PMC thrills me. It's embarrassing, but true. A document that was produced in Word or Framemaker or other tools that allow users to introduce tweaks to formatting may make the individual page that was tweaked look a little better, but when you're scanning a document hundreds or thousands of pages long, the reliable, mechanical, predictable layout and formatting of an XML-sourced document gives the document as a whole a solidity and air of professionalism that you can just never get otherwise. Everything in its place, everything flawlessly regular, every compromise a consistent compromise. It's gorgeous. So the truth is that I'm just a layout junkie like the rest of them; I'm just a junkie on a different scale. What the heck; go big.
Last Updated on Monday, 01 February 2010 21:32
Current Employer: PMC-Sierra
Thursday, 23 April 2009 00:00
jho
My current contract is at PMC-Sierra, Inc. I've been contracted to manage the development and rollout of a Bluestream CMS while maintaining existing XML resources and systems. This contract will end December 31, 2010. Addendum... It's a done deal. Bluestream XDocs 2.1 is up and running with users in Burnaby, Freemont, Shanghai, Bangalore, and misc. remote points. We are way out of beta and edging Microsoft Word out the door on a whole slew of fronts. We're getting one more significant upgrade to XMLmind which should significantly improve performance when opening large Docbook files (600+ pages, 200+ images) and after that we're moving onto some more interesting problems like automating data mashups and Ecilpse help generation. Good times.
Last Updated on Monday, 25 January 2010 16:07
|
