>>> + 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.
There are several issues that I think have made wikis not sufficiently attractive for us. 1) Editorial control - It isn't practical for many people to make major edits. It can fragment the docs so they lose overall coherence. However, one of my goals for the new guide was that incremental changes were easy to make and I think we have had some great commits of additional reference material by our base coders and I thought that was great. 2) Single source - We want to source the man pages out of the guide and we're really only a few days of hard work from that, despite the fact that not a lot of documentation work has happened in the past year. Using a single source is the only way to have accurate docs and guide, which will eliminate a lot of work and the innaccuracy that has plagued the docs in the past. I think docbook works well considering the overall goals we have. And i think the goals will make for better and more accurate docs. The single source issue is huge -no way for us to have separate man and guide docs that are accurate otherwise. And I don't think we can do that without xml. Also, I use a wysiwyg editor so I do very little xml coding directly. And I'm open to any method of contribution. Using Trac leaves something to be desired. Maybe a wiki scratchpad of some sort would be better. And at least by summer's end I intend to have the missing parts of the guide filled in and make a transition to the single source man pages with Simon's help. I understand your frustrations though, so I'm not sure how satisfying these answers will be. But I hope that helps. Mark _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
