On Wed, Jan 14, 2009 at 6:01 PM, <[email protected]> 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 [email protected] _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
