Website & documentation updates

[Juan Manuel Palacios]

On Oct 14, 2007, at 5:40 PM, Simon Ruderich wrote:

>
> Hi Juan


	Hello Simon!

>
>> This would be a really good move, kudos for taking the initiative!  
>> Only
>> comment I'd like to make is: order does matter in this case, as  
>> having at
>> least some documentation is better than none (even if  
>> misplaced ;-). So
>> could removal of these wiki docs be performed only after the  
>> corresponding
>> content has been added to the guide?
>
> I also thought so. I will notify you and the rest of the dev team  
> when I made
> a change and then you can check if there is something missing  
> before we remove
> the page from Trac.


	Unfortunately, I don't think we can't or should remove any page from  
our trac portal as of yet, even if the new guide already has the  
equivalent content written in, at least until we do at least a basic  
swap of the old project homepage for the new one (wherefrom we  
actually do link to the guide). I'm not, however, claiming we wait  
until the new site is 100% done in order to move it in place -- it's  
already progressing slow enough; on the contrary, I've been itching  
to move it in ASAP, basically barring on Mac OS Forge services  
migrations to new hardware. Once we have an acceptable and working  
version of what's in svn's trunk/www as our project portal (which we  
can always improve once it's up and running), then I do think we can  
start tweaking our trac homepage to remove documents that have  
already been written into the guide. I'll work to make that happen  
this week if possible. So, in a nutshell, hold on just a bit ;-)

---snip---

> Last week I already checked one page, could you (and any other  
> willing to
> help) please look if anything misses in the guide:
>
> http://trac.macports.org/projects/macports/wiki/InstallingMacPorts
>
> http://geeklair.net/new_macports_guide/#installing


	Some notes relevant to the guide after skimming over it:

*) from section 2.1, step 2 in the listing reads "Run the binary  
installer". To me, that phrase seems maybe unnecessarily technical  
and therefore potentially confusing. I would instead just instruct  
readers to run the "Installer Package" contained in the mounted disk  
image.

*) in secttion 2.2.1, I object to the recommended procedure, editing  
a system wide file under /etc. If I recall correctly, the goal of  
launching a login shell from the start in X11 (the very first one  
that greets you after launching X11.app) is equally accomplished by  
simply creating a user specific ~/.xinitrc file that defines "xterm - 
ls &" as the shell to run and then execs quartz-wm. So in a nutshell,  
pretty much what the system wide xinitrc file already does with the  
added "-ls" flags to xterm, with the very important difference that  
system wide files are respected. The menu customization still needs  
to be performed for new shells to be of login type too.

*) in section 2.4, a link to the "MacPorts source" only takes users  
as far as svn's /downloads dir, while some magic could be used to  
abstract an immutable path all the way down to the always-latest  
release directory therein, just as I do in trunk/www/install.php  
through variables defined in trunk/www/includes/common.inc. I'm sure  
something similar can be done in docbook ;-) Using variables and  
adapting them accordingly to our latest release would also, for  
instance, give us always accurate instructions in the configure  
sample code also given in section 2.4.

*) section 2.4.1, instructions to use a custom "--with-tclpackage"  
switch need not urge the users to create the chosen path before hand  
-- it'll be created at installation time just as the default /Library/ 
Tcl is.

*) in section 2.5, setting the bash shell (and in section 2.2.1.  
Optional X11 Settings), it should be noted that the profile  
containing the MacPorts paths is only created if one does not already  
exist. Also there's talk of "MacPorts libraries", while I believe  
that should be something like "MacPorts supplied programs and  
libraries" (likewise for the "vendor-supplied" counterpart). Lastly,  
don't claim that a "complete" profile will look as it is subsequently  
shown, but rather explain that those are the only settings MacPorts  
needs to function properly.

	Those are my notes for what's in the guide, I haven't had a chance  
to review the Wiki doc and make sure that everything in the latter  
made it into the former, though (will try after I wake up ;-). That  
being out of the way, the next step should be, I believe, extending  
the guide with whatever you may find relevant of what I put into  
trunk/www/install.php and reduce this last one to intelligent cues  
that lead the reader into the guide, so as to minimize documentation  
redundancy.... but that can wait, however ;-)

	Overall, very nice work, kudos! Regards,...


-jmpp