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-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

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-revi
ewer 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:gerainttransitive.com] 
> Sent: Monday, October 15, 2007 5:51 AM
> To: docbook-appslists.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-unsubscribelists.oasis-open.org
> For additional commands, e-mail: 
> docbook-apps-helplists.oasis-open.org
> 
> 

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

Geraint North wrote:

> 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.

There are already several DocBook -> WiKi stylesheets
available. None of
them supports full DocBook and they support various WiKi
syntaxes. I can
recall only one from the top of my head:

http://docbook.svn.sourceforge.net/v
iewvc/docbook/trunk/contrib/xsl/db2wiki/


-- 
------------------------------------------------------------
------
  Jirka Kosek      e-mail: jirkakosek.cz      http://xmlguru.cz
------------------------------------------------------------
------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document
processing
------------------------------------------------------------
------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34
member
------------------------------------------------------------
------

Thanks for that - I'd just started investigating the DocBook
-> HTML - 
 > Wiki route, and that seems to work well.  In
particular, the   
HTML::WikiConverter perl module seems to do pretty much what
I want,  
although it leaves a lot of FONT and DIV tag hanging around
that  
screw up the Wiki unless I strip them out.

I shall persevere and let you know how I do - I'm
specifically  
targetting MediaWiki at the moment.

Thanks,

Geraint North
Principal Engineer
Transitive


On 15 Oct 2007, at 14:38, David Cramer wrote:

> 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-revi
ewer 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:gerainttransitive.com]
>> Sent: Monday, October 15, 2007 5:51 AM
>> To: docbook-appslists.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-unsubscribelists.oasis-open.org
>> For additional commands, e-mail:
>> docbook-apps-helplists.oasis-open.org
>>
>>
>
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-apps-helplists.oasis- 
> open.org
>


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org