Specifically the "Choosing the Right Profile" section of http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=6 Many users don't twig that its a nested hierachy system, and get quite confused why seeing 2.4 in the output of "ls /etc/make.profile" suggests that they are using a 2.6 profile. I've seen a number of users question this, also questionning whether its a typo in the docs. e.g. after a discussion: 14:45 < smhar> is this right.. I was expecting a 2.6 in the listing to show that it is a 2.6 profile!! 14:47 < smhar> now it is clear.. maybe the guide should elaborate alittle here :-)
The cascading profiles is explained very well on that page that you linked to (Installing the Base System). It even has an explanation (2.4.x kernel) of why you see the 2.4 when you do "ls /etc/make.profile". According to bugzilla this change was made: "Sun Dec 26 14:56:32 2004 UTC (5 months, 1 week ago) by swift". Can we close this bug please?
The amount of times I have seen people confused by this suggests that it needs rewording. I don't see any mention on that page of it being a cascaded or nested profiles system. To gain that knowledge, you have to read between the lines. "As you can see, in the above example there is a 2.4 subdirectory. This means that the current profile uses the 2.6 kernel" Once you've convinced yourself that this might possibly not be a typo, you then read the next bit: "if you want a 2.4-based system, you need to relink your make.profile symlink:" So you then have to compare code listing 9 to code listing 7. Both of which are in a different format, so its not obvious at first what the difference is (plus, the difference is small). At this point, if the reader thinks about it enough, they might consider the fact that it could be a tree-style/cascading/nested profile system. But it seems that many just get quite confused. If you don't agree, please don't close this bug. Reassign it to me and I'll reword it someday when I get the time.
Created attachment 60813 [details, diff] hb-install-system.xml.patch 2:35am is not the right time to commit as I've learnt some time ago :) Rephrased a bit and used same format for both `ls` Please review. Curtis: please don't CC docs team bugs to docs team members. We get enough notifications already. Tx.
In CVS. Feel free to reopen if not clear enough yet.
Still doesn't even mention the tree/nested nature of the profile system, and the new text seems to imply that users should select a 2.4 profile - we should briefly explain the difference or at least say that you should go with the default profile and only relink it if you know what you are doing.
fair enough
Created attachment 60859 [details, diff] fix Sorry to be fussy :) Anyway, I gave it some more thought and have come up with this. Nothing major but I think it should clear things up. It at least avoids the evil "the current profile contains a 2.4 subdirectory. This means that the current profile uses the 2.6 kernel" sentence :)
looks good to me, any last words before commit?
In CVS. Thanks for the patch.
