| Summary: | some tweaks with portage docs | ||
|---|---|---|---|
| Product: | Portage Development | Reporter: | Gregorio Guidi (RETIRED) <greg_g> |
| Component: | Unclassified | Assignee: | Portage team <dev-portage> |
| Status: | RESOLVED FIXED | ||
| Severity: | enhancement | Keywords: | InVCS |
| Priority: | High | ||
| Version: | unspecified | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | |||
| Package list: | Runtime testing required: | --- | |
| Attachments: |
the diff
the diff the last diff patch for portage documentation revisited portage user guide patch for bin/ebuild.sh patch for bin/emergehelp.py patch for man/emerge.1 patch for man/emerge.1 (rediffed) patch for bin/ebuild.sh (rediffed) patch for man/emerge.1 ebuild.sh.patch |
||
|
Description
Gregorio Guidi (RETIRED)
2003-03-26 16:39:25 UTC
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. |