Checked in the current draft of the new guide

[markd at macports.org]

Juan Manuel Palacios <jmpp at 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/newguide.xml?rev=26949

resources/newdocbook.css
http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/resources/newdocbook.css?rev=26950

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