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