Wiki-like markup for Guide

[markd at macports.org]

>> There are several issues that I think have made wikis not sufficiently
>> attractive for us.
>
>Ok, I guess I didn't make my intent clear enough. My suggestion is not
>to use a wiki as documentation. I think we have that already, that's fine,
>and it serves a different need.
>
>My suggestion is about using a different format: instead of an complicated
>XML vocabulary a lightweight markup language [1]. I think Textile and
>Markdown
>are the most commonly used ones. Those are best known as the raw format of
>wikis, that's why I called it wiki-like. That way the documentation
>would still be in
>a single place in the svn. I find that an important property as well.
>But it does
>not necessitate use of xml. 

But there is more to it than having it in a single place.  It must have
enough of a data structure to support what we're doing.  There is a
current toolchain to get us from XML DocBook to man pages automatically. 
I think we'd end up rolling our own toolchain to accomplish the same thing
with markdown.  Simon could give a better answer because he's been doing
the scripting work, but I suspect there would be new challenges with
something like markdown to man pages.

And I think the more complex structured environment of DocBook has been a
benefit.  I realize that markdown (and other ones) support a structure as
well, but we'd I think we'd have to come up with a fairly complex style
guide for its use to support a consistent style to get the functionality
we now have.  In other words, we'd end up creating a DTD, which is what
DocBook is.  So my opinion is that it would take a lot of work to get the
functionality we now have, and we'd likely not do a good enough job with a
DTD to have as consistent a style as we have now.

Mark