[gst-devel] GStreamer wiki

[Tim 'Tool-Man' Taylor]

Richard Boulton wrote:

> Would it be possible to write a script to convert parts of the wiki into
> DocBook format?

It may be possible, but I'm not sure it's plausible.  You lose so much 
structure to the markup when you move it (create it) in Wiki, that 
either the generated DocBook will look like Wiki pages wrapped in 
DocBook chapters, sections, etc., or you'll need a set of wiki writing 
guidelines that defeat the purpose of having a wiki in the first place.

Here's an idea, borrowed from the ArsDigita Community System.  At the 
bottom of each HTML page of reference documentation -- below the 
chapter/section navigation -- a wiki page is appended to the content. 
This wiki page would serve as comments, questions, annotations, etc. for 
the current page -- the conceptual equivalent of "writing in the 
margins".  You don't put the documentation into wiki at all.

Where the reference docs become way out of date with the code, a rewrite 
of the chapter/section can be carried out in wiki (if desired).  The 
authors would add wiki annotations to the affected reference docs 
linking to the work-in-progress.

Periodically maintainers of the reference docs go over the annotations 
or wiki docs and update the DocBook versions.

You have a scheme for mapping reference doc URLs or page names to unique 
wiki names.  Including the annotation would go something like:

[appended to 
http://gstreamer.net/docs/manual/gstreamer-manual/gstreamer.html]

<p>This documentation is for the release of gstreamer-x.y.  For 
information regarding using these docs with the latest development 
version of gstreamer, read the comments below:</p>
<!--#include virtual="/cgi-bin/wiki/moin.cgi/GstManualGstreamer" -->

I'm convinced this results in less overhead than having all docs in 
wiki. In the case where the DocBook reference doc is mostly correct, 
it's easier to post a correction, and anyone can do it.  It distributes 
the load of synchronzing the DocBook docs with the information in wiki. 
  When all docs are maintained in wiki somebody has a helluva job of 
producing the DocBook reference docs when you want to make a stable release.

-- 
Tim Taylor
tim at tool-man.org