On Tue, Jan 13, 2009 at 1:41 AM, Ryan Schmidt <[email protected]> wrote: > On Jan 12, 2009, at 07:15, MacPorts wrote: > >> + 1. make guide use a reasonable (wiki-like) markup, not docbook-xml. > > I think we like our docbook-xml Guide... a lot of work was put into getting > it the way it is. What objections do you have to the way it's being done > now? Let's discuss.
I dislike editing XML, because it is so quirky. And I dislike docbook-xml because it has this vast vocabulary, which few poeple really use. Only a very small subset of it is used in the guide. And this makes it hard for new or occasional contributers (like me) to help. I think there are solutions out there that don't force me to think about online and offline document type definitions, well-formedness of ampersands, and if I can nest a certain element at this tree position. I find thinking of a text as a tree quite unnatural. Why not keep it as a stream of characters? But xml forces one to look at it as a tree. Mark once kindly offered me to accept text changes and make the actual editing. That's very generous. I'm sure he offers that to everyone else as well. But that still feels a bit indirect, and I don't really want to bother somebody else with a small change. I guess others are reluctant to do so as well. Still the many but small changes are the important asset in any open source project, and they are the means to get tedious work like documentation done. So a simple and straightforward, maybe even well-known markup as wikis tend to use them might help. I know about all the semantics and the structure arguments, and that the rendering is a separate matter. But documenting should not become harder than just writing an understandable text, which is hard enough in it's own right. So, these are my points against docbook. OTOH, if the majority is happy with the current setup, then let's leave it as it is, by all means. But if not, then such a change might help to get more contributions here, and thereby more current documentation. Florian -- Florian Ebeling Twitter: febeling [email protected] _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
