Re: [gentoo-osx] Documentation Update

[Hasan Khalil]

On Aug 10, 2005, at 10:50, Kito wrote:

> On Aug 10, 2005, at 12:42 AM, Grobian wrote:
>
>
>> Two small things that I don't know for sure:
>>
>> | Warning: Using any shell besides bash is currenly unsupported
>> and most
>> | likely won't work. You should change your default shell in
>> Terminal by
>> | clicking on Terminal->Preferences (in the menu bar), chosing the
>> | "Execute this command" option, and entering /bin/bash.
>>
>> How likely is this?  Of course I ignored this warning when
>> installing my Gentoo, because I feel hopelessly lost in bash.  On
>> the one hand, is it known what causes trouble? and on the other
>> hand, considering the default shell is bash from 10.3 (at least
>> 10.4) also for the root account, and everything is done using
>> "sudo su", how likely is it the user will use a different shell
>> for the root user than the system provided one?  On top of this,
>> whenever the whole emerge system is getting into action a bash
>> shell is forked from python I think, so what relevance is the
>> parent shell to that?
>>
>
> Yeah, I've always used zsh myself, with no problems to speak of.

The note has been deleted in the latest revision. Thanks Kito and  
Fabian for pointing this out.

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

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

> 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