Summary: | Possible rewrite of second part of Gentoo handbook | ||
---|---|---|---|
Product: | [OLD] Docs-user | Reporter: | Sven Vermeulen (RETIRED) <swift> |
Component: | Handbook | Assignee: | Sven Vermeulen (RETIRED) <swift> |
Status: | RESOLVED FIXED | ||
Severity: | normal | CC: | carlo, dev-portage, docs-team, earthwings, greg_g |
Priority: | High | ||
Version: | unspecified | ||
Hardware: | All | ||
OS: | All | ||
Whiteboard: | |||
Package list: | Runtime testing required: | --- | |
Bug Depends on: | |||
Bug Blocks: | 67114 |
Description
Sven Vermeulen (RETIRED)
2004-09-23 08:59:13 UTC
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. |