RE: [docbook-apps] DocBook -> Wiki

["David Cramer" <dcramer@motive.com>]

Your wiki engine may already have html2wiki scripts. If so, you could
convert the docbook to html and then convert that to wiki markup. You
could customize tweak docbook2html xsls and/or the html2wiki scripts as
needed to improve the results. I'm sure you'll have to do something
special to deal with images for example. 

The idea is appealing and I've wondered about the possiblity myself, but
one thing to consider is that your reviewers won't be looking at the
format you actually ship to customers.  So you would miss an opportunity
for them to find formatting issues or things that are unclear due to
some aspect of the presentation. We deliver html and pdf formats, but
our html formats are more popular/get more use. For reviews, we publish
to an eclipse infocenter and include feedback links in the header. The
feedback links contain some javascript that prepopulates the email
message with the document title, section title, url, and date/time the
document was generated. As we receive feedback, we incorporate it and
republish the document. If it's important for reviewers to see each
other's comments, you could create a distribution list to which all
reviewers of a document are subscribed. 

If pdf is your primary format, you might use Acrobat's commenting
mechanism. In recent versions of full acrobat, you can send a document
for review so that the recipients can add comments even if they only
have acrobat reader. 

There are also commercial solutions like xmetal reviewer:
http://na.justsystems.com/content.php?page=xmetal-reviewer With it, you
publish the actual xml doc to a server. Users can edit and comment
inline. The writer then accepts/rejects changes etc. However there again
you'd be having the reviewers look at something that's not the actual
version you ship. 

David

> -----Original Message-----
> From: Geraint North [mailto:geraint@transitive.com] 
> Sent: Monday, October 15, 2007 5:51 AM
> To: docbook-apps@lists.oasis-open.org
> Subject: [docbook-apps] DocBook -> Wiki
> 
> Hi,
> 
> I'm thinking of putting together some DocBook -> Wiki XSL 
> stylesheets.  This is to attempt to solve the problemm (other 
> suggestions gratefully received) of handling simultaneous 
> multiple reviewers of a DocBook document.
> 
> The idea is that, having put together the Admin Guide for a 
> release of our software, the author publishes it on our 
> internal Wiki before handing it to our Release Engineering 
> team for testing.  As the RE team discovers bugs in the 
> documentation, they can alter/annotate it on the Wiki, where 
> their changes will be immediately visible to the rest of 
> Release Engineering, and to the original author.
> 
> Using the Wiki's change control tracking, the document author 
> will be able to see the comments and changes made by the 
> Release Engineering team, and then selectively (and manually) 
> roll them back into the original DocBook - I'm not trying to 
> roundtrip the document via the Wiki and back again, as I know 
> that the conversion will be lossy.
> 
> Has anyone else attempted this?  Does it sound useful?
> 
> I'd also appreciate some guidance as to how I should start - 
> should I take an existing (e.g. HTML) set of stylesheets, or 
> just write my own from scratch?  I've done a lot of 
> customisation of the HTML and XSL- FO stylesheets, so I have 
> a pretty good idea what's involved either way.
> 
> Thanks,
> 
> Geraint North
> Principal Engineer
> Transitive
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: 
> docbook-apps-help@lists.oasis-open.org
> 
>