I'm seeing many people messing with Portage and Portage settings, based on various input they receive from #gentoo and other channels without knowing what they are doing. Even though the current Gentoo Handbook contains the information they need, it seems that the users are unwilling (or unable) to read and digest the second part of the Gentoo handbook, more precisely the second chapter about "Portage and Software", which imho should be read from top to bottom and backwards by every single user out there. Alongside I hear people asking for a Portage handbook even though they are unaware that most of what they are looking for is described in the Gentoo Handbook, again part 2. I am proposing a rewrite of the second part of the Gentoo Handbook, split into two parts: * Customizing Gentoo * Working with Portage The part "Customizing Gentoo" would contain the following chapters (title's should be sufficient to comprehend): - USE flags - Portage Features - Initscripts - Environment Variables The part "Working with Portage" would contain the following chapters: - A Portage Introduction This would contain everything a user *needs* to maintain software _within_ the stable branch. So "search", "emerge", "unmerge", "update", "sync". A section on masked packages only telling them to stay away unless they know what they're up to (and they have to read the rest of this part of the Gentoo handbook). Also includes information about Portage' configuration file protection and, albeit with a big red warning, information on depclean. - Files and Directories A run-down on all the files Portage uses and their meaning. We don't mind explaining stuff users don't understand immediately, it's for advanced users only - the rest should skip and read the rest and later come back. - Configuring through Variables A run-down on all the variables that can be set in /etc/make.conf by the user. - Mixing Software Branches An in-depth explanation about the various branches, what possible masking can occur and how to resolve them. This latter should be no more than a reference to "Files and Directories" which already talks about the various /etc/portage files and their meaning/syntax. - Additional Portage Tools Explain the use (but don't just copy the manpage verbatim :) of "dispatch-conf", "emerge-webrsync", "g-cpan.pl" and other tools that are usable stand-alone (i.e. that are not execve'd or whatever Python uses by Portage itself). - Diverting from the Official Tree Let the reader discover overlay's, inject's, binary packages, but also how to have rsync skip certain categories. - The Ebuild Application Explain what the ebuild application does. This means a step-by-step explanation on what happens when a user does "emerge <package>" or any other emerge-command and tell the user how to "circumvent" this with ebuild. Any more advanced items (such as full coverage of ebuilds and e-classes, profiles and more) should imho be placed in the developers handbook. Thoughts, comments?
Okay, I'm starting with drafting the layout and such online, see http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml The draft is not functional yet. I've moved the "Introduction to Portage" to the "Working with Gentoo" chapter as it's too important for the users to understand how to work with the "emerge" command. It's even before the "USE flags" chapter as that chapter relies on some emerge knowledge.
Why do you bother asking a question if you don't allow anyone some time to answer? I doubt a rewite will achive anything except generate more work. Lazy users who did not read the current handbook will not read your rewrite. Maybe users should be made more aware of the current content. Look at www.gentoo.org: """ Installation: Gentoo Handbook """ Don't be surprised if users believe the hb is only required to install Gentoo. Besides, users *need* to follow the hb to install, but then find out they can manage without part 2. It's unfortunate, I agree users should read part 2, but you can't force them to. I don't think a rewrite is required, but more could be said about portage/emerge/ebuild and their files, and some reordering would be an improvement indeed.
Of course you can still comment :) I rather start writing stuff so that ppl can decide for themselves if the "new" rewrite is better or not. If not, no sweat, it can be dropped or kept on my dev.g.o. If it is, good. If it's partly (because some sections are better in the new rewrite than with the current one) we can copy/paste. I've just finished writing the introduction to portage. Take a look for yourself and see if you feel it's better than the "Software and Portage" chapter.
Okay, as you can see on http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml I'm almost finished. I just need to check dispatch-conf out since it seems to be a promising tool that many users will appreciate if they know how to work with it. For the time being, I'd appreciate it if people more knowledgeable to Portage can take a look at the Portage-related chapters to see if they contain errors. @portage-folks, could you verify if there are issues on http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml?part=3 regarding Portage itself? It's drafted with .51 in mind (won't be online before then). I'd also appreciate it if you would like to add stuff to it or remove parts.
A few points I noticed: "Well, this isn't exactly a directory but a symbolic link to a profile inside /usr/portage/profiles." There is no technical requirement for a profile to live in the tree. No information on /etc/portage/profile No information on /etc/portage/bashrc (maybe better so ;) "Even though Portage cannot use RPM files, it is able to generate them." This feature isn't really supported and is not accessable with emerge, only with ebuild. The description of the AUTOCLEAN variable is wrong. This variable might be removed in 2.0.52, so it's probably better not to mention it. It's probably worth to mention that there are no official PORTAGE_BINHOST mirrors. Please mention that you have to emerge mirrorselect before you can use it. "it uses to wget by default." s/uses to/uses/ You can also define protocol-specific handlers with FETCHCOMMAND_HTTP, _FTP and so on. "The Portage Features have been discussed in previous chapters." Which chapters ? "when you have updated your system to use the testing branch there is usually no easy way back to the testing branch" no comment ;) "You can also enter a version range using the <=, <, > or >= operators." In the following example you use =
Since it is part of gentoolkit and not Portage, I'm not sure how well it fits in the section on Additional Portage tools. However, I think that a blurb on revdep-rebuild should be on the page. The reasons are it is referenced in several ebuild ewarn/einfo messages when libraries are upgraded. The second is that I have seen confusion from Gentoo Users on what revdep-rebuild is designed to accomplish. A lot of users seem to think that revdep-rebuild will find and fix every possible reverse dependency issue. This is not correct as all it is designed to do is check the dynamic linking of shared objects. For a starting point, if you decide to include it, here is an excerpt from an email I sent to the gentoo-user ML > 'revdep-rebuild -pv' works, thanks! Do I understand well such > command tests overall libs integrity? > Yes and no. revdep-rebuild is designed to do two things 1. When called without the --soname option, it will scan your entire system for shared objects (executables and libraries) for broken dynamic links. When it finds a shared object with broken dynamic linking, it determines what package installed the object and rebuilds it. The theory is that rebuilding the package will fix the problem (It does for 99% of the cases). Two places where it doesn't work is OpenOffice - it appears to broken when it actually is not and binary packages. Dynamic linking isn't the only thing that can be broken. I have seen quite a few reports from people who have upgraded gcc from 3.3 to 3.4 where libraries compiled with 3.3 don't play nicely with stuff compiled with 3.4. However, since the dynamic linking was not broken, revdep-rebuild did not detect any problems. 2. When called with the --soname <some library.so>, revdep-rebuild will scan the entire system looking for shared objects that dynamically link to the library specified. This can be used to force a rebuild of all packages that dynamically link to a specific library. This only works for dynamic linking, it has no way to determine if an object has a static link to a library. To summarize, revdep-rebuild only checks dynamic linking of shared objects.
-- No information on /etc/portage/profile I haven't found any information on /etc/portage/profile in the Portage man page. Care to elaborate on this? -- "Even though Portage cannot use RPM files, it is able to generate them." -- This feature isn't really supported and is not accessable with emerge, only -- with ebuild. True, but as long as it's documented in the (recommended) man pages I see no reason to hide it from the documentation. -- The description of the AUTOCLEAN variable is wrong. This variable might be -- removed in 2.0.52, so it's probably better not to mention it. I've removed it from the documentation, my bad about the wrong description. I'll just keep the CLEAN_DELAY information. -- "You can also enter a version range using the <=, <, > or >= operators." -- In the following example you use = Yes, it's an example that most users probably want (specific version); I just inform the users that they can also use other operators as well. I've now added a sentence informing them about the example. Thanks for the other feedback, I've incorporated them all.
Gentoolkit has a lot of tools that might need more documentation lovin'. I try to keep that particular chapter open for portage-provided applications only (i.e. part of sys-apps/portage). revdep-rebuild has already passed the revue a couple of times in the documentation. I believe the first time a user is informed about revdep-rebuild is in the USE flag chapter, stating: """ When depclean has finished, run <c>revdep-rebuild</c> to rebuild the applications that are dynamically linked against shared objects provided by possibly removed packages. <c>revdep-rebuild</c> is part of the <c>gentoolkit</c> package; don't forget to emerge it first. """
Committed to CVS.
