Re: [gentoo-osx] Documentation Update

[Kito]

On Aug 10, 2005, at 11:58 AM, Hasan Khalil wrote:


>>>> Please note that there's probably a good deal more documentation
>>>> work to be done, but I feel that it's probably smarter to get
>>>> the updates published in stages rather than all at once. At the
>>>> very least, it allows for better QA analysis of each revision.
>>>> Kito: I apologize in advance if I butchered the description of
>>>> the progressive profile. Please feel free to slap me with a very
>>>> large, very freshly-dead herring, and submit corrections as
>>>> necessary.
>>>>
>>
>> Attached is a rough description of the progressive profile.
>>
>
> Okay, looks like you wrote a good deal there, and I like it. I had
> originally planned on having at least one separate section
> (possibly one per profile) on just what the different profiles were
> all about, but I felt it would be better to implement the changes
> in phases. That being said, I think it's wise to hold off on it and
> just provide a short description for now. Is the short description
> on there unacceptable, even as it's temporary?
>
> Furthermore, I'm not sure that the installation/usage guide, at
> least in its current form, would be a good place for this
> information. What I'd like to see is for the guide to be expanded
> into a proper book with separate pages on each important detail
> (for now, I see at least 4 pages: Project/Installation Notes,
> Installation Guide, Usage Guide, Troubleshooting/Known Issues/
> Whatever). Before doing anything of the sort, I'll consult this
> mailing list, of course. :)
>

Hmmm, not sure I agree... Since the profile is something that should  
be decided during bootstrap.... Since this is what we have, why not  
put it on there now? Sure when this page gets obscenely verbose, we  
can start splitting it up, but I think it would be fine to have  
descriptions there for now...

>
>> I would suggest getting rid of the section telling users to
>> keyword ebuilds directly, and instead point them to the /etc/
>> portage/* files. As more of the base-system packages get the ~ppc-
>> macos keyword for the progressive profile, I suspect users will be
>> confused when they see an ebuild with the ~ppc-macos keyword but
>> still being unable to emerge as a result of it being masked for
>> file collisions on the standard profiles.
>>
>
> I completely agree. I'd really like to ditch the whole section in
> exchange for a paragraph and a link to some already existing
> resource, if some such pertinent resource already exists (maybe
> just refer them to `man portage`?). I don't plan on changing it
> with this release, though; I'd really like to get this through the
> door as quickly as possible since there are some important
> alterations there.
>

Why the big hurry? seems if we are going through the trouble now,  
might as well kill all the birds we can with this rock ;)

>
>> We should probably also mention the fact that the installer has
>> the bug of portage not knowing its installed, so probably just
>> tell them to `FEATURES="-collision-protect" sudo emerge --nodeps
>> portage` to avoid the endless dup bugs being filed and the same
>> question being asked in #-osx.
>>
>
> Absolutely. I'll add this Real Soon Now(tm).
>
> Thanks all for your feedback. Any other issues?
>
> --
>
> Hasan Khalil
> eBuild and Porting Co-Lead
> Gentoo for Mac OS X
>
>

-- 
gentoo-osx@g.o mailing list