Wiki-like markup for Guide

[C. Florian Ebeling]

On Wed, Jan 14, 2009 at 6:01 PM,  <markd at macports.org> wrote:
>>> 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.

Ok, then let's just keep docbook. I thought other might consider it combersome
as well, but if that's not the case, then so be it :)

Those who'd better like something else still can alleviate their pain
with Pandoc:
http://johnmacfarlane.net/pandoc/try

Florian


-- 
Florian Ebeling
Twitter: febeling
florian.ebeling at gmail.com