Several problems I had while attempting to install gentoo were due to lack of information related to emerge. I suspect that the people who wrote the detailed installation guide were all expert gentoo users. I think there's some basic ideas that the novice needs to be told, that would improve the guide even more. So, here are some thought from a gentoo novice - I hope they are helpful. Quite a few things can go wrong during the install (like being required to update portage, and not knowing how to do that, or needing to install a package because of a dependency: e.g. openssl-0.9.6k requiring perl5), but there isn't enough info to do these basic things. In the installation guide, code listing 5 says that "emerge sync" updates portage. "emerge --help" doesn't give enough info to the novice to inform them how to update portage. emerge --help specifies several actions (clean, depclean, info, inject, prune, regen, search, unmerge), and *none* of them seem to relate to installing or updating a package. emerge [ options ] [ action ] [ ebuildfile | tbz2file | dependency ] [ ... ] emerge [ options ] [ action ] < system | world > emerge < sync | info > emerge --resume [--pretend | --skipfirst] emerge help [ system | config | sync ] You'll also notice that the help doesn't describe what system or world mean, what an ebuildfile is, or a tbz2file is, or even what an ebuild is. I guessed "emerge portage" was the right thing to do to update portage, but from followup reading I've done since, it seems that's quite wrong. (Incidentally, it fails because of a dependence on j2sdk-1_4_1-doc.zip.) I gather that portage is not a package, though I hope I can be forgiven for thinking that it was, and looking for a way to update that package. I assume from looking briefly at the portage user guide, that it's some more general thing, since the actual command to "update portage" is said to be: emerge -u system In other words, "portage" is almost a synonym for the system as a whole. It would be very helpful if the message that strongly urges you to update portage actually spelled out the required command: emerge -u system. Likewise, if you get an error that includes the comment "see the comments in the ebuild for more information". But what is the "ebuild"? Is this message referring to an actual file? If so, the error message needs to provide the full pathname. Another thing I noticed during my attempted install, is that there's a huge amount of output from the big emerge commands. Perhaps the guide could recommend running something like: emerge system > /tmp/emerge.out 2>&1 && tail -f /tmp/emerge.out I reckon you'd get lots of people not realising when it finished, though, so some wrapper that ran emerge, waited for it to finish, and killed the tail -f at the end would be a nice touch to include in the basic system. Reproducible: Always Steps to Reproduce: 1.Read the installation guide 2.Follow the steps until something unexpected happens 3.Try to guess what actual commands to type to continue. Actual Results: Eventually, my attempted installation failed. Expected Results: The error messages should have given more precise instructions. I'm running RH 7.2 right now, but have chrooted into my partial gentoo installation, so this may be acceptable: bash-2.05b# source /etc/profile posh / # emerge --info !!! No gcc found. You probably need to 'source /etc/profile' to update !!! the environment of this terminal and possibly other terminals also. Portage 2.0.49-r4 (default-x86-1.4, [unavailable], glibc-2.3.2-r1, 2.4.23) ================================================================= System uname: 2.4.23 i686 ACCEPT_KEYWORDS="x86" AUTOCLEAN="yes" CFLAGS="-O3 -march=pentium4 -funroll-loops -fprefetch-loop-arrays -pipe" CHOST="i686-pc-linux-gnu" COMPILER="gcc3" CONFIG_PROTECT="/etc /var/qmail/control /usr/share/config /usr/kde/2/share/config /usr/kde/3/share/config" CONFIG_PROTECT_MASK="/etc/gconf /etc/env.d" CXXFLAGS="-O3 -march=pentium4 -funroll-loops -fprefetch-loop-arrays -pipe" DISTDIR="/usr/portage/distfiles" FEATURES="sandbox ccache autoaddcvs" GENTOO_MIRRORS="http://gentoo.oregonstate.edu http://distro.ibiblio.org/pub/Linux/distributions/gentoo" MAKEOPTS="-j2" PKGDIR="/usr/portage/packages" PORTAGE_TMPDIR="/var/tmp" PORTDIR="/usr/portage" PORTDIR_OVERLAY="" SYNC="rsync://rsync.gentoo.org/gentoo-portage" USE="x86 oss apm berkdb 3dfx alsa arts avi bonobo cdr cjk crypt cscope cups dga directfb doc dvb dvd dvdr emacs encode ethereal evo fbcon flash foomaticdb gb gd gdbm ggi gif gnome gphoto2 gpm gstreamer gtk gtk2 gtkhtml guile icc icc-pgo imap imlib jack java jikes jpeg junit kde kerberos krb4 ladcca lcms libg++ libgda libwww lirc mad mbox mcal mikmod memlimit mmx motif mozilla mpeg mpi nas ncurses nhc98 nls nocd oggvorbis opengl pam pda ppds pdflib perl plotutils png pnp python qt quicktime readline ruby samba sasl scanner sdl slang slp snmp spell sse ssl svga tcltk tcpd tetex tiff truetype usb videos wmf wxwindows X Xaw3d xface xinerama xosd xml xml2 xmms xv zlib"
Hi Luke, Thanks for the feedback. I'll try and summarize my ideas on your proposals. First of all, when the user hits a problem during the installation of Gentoo, this is seen as a serious problem. Not because it is unexpected, but because we can't predict how new users react to the situation. In this case it is better to fully inform the user what to do instead of letting them guess. For instance, when you're told to upgrade portage, you shouldn't do anything - period. This is mentioned in the official installation instructions: """ http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=6 If you are warned that a new Portage version is available and that you should update Portage, you can safely ignore it. Portage will be updated for you later on during the installation. """ When a package needs to be installed due to a missing dependency, this should be resolved much faster by updating the ebuild than the documentation. This is fairly trivial, as the ebuild is erroneous and not the documentation, and ebuilds are evenly fast updated (once an hour) as the documentation. Probably faster even, since there are many more ebuild developers who can update the malfunctioning ebuild than there are documentation developers (but we're very active!! :) Next, during the installation the user shouldn't be informed on how emerge works. This is for later, when the user has a functioning Gentoo installation. During the installation the user can't test/try what he has learned and a Gentoo installation already takes up a considerable amount of time -- talking about Portage and emerge and all other Gentoo specific stuff isn't meant for the installation instructions. I have a clear vision on the installation instructions (I'm purely talking about the Gentoo Handbook, Part 1, "Installing Gentoo" as the other guides will be removed with Gentoo's next release): they should contain all the information necessary for a user to succesfully install Gentoo, but not a word more. The information on, USE flags, Portage, emerge, initscripts and all other Gentoo-specific material is discussed in the second part of the Gentoo Handbook ("Working with Gentoo") as the user then has a working Gentoo installation. I know this is a blade that cuts from two sides and your points are indeed valid, but it is my strong believe that the discussed situation is better. Now on Portage, we try to talk about "the Portage tree" when we are talking about the collection of ebuilds and profiles and about "Portage" when we are talking about the code itself. Moreover, "the Portage tree" resides in /usr/portage while "Portage" resides in /usr/lib/. If you find any location where we talk about Portage while we mean "the Portage tree" or vice versa, please report it so we can update it.
Marking as wontfix...
Thanks for the explanation, Sven. In that case, I'll revise my feedback as follows. 1. If the novice user ins expected to disregard the strong recommendation to update portage, then the wording on that should change. Currently, the novice is pushed down that path, and as I discovered, it stops the installation. (Note also that the user guide doesn't say you shouldn't update portage - it says it's safe not to do so. So the "strong recommendation" carries more weight.) 2. In your explanation, you talk about portage and "the portage tree". Both terms will mean similar things to the novice installer. Making sure you use the right term consistently will help more advanced users, not novices. 3. You also mentioned ebuilds. That's a term I still don't understand. I don't think it's explained or described anywhere in the installation guide. E.g. you say: "When a package needs to be installed due to a missing dependency, this should be resolved much faster by updating the ebuild than the documentation" By this I think you mean that if there's a problem and the install fails, a developer will quickly fix the problem, so the user can just try again. But I don't understand how the developer learns of the user's problem, and I don't understand how the user knows that they should just wait for a few hours or days and then try again. If that's what they should do, perhaps a failed install should ask for some info and assist the user in providing a bug report. E.g. when my installation failed because I included both A and pam in my USE variable, do you mean I should have just quietly waited until it was fixed? Surely you'd prefer to allow some of your users to be less passive if they felt that way, and give them some information so they could try to resolve the problem themselves? 4. When a problem occurs and the user receives the message "see the ebuild for more information", that is a dead end. The novice has no idea what an ebuild is, or where they should look for more info, so they are likely to give up on gentoo at that stage. You also said: "Now on Portage, we try to talk about "the Portage tree" when we are talking about the collection of ebuilds and profiles and about "Portage" when we are talking about the code itself. Moreover, "the Portage tree" resides in /usr/portage while "Portage" resides in /usr/lib/. If you find any location where we talk about Portage while we mean "the Portage tree" or vice versa, please report it so we can update it." You'd know better than me whether the point in the gentoo installation where it says "A new version of portage is available. You are strongly recommended to update portage" (or something like that), means portage or the portage tree. Though, as I've said, whichever term you use there won't make any difference to the novice, and they're very likely to dutifully follow those instructions, and get into difficulty. Anyway, even with our philosophical differences (you want to reduce the info available to the user, to avoid confusing them - I prefer to give them extra info, and let them choose for themselves), I hope these suggestions may be useful to you. I'll reopen this bug, just because I'm not sure if you'd ever see these comments if I didn't. I won't reopen it again - I'm not trying to annoy you! Best regards, luke
Typos in what I wrote: If the novice user ins expected --> If the novice user is expected E.g. when my installation failed because I included both A and pam --> E.g. when my installation failed because I included both X and pam Sorry about that. luke
Hi Luke, Telling the user that he "may not" update Portage makes him believe that our installation process is flawed and that the documentation has been changed to fix such a bug. As I'm totally opposed to using documentation to fix bugs that should be fixed otherwise I don't use such strong wording. We tell the user he can "safely ignore" it which is sufficient for the majority of the users. If the user wants to update Portage nonetheless, he may do so. In most cases this wont introduce a problem. Sadly enough, in some cases it does. I also don't believe that the installation instructions are the right place to introduce the user with Portage, the Portage tree, ebuilds, etc. The installation instructions are just that: installation instructions. They are meant to guide the user through the installation process on a step-by-step basis. Informing the user about the Gentoo specifics can be done after the installation (when the user has an installed Gentoo system) or, if the user wants, before the installation (he just has to read the second part of the Gentoo handbook). I used Gentoo-specific terms in my previous explanation to inform you, not to describe what users should know, but to let you know why I feel it is less important for the user to know it at that stage. Sometimes the installation fails because of a developer error. This doesn't happen frequently, but since Gentoo evolves very fast, it does happen. The QA team tries to minimise this as much as possible, though. In case an error does happen, the user who wants to aide Gentoo is asked to provide a bugreport as is mentioned in the beginning of the guide: """ If you find a problem in the installation (or in the installation documentation), please visit our bugtracking system and check if the bug is known. If not, please create a bugreport for it so we can take care of it. Do not be afraid of the developers who are assigned to (your) bugs -- they generally don't eat people. """ There is imho not more we can say. It is also less important as most users who receive errors don't fill in bugreports (sadly enough) because they don't want to go through all that trouble. In your case (the USE flag issue) you have several choices: (1) you bugreport your issue and have a warm, fuzzy feeling because you helped the development of Gentoo, (2) you ask it to the community (forum, mailinglist, irc) (3) you want and retry (4) you step down Those options are all described in the beginning of the installation process. Again, you might feel that those instructions are hidden in some forgotten paragraph, but installation failures are not that common so it would be just plain wrong to use a big, fat font to warn and scare people as if the installation always borks. Error/warning instructions printed to screen come from the ebuilds themselves (the "package format" Gentoo uses) which we can't change as they are used not only during the installation, but also through the lifetime of your system. We should *never* reduce the error messages to something that might sound good for novices but aren't helpfull in resolving the issue. As you install Gentoo, it won't take long before you learn what an ebuild is, and if you still don't, such error messages will most likely trigger your quest for information and have you search what ebuilds are. One point of Gentoo as metadistribution is to have the users learn. This process is enforced through both documentation and experience.
Hi Sven, You wrote: "Telling the user that he "may not" update Portage makes him believe that our installation process is flawed and that the documentation has been changed to fix such a bug. As I'm totally opposed to using documentation to fix bugs that should be fixed otherwise I don't use such strong wording. We tell the user he can "safely ignore" it which is sufficient for the majority of the users." But you (well, the gentoo install) also tells the user that he should update portage. All I'm suggesting is that the bug is in the documentation, if I can be allowed to call the output from the gentoo installation that helps guide the user in doing the installation, as part of the documentation. I think a more liekly reason that this doesn't cause problems for the majority of users is that they don't see how to update portage even when recommended. I very much doubt it's because they remembered a gentle remark from some hours before. The document also says that if you are not using GRP you *must* download a recent portage snapshot, and emerge sync does this. So the documentation is sending strongly mixed messages in this instance. I also think it's a problem in the documentation that "GRP" is referred to quite often, but defined only once. It's easy to miss: I only stumbled over it today. I doubt I could find it again. Can I suggest removing that acronym and spelling it out in full? It would be kinder to the reader: one less definition to remember. You wrote: "I also don't believe that the installation instructions are the right place to introduce the user with Portage, the Portage tree, ebuilds, etc. The installation instructions are just that: installation instructions." Agreed. But things go wrong, and do go wrong, as demonstrated by the active and very helpful forums. I couldn't have got my gentoo system working without them. So, in my opinion, adding some extra info to the user guide, maybe in a troubleshooting section, would help quite a lot of users who are trying to install gentoo. You wrote: "In case an error does happen, the user who wants to aide Gentoo is asked to provide a bugreport as is mentioned in the beginning of the guide:" True, but how many users remember that? There is also much more effort in using the bug tracking system to fill out a high-quality bug report than there would be in just firing off an email to a bug-report list. You're probably right to do it the way you do, though. My only suggestion would be to repeat the reminder in the hypothetical trouble-shooting section I've suggested, and perhaps even give some guidance on how you like the reports filled in, and how it helps. You wrote: "There is imho not more we can say. It is also less important as most users who receive errors don't fill in bugreports (sadly enough) because they don't want to go through all that trouble." Oh! Which reminds me of a nasty problem with bugzilla which would also dramatically reduce the number of bug reports you'd get. If you fill out a bug report (as I did), possibly spending an hour on it (as I did), and forget to fill in a required field, bugzilla can't process the bug and tells you to hit the back button. But when you do that, all the fields you've filled in get wiped out! Assuming a reasonable percentage of users make a similar slip-up, a lot would not have the patience to fill out the report all over again. You wrote: "In your case (the USE flag issue) you have several choices: (1) you bugreport your issue and have a warm, fuzzy feeling because you helped the development of Gentoo, (2) you ask it to the community (forum, mailinglist, irc) (3) you want and retry (4) you step down" Yep, I did (1), twice, for some other issue, and started doing it for the USE problem. Doing the search before proceeding, as per the bug reporting instructions, lead me to the forum posting which had the same problem and even the resolution. You wrote: "Error/warning instructions printed to screen come from the ebuilds themselves (the "package format" Gentoo uses) which we can't change as they are used not only during the installation, but also through the lifetime of your system. We should *never* reduce the error messages to something that might sound good for novices but aren't helpfull in resolving the issue." I agree. I was suggesting adding detail to the error messages so that they would be useful to novices as well as more advanced users. You wrote: "As you install Gentoo, it won't take long before you learn what an ebuild is, and if you still don't, such error messages will most likely trigger your quest for information and have you search what ebuilds are. One point of Gentoo as metadistribution is to have the users learn. This process is enforced through both documentation and experience." I know it's an effort to produce good documentation, I've been involved it it a lot. Do you really mean that problems in the documentation are good, because they encourage users to learn?! The way to encourage users to learn something new is to make them feel empowered, and tell them enough so they understand what they're doing. I think it's only geeks that are motivated by problems and obstacles. Just my 2c. Best regards, Sven, luke
[Updating Portage] The user gets the message during installation, but we can't remove that message only during installation as it is the same message the user will receive when he is updating an already installed Gentoo system. The documentation mentions that you can ignore this, so ignore it. And if you don't want to ignore it, then don't, but don't blame issues on Gentoo :) [GRP] If I would write out GRP as "Gentoo Reference Platform" users will still not know what it is. Telling them it is the use of prebuilt packages every time again is a plausible solution, but I'd rather have the users talk about GRP as "prebuilt packages" is a bit more broad than GRP. If they would ask questions about prebuilt packages they might be misunderstood if they are really talking about GRP. [Remembering what to do when things go wrong] I disagree. If we would continuously stress every important or less important point, the installation instructions would triple in size as most (if not all) sections are important. [Learn by trying] I don't mean that the documentation should contain errors so that the user can learn from them. I'm not going to allow documentation to contain errors. I am going to allow the documentation to contain information that might be misinterpreted by some people. Unlike source code, you can't make documentation "just right" for everybody.
