Juan Manuel Palacios <jmpp@macports.org> on Thursday, July 12, 2007 at 5:24 PM -0800 wrote:
First off, and even if it's just a first draft that we can improve as we learn from experience, I'd like to see a single all- encompassing guide too, with a "users oriented" first section and a "developers" section in which we can put all the Portfile reference stuff and others not geared for regular users. If this proves to be hard to manage and a lot of voices raise up asking for a "simple and short user reference", I'm figuring we can always take the contents of the rewritten guide and split them up in two.
My thoughts exactly. Though I did not end up dividing cleanly into users/developers parts, I personally think that since even newbies these days sometimes ask "How do I modify a Portile?", that the guide is better sectioned functionally according MacPorts itself, rather than by hypothetical types of users. But still, more or less the first part is the "using" part, the middle part tends towards development, and the end is pretty advanced stuff. Not clear lines, but I think the sections make the guide fairly intuitive nonetheless. At least I hope, and others are certainly free to disagree or suggest changes.
We spoke about committing to svn and you expressed your thoughts and concerns about it, but I didn't manage to reply at the moment due to a lack of time. In a nutshell, I'd really love to see your work in our tree so that all those willing to contribute can do it in a more timely fashion (I know I would have already contributed three or four fixes if I had access to the sources ;-). But I understand that since you're not amending what we have but actually rewriting it, you prefer to keep from committing until your sources become an actual drop in replacement for what's already there.
So how's the following: you write up the new guide up to the point where it can replace to a good extent what we have, even leaving empty certain sections/areas if you have to because you don't have enough information to write it up on your own, and you commit that? Once that's in all of us can dive in and help you complete it. I'm even thinking that for the sections you can't rewrite, but what's in the old guide suffices for them to whatever extent, you can simply copy & paste that into the new sources and write up a marker saying "THIS IS OLD, NEEDS REWRITING!" for contributors to notice.
More over, we can all agree to nominate Maun Suang and you "Guide Masters": rather than simply diving in and committing patches to the sources in svn, we instead upload them to tickets in the "Documentation" milestone and you guys, governing that milestone, review them and decide when/how to commit them, rewriting them if need be.
Sounds like a decent plan to me. I just committed what I have so far. xml/newguide.xml http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/xml/new... resources/newdocbook.css http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/resourc... Hack away! Needs work in the reference sections, among others. 6.2 and 6.3 have placeholders for keywords and Tcl primitives respectively. Full comments in the svn checkout logs. See the the updated copy with a slightly different stylesheet at my .mac page for those wanting a peek at the draft of the new guide. Colors are awful! You have been warned! http://homepage.mac.com/duling/macports/guide.html Mark