MacPorts 1.5.0 and binary packaging / New improved Guide

[Juan Manuel Palacios]

	Couple of quick comments, I see that thankfully you guys already  
have a lot of the details sorted out and the ball is rolling!

On Jul 12, 2007, at 2:30 PM, markd at macports.org wrote:

> Boey Maun Suang <boeyms at macports.org> on Thursday, July 12, 2007 at  
> 10:16
> AM -0800 wrote:
>>> Comments still welcome on the Guide so far.
>>
>> I haven't been through it in detail, but it looks good to me.  I
>> haven't thought too clearly about what, if anything, should become of
>> the old guide (I don't know if a separate technical reference is
>> warranted, which seems to be what the old guide leans towards).
>> Perhaps we can post them somewhere and solicit feedback from users as
>> to what they find easiest to understand and use, and what they think
>> ought to be included or restructured.
>
> I really wanted the new guide to serve as technical reference also, at
> least for now.  I wanted the "Portfile Reference" section to be  
> more or
> less exhaustive.  If that should turn out too large then it could  
> be split
> out into a separate reference, but I'm not sure it will be that large.
>
> My two goals for he new guide was 1) better organization, and 2)  
> more or
> less exhaustive "Using MacPorts" and "Portfile Reference"  
> sections.  The
> latter to give us a place to stick all the helpful information about
> keywords and commands that we exchange on the list now, and often  
> forget.
> Those things should go in the guide but the old guide had no  
> structure to
> contain them, and I don't think a FAQ is adequate.


	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.

>>
>> As for the source of your guide, which I understand is a DocBook
>> article, would be able to put it into the doc/ part of the repository
>> so that we can look at it?  I understand if you'd like to hang onto
>> control of it yourself (saves me some work, for a start :P), but I
>> think it'd be helpful if the source was somewhere that all those
>> interested in the working on documentation could see it.
>
> Here's where I need some advice.  I did the new guide as an  
> "article" and
> in one XML file because that was more familiar to me.  Should I  
> switch to
> a "book" and/or split the XML into multiple files?  Anders has  
> reminded me
> that the copyright information frm the old guide needs to be added  
> back in
> and I haven't got there yet.  Other than that those questions I'm  
> willing
> to commit it to svn.   And I can't fill in the reference sections  
> fully by
> myself anyway so it does need to be committed very soon.  Let me  
> know your
> thoughts on that.
>

	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.

> Mark

	So, what do you guys say? Does this sound like a good protocol?

	Regards,...


-jmpp