[gentoo-portage-dev] RFC: emerge manpage options categorization

[Duncan]

While looking up something in the emerge (1) manpage, I noticed again its 
proliferation of options, many of which are for esoteric cases that 
normal users don't need to worry about for normal usage and some of which 
(like --rage-clean) are ANTI-recommended, with many others which are 
arguably best set once in EMERGE_DEFAULT_OPTS and forgotten about.

Perhaps it's time to consider further option categorization.  Suggested 
categories:

Common Runtime Options
Common EMERGE_DEFAULT_OPTS Candidate Options
Other Useful Options (optional)
All Options

The All Options category would be what's currently under Options, 
basically everything (including the common options) in alphabetical 
order, intended as an exhaustive options reference.  Arguably, this could 
be split off into its own manpage, emerge-reference or emerge-advanced or 
some such, with a reference to it in the main manpage.

The two common options categories would contain recommended or otherwise 
known to be commonly used options, that users really should know about, 
but NOT the more esoteric stuff with sane defaults like
--backtrack=<count>, --misspell-suggestions, etc.  Splitting these into 
common default-options and common runtime would let users find what 
they're looking for based on task (occasional default-option optimization 
or this-run tweaking) they're working on.  Obviously, some options might 
end up in both.

The other useful options category, if created, would be for less common 
options that can still be useful from time to time.  Arguably, options 
such as --only-deps, --color and possibly --tree could go here.  As such, 
it'd be a middle-ground between common options and the obscurity of those 
listed only in all options.  I think breaking it down into runtime and 
default options would be a bit much, but of course "(runtime)" and 
"(default-opts)" notes could be added where appropriate, if considered 
useful.

Arguably, this would let portage devs put portage-dev recommended but 
politically sensitive options such as --dynamic-deps=n and --changed-
deps=y in the common defaults section, while effectively making corner-
case and NOT recommended options like --rage-clean a bit harder to find 
for the "ordinary user" (particularly if the all-options reference is 
moved to its own manpage), while still keeping them documented for users 
that want to explore the portage flexibility they expose.

In theory, the actions category could be split up as well, perhaps simply 
into common and other, but I'm less sure about this idea and consider it 
less urgent in any case.

Comments?

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman