The man page of emerge lists such things as --depclean and --sync, that do not take an argument, under Actions, but lists the comparable --resume under Options. In my opinion a sensible division of actions and options is this: anything that doesn't combine with any other action is an action, anything that modifies one or more actions is an option. Then --depclean, --info, --metadata, --regen, --resume, --sync and --version are (special) actions, and --help, --search and --searchdesc too. And --clean, --inject, --prune, --unmerge, --update and --upgradeonly are normal actions: taking ebuilds and such as arguments. The rest are options. Attached patch groups all actions together. (If desired, I can make a similar patch for 'emerge --help'.) Reproducible: Always Steps to Reproduce: 1. 2. 3.
Created attachment 52776 [details, diff] groups all actions together
this kind of logic needs to be decided on by the portage team before the docs will be touched up ...
> this kind of logic needs to be decided on by the portage team > before the docs will be touched up ... Shall I post to portage-dev, or is this not a good time? Or is it already being discussed behind the scenes? (Another possibility of course is to consider only normal actions (those that can take an ebuild as argument) as actions, and all the others as options. This probably comes closer to the usual naming scheme, where --version and --help are special options that cancel the normal behaviour of a command.) (A third possibility, and my preference, is to make three categories: actions -- those that can take an ebuild argument, specials -- those that cancel the normal pacakage-installing behaviour and make emerge do something else instead, options -- those that modify most actions and some of the specials.)
+1 on this patch, we discussed this a while back when I wrote the action based emerge thats been sitting on my hard drive for quite some time. I'd prefer if it made it into trunk sometime :)
update it and it's in.
Created attachment 76518 [details, diff] groups all actions together Updated patch. (It additionally doubles four single spaces between sentences; they caught my eye.)
err... what was that split against? 2.1_pre3?
Created attachment 76537 [details, diff] groups all actions together, on the portage_2_0 trunk The previous patch was against HEAD (revision 1.74). This new patch is against the portage_2_0 branch (revision 1.70.2.16). Am I looking in the right place here?: http://www.gentoo.org/cgi-bin/viewcvs.cgi/portage/man/emerge.1?root=gentoo-src&rev=1.74&sortby=date&view=log
Created attachment 76539 [details, diff] adds --resume to the synopsis, makes the wording more uniform, and removes the mentioning of "inject" If this patch is accepted, I'll make a similar one for HEAD.
Nope, that's cvs head; pull down the portage-2.1_pre3 tarball, and work from the manpages there- I'd tell you to use anonsvn, but we're still waiting on that. Alternatively, viewcvstest.gentoo.org/portage/main/trunk/man is another route. Pardon the 101 jumps here; literally, once I've got the patch, assuming it's sane it's in. Thanks
Created attachment 76543 [details, diff] groups all actions together This one's against viewcvstest.gentoo.org/portage/main/trunk/man/emerge.1, revision 2505.
insvn rev2553 Got any more? ;)
Created attachment 76665 [details, diff] adds --resume and --config to the synopsis for greater visibility, puts --config in its alphabetical place, and makes the wording more uniform > Got any more? ;) Sure. :) Here's the first. More to come. Question: isn't --inject long dead? Any reason it is still in this man page?
Created attachment 76667 [details, diff] cleans up the description of the letters printed by --pretend
Created attachment 76676 [details, diff] regroups the actions in the emerge --help text, and adds --nocolor to it
Ping. Harring? Any chance the last three patches could go in?
Pardon the delay- been getting schmucked by work/real life time wise. patch 1 s:Make sure none of the output:Disable color output: patch 2 s:better version:newer version: Better being relative ;) Not sure on the slot wording change offhand though patch 3 Nice catch, kind of a forgotten file usually. Any thoughts/ideas on how to auto generate that? Whether generating a man page from emergehelp output, or generating emergehelp data/text from man page... Reasoning being, at least in my case, I'm an idiot and suck at remembering to update something in two different places- one spot, yeah, I can get that, but two? Taxes the brain ;) Thoughts?
> patch 1 > s:Make sure none of the output:Disable color output: Yes, better, will make that change. > patch 2 > s:better version:newer version: Not quite: a better version is not always newer: when a newer version later appears to be borked, portage will sometimes downgrade to an older and 'better' version -- "U" is then accompanied by "D". Also when manually installing an older version, "UD" will be shown -- so "U" seems to mean "different", not "newer". Adapted patch is coming. About the slot installation: there's no need to mention "new", as "S" is always accompanied by "N". > patch 3 > Any thoughts/ideas on how to auto generate that? No, but it's not needed, I think. When no one files bugs on it, it apparently doesn't get used much. :) And personally I like it that the text isn't the same as the man page: some different wording and more examples are nice to see.
Created attachment 77353 [details, diff] adapted synopsis patch
Created attachment 77354 [details, diff] adapted letters patch
Released in 2.1_pre4
