Yesterday a user went onto IRC to flame a bit about emerge's output to his attempt to merge a package marked for testing: -------------------------------------- For more information, see MASKED PACKAGES section in the emerge man page or section 2.2 "Software Availability" in the Gentoo Handbook. -------------------------------------- The problem is, section 2.2 does not exist anymore. (Maybe this calls for another bug report about the Gentoo Handbook, but it seems most of the section numbering is gone from the Handbooks.) From Google's search results, it seems a section by the name of "Software Availability" was still present as late as 2004.2. Judging from the current Gentoo x86 Handbook, it seems the user should probably be directed toward something with the header "3.b. Mixing Stable with Testing". It's hard to tell at a glance from the TOC because that header is not mentioned there, but it appears to be section b ("Mixing Stable with Testing") in chapter 3 ("Mixing Software Branches"), from part C. ("Working with Portage") of the Gentoo Handbook. It might also be noteworthy to be aware that for this user, the MASKED PACKAGES section in the man page turned out to be impossible to find, because he did a search in the man page using '/masked packages' and did not know that most common search options in Gentoo are set case-sensitive by default. Again, this may either be a documentation bug or this same bug: users ought to know that Gentoo is rather case-sensitive. The end result was that he couldn't find either source of information and went out to find someone who could tell him. The main reason I am filing this bug is, that this happens all the time and many experienced Gentoo users on IRC are starting to think that n00bs are dumb. Reproducible: Always Steps to Reproduce: 1. Leave documentation and emerge's error output as is. 2. Wait for new user to stumble over this problem. 3. Explain to new user on IRC. 4. Rinse, Lather, Repeat.
Point taken. Best solution would perhaps be to just not include any external pointers at all as they can become invalid at any time. Any suggestions on how to be helpful that'll go the distance? ;)
(In reply to comment #1) > Point taken. Best solution would perhaps be to just not include any external > pointers at all as they can become invalid at any time. Any suggestions on how > to be helpful that'll go the distance? ;) Basically, set up a specific "emerge b0rks" web page and man page and refer to that... :) But let's see: ------------- *teh hppa system* ~ # emerge -vp quake3 These are the packages that I would merge, in order: Calculating dependencies !!! All ebuilds that could satisfy "quake3" have been masked. !!! One of the following masked packages is required to complete your request: - games-fps/quake3-1.32b-r3 (masked by: -* keyword) - games-fps/quake3-1.31 (masked by: -* keyword) For more information, see MASKED PACKAGES section in the emerge man page or section 2.2 "Software Availability" in the Gentoo Handbook. ------------- Why not at least remove emerge's *specific* references to the Handbook and man page? Alternatively, you might want to go all *radical* and have emerge say something quite intelligible at this point, like: This package has not been marked testing or stable for your type of system. You may want to override this using ACCEPT_KEYWORDS or package.keywords. As emerge has the ability to detect and report the type of problem, I imagine it wouldn't be very difficult to add specific error descriptions like this one. The explanations in the Handbook are quite clear, as long as they can be found: pointing someone to go look through dozens of pages is not the way to go. (Btw, part 3, "1.d. When Portage is Complaining..." appears to be another helpful section in the Handbook.) A more durable approach would probably be to have the Docs project set up a *short* document at a fixed location (or three: a web page as a URI, and a man page as LRI) titled something like "Troubleshooting Portage" (or indeed "When Portage is Complaining"), and also have sys-apps/portage refer to that document and include the man page with the same content as the web page in that package. OT: Another helpful idea might be to clarify the use of the terms "mask", "masked" and "masking" better. The dual use of signifying when a package is: 1) blocked from installation through keywords or package.mask, and 2) actually masked: being identified in a package.mask in the tree. It's obvious which is meant to anyone with experience using Gentoo, but it's utterly confusing to new users when a term has two meanings, especially if one meaning overlaps the other, as in this case. Masking to me generally means being filtered out or blocked from view, whereas blocking generally means being made inaccessible. Blocking in portage's lingo happens when one package is prevented from merging while another, blocking package is merged. Equally, a missing keyword might block the installation of a package. Now I don't intend to turn this bug into a philosophical discussion about terms and meanings, but surely it shouldn't be too difficult to browse through a thesaurus and find specific words for portage's specific features and behaviours?
Fixed in portage-2.0.53_rc3
