I suggest here some updates to some man-pages (as found in portage-2.0.47-r10). Apart from some cosmetic changes, the important issues were: emerge.1: - say what "-u" and "-v" _really_ do - add an exmple of a pretended install where a newer version is present but not downgraded due to SLOTS - remove two old warnings - clarify meaning of use.defaults ebuild.5: - correct wrong FILESDIR definition - add an explanation for PDEPEND make.conf.5: - correct FEATURES These are leaved to your judgement... by the way... is a revisitation of portage manual and guide planned in some way? those documents are really outdated (eg. code sections)! need help?
Created attachment 9856 [details, diff] the diff
Created attachment 9857 [details] the diff
Created attachment 9858 [details] the last diff
And yes... if you consider that is more valuable a big single effort to resync manpages with current portage status and features, opposed to small corrections, let us now! :-)
By all means, if you would like to do more updates or larger ones, feel free. It saves me a lot of time, and it's appreciated by a lot of people. Thanks.
Ok, i'm posting a more coherent effort to "refresh" portage documentation. Portage-2.0.47-r12-doc.diff is a patch against portage tree that provides: - switch to the new syntax (is this a bad thing?) - some minor updates to emergehelp.py - "help" update in ebuild.sh - a complete resync of the emerge.1 manpage with emergehelp.py - little changes in ebuild.1, ebuild.5, make.conf.5 manpages In addition, I post an update of the portage-user.xml guide which hopefully reflect latest portage developments. (Refresh is also needed for portage-manual.xml, e.g. epm and etc-update are no longer in gentoolkit, feature list needs update...). I'm dropping a note on gentoo-doc if someone wants to review these changes... Clearly these changes are intended as "how I think the doc should be" and you're free to take just the bits you consider appropriate.
Created attachment 10047 [details] patch for portage documentation
Created attachment 10048 [details] revisited portage user guide
Updated ebuild.5 ... http://cvs.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-src/portage/man/ebuild.5.diff?r1=1.41&r2=1.42
updated ebuild.1 ... i did not remove the definition of the 'unmerge' command ... it really makes no sense to do so ... i also re-worded the config step ... http://cvs.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-src/portage/man/ebuild.1.diff?r1=1.11&r2=1.12
nick: you'll have to merge the changes to the .py files (for obvious reasons) ... you'll also have to do emerge.1 and make.conf.5 because i'm not up-to-date with the current feature set of portage
Thanks for the commit. The reason for removing "unmerge" is that it's no more available (in portage 2.0.48_pre2, see lines 1401-1402), but maybe it was unintended (bug?). Bye.
Created attachment 12390 [details, diff] patch for bin/ebuild.sh This patch is just an update of the "help" section of bin/ebuild.sh
Created attachment 12391 [details, diff] patch for bin/emergehelp.py This patch contains few changes, mainly some extra lines taken from emerge man page, plus some clarifications
Created attachment 12392 [details, diff] patch for man/emerge.1 This patch is quite huge, but it's no more than a complete resync with emerge --help, plus some trivials and a correction of "use.defaults" in the FILES section.
I posted some updated patches against portage-2.0.48, for the internal documentation and for the emerge man page. This changes should also take care of bugs: bug #17977 (first part) bug #19239 bug #19371 bug #19401 bug #21316 bug #21379 bug #21510 Bye.
Created attachment 12409 [details, diff] patch for man/emerge.1 (rediffed) Small improvements, corrected error in --resume
Created attachment 12410 [details, diff] patch for bin/ebuild.sh (rediffed) corrected missing "unmerge"
after vapier's update for portage-2.0.48-r1, emerge.1 is quite good. Still remaining issues: - listing `help' among actions is misleading (`emerge help' does nothing) - --version lacks the short option (-V) - in FILES: description of /etc/make.profile/use.defaults is wrong (or at least misleading).
Just to summarize: I'll post a patch for man/emerge.1 that just modify three small thigs: trim 'help' from actions (emerge help does nothing), add short option to --verbose (-V), correct description of use.defaults. Please consider also the patches for emergehelp.py and for ebuild.sh. Thanks.
Created attachment 17630 [details, diff] patch for man/emerge.1
i added the 2nd and 3rd hunk of the emerge.1 patch ... however, the fact that `emerge help` and `emerge help clean` does not work is more of a bug ... i believe we should get rid of `emerge help` and turn it into `emerge --help` ONLY ... that means that it would work like this: `emerge --help config` and `emerge --help clean`, etc... also, if someone runs `emerge help` right now it just says this: root@rux0r 2 man # emerge help emerge: please tell me what to do.
Ok, in fact the 'emerge help' thing is bug #21379. Substituting 'help' with '--help' is what i tried to do, in emerge.1 and in the first hunk of the emergehelp.py patch. BTW, thanks for the fast commit!
I fixed the help vs. --help issue in CVS, anyone want to summarize what's left to close this bug?
The part of this bug that still makes sense is the patch for ebuild.sh. I was writing an updated patch for 2.0.50-r1, but in doing so I encountered three problems. I was making the output of "ebuild ... help" something like help : show this help screen setup : execute package specific setup actions fetch : download source archive(s) and patches digest : creates a digest and a manifest file for the package manifest : creates a manifest file for the package unpack : unpack/patch sources (auto-fetch if needed) compile : compile sources (auto-fetch/unpack if needed) preinst : execute pre-install instructions postinst : execute post-install instructions install : installs the package to the temporary install directory qmerge : merge image into live filesystem, recording files in db merge : does fetch, unpack, compile, install and qmerge prerm : execute pre-removal instructions postrm : execute post-removal instructions unmerge : remove package from live filesystem config : execute package specific configuration actions package : create tarball package of type (will be stored in /usr/portage/packages/All) rpm : builds a RedHat RPM package clean : clean up all source and temporary files problems: - the line that describes "package" prints the empty variable ${PACKAGE} after "type", what does it mean? should I reword that description? - I take the list of possible actions from portage.py, but there I see the action "depend", which always produce a traceback, and - the action "touch", which always produce an error message. Should I just ignore those two? BTW, the ebuild(1) man page could also be updated with "manifest", but apart from that is quite good. Should I provide an update for that, too?
Ok, this is another opportunity to close this bug. I guess "depend" action is used internally for creation of the cache in /var/cache/edb, so I ignored it, even if it is broken. "touch" should not exist on line 2077 or portage.py, that's a trivial issue. So the following patch for ebuild.sh should be fine.
Created attachment 29203 [details, diff] ebuild.sh.patch
I see it's applied. Closing.
