On Jan 14, 2009, at 9:18 AM, C. Florian Ebeling wrote:
On Wed, Jan 14, 2009 at 6:01 PM, <[email protected]> wrote:There are several issues that I think have made wikis not sufficientlyattractive 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 andMarkdownare the most commonly used ones. Those are best known as the raw format ofwikis, that's why I called it wiki-like. That way the documentation would still be ina 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 haveenough of a data structure to support what we're doing. There is acurrent 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 doingthe 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 aDTD to have as consistent a style as we have now.Ok, then let's just keep docbook. I thought other might consider it combersomeas 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
So you dont feel like you're the only one... :) It is definitely cumbersome to edit manually. The few times I've had to touch the guide I did it with vi. So I agree on that point, but also agree that the structure gives a lot of benefits. The bottom line is if you're going to spend any significant time on the guide, find a gui or other tool to do the xml for you.
-Bill
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
