Section 6b Configuring Portage/Choosing the right profile: There is no description of "a profile" which says: (i) The target of the link /etc/make.profile is a DIRECTORY (not a file); (ii) What files are part of a profile and what they do; (iii) That files with the same name all the way up the directory path are relevant, with the lower files taking precedence over the higher ones. The manual doesn't say whether I should edit a profile or not. It doesn't recommend a profile for the first installation (unless the Code Listing 2.2 is a recommendation; it isn't very explicit). Without the above description, sentences such as "The default USE settings are placed in the make.defaults files of your profile" are difficult to understand. Reproducible: Always I am a new Gentoo user, but an experienced Linux user. I was hit by this lack of documentation whilst doing my first installation. This lack has caused me several days confusion and frustration, finally resolved by the good guys on gentoo-user@lists.gentoo.org. See the thread in the URL in this bug report. I have spent (?lost) many hours fruitlessly searching the rest of the Gentoo site for this info. Please fix the docs! Thanks in advance!
We actually *do* say what profiles are, both in the handbook, and in the guide that deals with profiles: http://www.gentoo.org/doc/en/gentoo-upgrading.xml See chapter 6b of the handbook, section 2. The profiles we list, such as the default 2008.0 profile -- it doesn't matter if it's a directory or a file; symlinking still works the same way. Also, in Linux, a directory *is* a file, to state the obvious. As to suitability for a particular purpose, well, we can't really make *specific* recommendations; just general ones. You have to determine your own system's needs. That's why we provide pointers to where the defaults are located; so that you can assess what will be of the most benefit. We already say that the default profile is the recommended one, so your claim -- "The manual doesn't say whether I should edit a profile or not. It doesn't recommend a profile for the first installation" -- is not accurate in the slightest. For more information on profiles and Portage, etc., as mentioned repeatedly throughout all of our documentation, "man portage" is your friend. You may want to check out the full documentation listing here: http://www.gentoo.org/doc/en/list.xml Or categorized, here: http://www.gentoo.org/doc/en/index.xml#doc_chap2
*** Bug 232905 has been marked as a duplicate of this bug. ***
Josh, I think you were too quick to resolve the bug as invalid. Alan told in his description that he's a new user while you probably know the documentation in and out. Your comment does not sound to me, as if you sat back and tried to imagine how the documentation does look like to someone who is not comfortable with the Gentoo specifics. Not having had a look at your documentation for a very log while, I did so now and can only concur Alan's findings. There is not a single sentence in the installation handbook what a profile (directory/file aside) actually _is_. Nor is there a link to extended information for the curious. Unfortunately the more in-depth cascading profile document¹ is seriously outdated. A bug would go to releng, the docs-team or both!? Furthermore I think for new users it would be much simpler to use the eselect utility, instead telling them to symlink manually. Telling a new user to have a look at Gentoo upgrading guide is a bit odd. I wouldn't come to the idea to look at the upgrading guide, if I were new to Gentoo and my bet is you wouldn't either. Similar regarding mentioning the full documentation listing. Our documentation is so elaborate nowadays you could read it literally for day without even starting to install Gentoo. I think this is hardly reasonable. [1] http://www.gentoo.org/proj/en/releng/docs/cascading-profiles.xml
(In reply to comment #3) > Not having had a look at your documentation for a very log while, I did so now > and can only concur Alan's findings. There is not a single sentence in the > installation handbook what a profile (directory/file aside) actually _is_. I disagree; I've already cited chapter and section that *does* explain it. Read: http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=6#doc_chap2_sect2 > Unfortunately the more > in-depth cascading profile document¹ is seriously outdated. A bug would go to > releng, the docs-team or both!? Documents in /proj/ belong to that particular project. > Furthermore I think for new users it would be much simpler to use the eselect > utility, instead telling them to symlink manually. Well, then eselect needs to be shipped by default on the stages, and/or should be included in the system set. The problem is that it is clearly *not* something essential, thus doesn't belong in "system" with e.g. the toolchain, net-tools, and so on. We have users to manually symlink their profiles in the handbook 1) because eselect isn't available and 2) it's good practice.
Josh, you wrote: >> Not having had a look at your documentation for a very log while, I did so now >> and can only concur Alan's findings. There is not a single sentence in the >> installation handbook what a profile (directory/file aside) actually _is_. >I disagree; I've already cited chapter and section that *does* explain it. >Read: >http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=6#doc_chap2_sect2 I had actually read that section when I submitted the bug report. It explains profiles only in abstract terms. That explanation was inadequate for me, a new Gentoo installer, to set up my profile. For example, I didn't (and still don't) know what exactly is meant by a "building block" in Gentoo. The text says what a profile _does_, but not what it _is_. For me, it was the epitome of frustrating vagueness, thought this was clearly not intended. For it to have been useful to me when I needed to understand it, the explantion would have needed to say something like "all the files called foo, bar, and baz in the tower of directories from the specified one up to /usr/portage/profiles (or whatever that root is)." I was unable to progress with my Gentoo installation without getting help from the mailing list on this point. Given the excellent expliciticity of the rest of the manual, which I though gave exactly the right amount of detail, recipes which never got overbearing or patronising, this particular bit stood out like a sore thumb. Please amend it, sometime soon.
Created attachment 162419 [details, diff] proposed additional detail about cascading profiles 2008.0 This is a proposed patch to the installation handbook. The content could also be used on the FAQ paqe with minimal editing. I included a warning and example code, figuring it would be less effort for you to delete them than create them. The example code is valid for all 2008.0 archs *except* powerpc (needs extra '../' on path to ...releases/2008.0). I wasn't sure how to test a function to change the <pre _ </pre> example, so figured a working patch was better than a totally cross platform example. There is certainly a need for more information about profiles for (at least) new users during first installs. It is a question that comes up regularly on IRC. As far as the forums go, many new users haven't figured out how important they are, or how to effectively search. Besides, a forum search on something you don't understand is a lot to sort through during an install. Likewise for gentoo docs not linked directly in the handbook. If I'm brand new to gentoo I read "You may wish to view the desktop profile's make.defaults to determine if it fits your needs." and say, what? There is no make.defaults in .../desktop, just some file called parent. (Remember there has been no notion of parenting or hierarchies anywhere in the docs yet. 'parent' means nothing to many users at this point.) Then I think back to the earlier paragraph about it setting defaults for my system and I think "Wow, I better make the right choice. This affects *everything*!" Then I waste time googling and trying to set up IRC and finally end up picking the default anyway, but feeling anxious and frustrated about something that really isn't that big a deal. It would have helped me to have more info easily available during my first few installs. I wasted a lot of time afterward changing around use flags and fighting my profile till I happened to find a forum post like http://forums.gentoo.org/viewtopic-t-699886-highlight-profiles.html that didn't contain contradictory info, started to understand how things worked, and finally read through the profile subdirectories. IMHO this much detail doesn't have to be in the handbook, but at least a link to a fuller explanation in the FAQ or some other doc needs to be there. Thanks for all you do, nightmorph. You must have an incredible workload. I won't get my feelings hurt if you don't apply this, but I will keep looking for ways to reduce new user confusion.
I do not believe it is important for a user to exactly know what a profile defines at this stage, as it is not mandatory for an installation. The text inside the handbook covers what most users should know (if not more already); a more detailed approach at profiles is outside the scope of this document.
(In reply to comment #7) > I do not believe it is important for a user to exactly know what a profile > defines at this stage, as it is not mandatory for an installation. The text > inside the handbook covers what most users should know (if not more already); a > more detailed approach at profiles is outside the scope of this document. I agree entirely. However, would it be worthwhile to add some additional clarifying material to one of our other documents? See comment #6. The only problem there is that it's replacing one bit of technojargon with another, with dizzying ../../../ locations and phrases like "flat files." Perhaps there's somewhere in one of our Portage handbooks where we can provide a gentler, somewhat more in-depth introduction to profiles? Otherwise I'm all for closing this bug.
> (In reply to comment #7) > I do not believe it is important for a user to exactly know what a profile > defines at this stage, as it is not mandatory for an installation. The text > inside the handbook covers what most users should know (if not more already); > a more detailed approach at profiles is outside the scope of this document. With the greatest of respect, _this_ user, I, most definitely _did_ need to know what a profile was; the (otherwise excellently documented) installation procedure required me to set one. The text in the handbook most assuredly did NOT cover what I needed to know. This lack cost me several days delay, frustration and anger. If you are right about it not being important for "a" user to understand profiles, then there is something really wierd about me, some wierd cognitive disability I suffer that doesn't trouble any "normal" user. I don't believe this to be the case, and I am not happy that you have made such an insinuation on a public list. Let me emphasise, I reported my EXPERIENCE as a new Gentooer, and took the time and trouble to send feedback to the maintainers, mainly out of a sense of moral obligation. In return I expected, at the very least, a courteous "thanks for the report, we'll look at this and fix it if need be". I am well acquainted with free software, including several other distributions of GNU/Linux. By contrast, you are merely speculating, presumably as an experienced Gentoo installer, about what you think new users need to be told. I think you are wrong. And yes, I still believe Gentoo is the right distribution for me.
Created attachment 165078 [details, diff] hb-install-system.xml.patch Josh, I agree that profiles not that important during installation but new users feel different and really fuzzy description of what profile is make this part of handbook not so useful. Personally during attentive handbook reading (actually editing Russian translation) I also was going to supply some patch and change this part of our handbook as the definition of profile is hard to understand. Now based on patch from Wirt I apply my own patch to change that definition. If you'll decide to write your own patch, please, notice: 1. that it's good idea to mention USE variable explicitly, users often ask where does defaults come from 2. "building block" is really hard to understand. Even now after some years of using portage I'm not sure that building block is good definition for profile as it merely sets defaults...
I still don't see why the majority of users would need any knowledge of cascading profiles. Not that I think the current text can't be improved, but adding too much new information here would only make the installation harder to perform. Perhaps the Gentoo Upgrading Guide (http://www.gentoo.org/doc/en/gentoo-upgrading.xml) can be improved (in this document, more detail could be very well in place) and can be linked to from the installation guide?
Created attachment 188630 [details] proposed paragraph inclusion from a new user perspective
I'm a new gentoo user and I also thought the handbook didn't make it clear. I want to help clarify this. Afaik, I think I might have worked it out, though I'm not an expert: an expert might want to correct me. I offer my suggestion for inclusion into the (maybe only x86) handbook, hoping that it's correct and that you like it, in section 6b right after the sentence "First, a small definition is in place."
just thought... I missed out a 'see below' where I have mentioned USE flags when we haven't yet looked at them.
The root of the problem seems to be that users are confused by the filesystem layout of profiles within the tree (and exactly where make.profile is supposed to link to). In my opinion, Gentoo could easily resolve this by hiding the implementation details through simply including eselect in stage3 (bug #234310 ) and instructing users to use that for profile selection. At the very least, using eselect ensures they have a valid profile symlink, and greatly reduces the number of possibilities from the users point of view. It would greatly simplify the users view of profiles down to something much more manageable.
What we have in there is fine as it is. It's best to abstract the nitty-gritty details that would otherwise bog down a user, as explained in the comments. Now that eselect is included in our installation media, it obviates the need to get into tricky technical explanations of where stuff is or how to set it. Closing.
