>> 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 _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
