MacPorts 1.5.0 and binary packaging / New improved Guide

[markd at macports.org]

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.
>
>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.

Mark