[idea] round tripping

[Jeff Schering]

On Tue, 15 Mar 2005 08:46:06 +0200, Sean Wheller <sean at inwords.co.za> wrote:
> 
> I really, don't care what technology or system is used, so long as it will
> round trip. As I see it, it is much easier to take the current system and
> continue development than to rewrite it in python. Of course if some of the
> devs have time on their hands ...
> 

>From what I can tell, round tripping between the current wiki and
DocBook can be done. It just can't be done easily (unless there is
something I'm missing - if there is, please tell).

Going from DocBook to wiki is easy enough -- we just need some brave
soul (or poor sucker, depending on what you think of xslt) to write
the xslt.

However, going from moin wiki markup to DocBook can never be
*completely* automated. There is no way for a script to know when the
markup '''Update Manager''' is bold because the author wanted to
emphasize the text, or because the author wanted to signify that
Update Manager is an application. The script would not be able to
determine whether or not to surround the "Update Manager" text with
<application> tags.

Barring AI, there will always be a need for at least some human
intervention and manual editing when going from wiki markup to DocBook
markup. Wiki markup simply does not contain enough information to be
reliably converted to DocBook by a non human.

In addition, I don't see using a DocBook type of markup in the wiki as
a solution. I thought the idea behind using a wiki instead of DocBook
was because of the lower barrier to participation. Adding all kinds of
new tags to the wiki markup would defeat that purpose. (It's also my
understanding (correct me if I'm wrong) that one of the original ideas
behind wiki markup was the removal of all but a bare minimum of
markup, so that people wouldn't need to learn much before editing a
wiki page.)

Perhaps people who want to contribute without involving themselves in
DocBook and Subversion simply post their input to some appropriate
place on the wiki[1]. There are enough people on the doc team who care
passionately enough to take the input, edit it as necessary, and
commit it to the appropriate svn repository. Once it has been added,
run it through the xml processor with the as yet to be created (and
thoroughly hypothetical) xslt file and post the results back to the
wiki page.

The two will only be out of sync for the time it takes to convert the
wiki into DocBook and post it back.

The only problems I can think of right away are these:
1. Version control. It's an issue, but with solutions. Perhaps place
the svn version number in a comment in the wiki. This may require that
one document == one wiki page.
2. Is having one big wiki page for a large document with many chapters
and sections desireable? The user guide, for example.
3. the wiki page may be changed while the DocBook is being created and
committed. The new wiki page that is generated would overwrite the
changes made in the meantime to the wiki page. To prevent this, the
wiki page would need to be locked, possible for as long as a couple of
hours.

That's my two cents worth. I'm not emotionally attached to any one
solution, but it would be nice if there's always an xml format
somewhere in the mix so we can create several presentation formats
from a single source.

Cheers,
Jeff

[1] I realize that "some appropriate place on the wiki" might be
easier said than done.