[mythtv-users] Mailing list and a Wiki... and a dessert topping

[David]

Peter Valdemar Morch wrote:

> David myth-at-dgreaves.com |Lists| wrote:
>
>>> You might even start by importing the current documentation to your 
>>> wiki.
>>
>>
>> It's a good idea - I though about it quite a bit - we'd need to keep 
>> in sync and it's too hard for now.
>
>
> Now there is a way-cool idea.

> LinuxDoc/SGML can generate output in a variety of formats, and surely 
> WikiMarkup could be one of these formats. As a starting point for the 
> docs.

This won't be a one-off will it. (see later)

> Seperated into different pages, just like the HTML docs. When a CVS 
> update occurs, this is done by patching as in:
>
> diff -ur previousOfficialWikiMarkup/ currentWiki/ > userContribs.diffs
> mv currentWiki/ currentWiki.old
> mv officialWikiMarkup currentWiki
> cd currentWiki
> patch -p1 ../userContribs.diff
>
> At any point,
>
> diff -ur officialWikiMarkup currentWiki
>
> is the user contribution to the documentation...
>
> I like the idea. A lot. Some work, naturally, especially when there 
> are merge conflicts (append the user contributed part of such 
> conflicts to PageName/Conflicts?) But it would be *very* slick! And 
> actually useful for many other projets as a 
> keep-documentation-up-to-date thing. I love this idea!!

That does sound very interesting...

> Does anybody know how tricky it is to do the LinuxDoc->WikiMarkup 
> translation. Something about XSLT, right? I'll try to look into that. 
> As far as I can see, this is the only really tricky part of the whole 
> thing.


And in reverse...  I was thinking of taking Moin's Wikiformat -> XML -> 
Linuxdoc (actually DocBook but I was wrong)
I suspect you want to let MoinMoin do that. It's not easy. Take it's 
parsed output in XML rather than HTML and XSLT that.
BTW, append "?action=format&mimetype=text/xml" to a Wiki page and you 
get xml.
eg: 
http://www.mythtv.info/moin.cgi/HardWare_2fVideoCaptureCards_2fPvR350?action=format&mimetype=text/xml


Are you suggesting a process like:
* change  to official docs (be that a release or a CVS commit)
* convert previous and current to WikiFormat to get patch
* apply patch to affected wiki page

What about this:
I was thinking of making the generated WikiPage immutable. Create a sub 
page with comments. The sub page could have chunks reproduced and edited 
ready to form a patch. This gets around the collision problem and:
* makes .org the master for the parent page
* allows the sub page to contain Wiki links to potentially O/T areas
(Hell, you could even use Moin's processing instructions to mark a chunk 
from the page, tag it,  wrap it as a patch and send it to the official 
maintainer. Then if/when the patch comes in Moin could blat the tagged 
bit as it would live in the parent.)

The process is then:
* change  to official docs (be that a release or a CVS commit)
* convert current to WikiFormat
* replace affected wiki page - leaving sub page in place
* remove redundant info from the subpage

Makes me think: why not have two subpages? One for 'info' one for 'patches'?
Like this:
  http://www.mythtv.info/moin.cgi/OfficialFaq_2fFAQ21_2e18

The process is then:
1 change  to official docs (be that a release or a CVS commit)
2 convert current version to WikiFormat
3 replace affected wiki page - leaving sub pages in place
4 remove redundant info from the ProposedChanges subpage

Obviously 1 can be triggered in many ways (including current submit 
patch process) - the Wiki way would be:
* make changes in /GeneralDiscussion - iterate and manage
* move changes to /ProposedChanges
* submit patch to docs (manual)
* if accepted goto 1
* if not accepted, create new WikiPage and put a link at the top of 
GeneralDiscussion.

David