Gentoo Archives: gentoo-portage-dev

From: Duncan <1i5t5.duncan@×××.net>
To: gentoo-portage-dev@l.g.o
Subject: [gentoo-portage-dev] RFC: emerge manpage options categorization
Date: Thu, 12 Mar 2015 02:19:21
Message-Id: pan$99f15$94415e87$8ccc4edc$
1 While looking up something in the emerge (1) manpage, I noticed again its
2 proliferation of options, many of which are for esoteric cases that
3 normal users don't need to worry about for normal usage and some of which
4 (like --rage-clean) are ANTI-recommended, with many others which are
5 arguably best set once in EMERGE_DEFAULT_OPTS and forgotten about.
7 Perhaps it's time to consider further option categorization. Suggested
8 categories:
10 Common Runtime Options
11 Common EMERGE_DEFAULT_OPTS Candidate Options
12 Other Useful Options (optional)
13 All Options
15 The All Options category would be what's currently under Options,
16 basically everything (including the common options) in alphabetical
17 order, intended as an exhaustive options reference. Arguably, this could
18 be split off into its own manpage, emerge-reference or emerge-advanced or
19 some such, with a reference to it in the main manpage.
21 The two common options categories would contain recommended or otherwise
22 known to be commonly used options, that users really should know about,
23 but NOT the more esoteric stuff with sane defaults like
24 --backtrack=<count>, --misspell-suggestions, etc. Splitting these into
25 common default-options and common runtime would let users find what
26 they're looking for based on task (occasional default-option optimization
27 or this-run tweaking) they're working on. Obviously, some options might
28 end up in both.
30 The other useful options category, if created, would be for less common
31 options that can still be useful from time to time. Arguably, options
32 such as --only-deps, --color and possibly --tree could go here. As such,
33 it'd be a middle-ground between common options and the obscurity of those
34 listed only in all options. I think breaking it down into runtime and
35 default options would be a bit much, but of course "(runtime)" and
36 "(default-opts)" notes could be added where appropriate, if considered
37 useful.
39 Arguably, this would let portage devs put portage-dev recommended but
40 politically sensitive options such as --dynamic-deps=n and --changed-
41 deps=y in the common defaults section, while effectively making corner-
42 case and NOT recommended options like --rage-clean a bit harder to find
43 for the "ordinary user" (particularly if the all-options reference is
44 moved to its own manpage), while still keeping them documented for users
45 that want to explore the portage flexibility they expose.
47 In theory, the actions category could be split up as well, perhaps simply
48 into common and other, but I'm less sure about this idea and consider it
49 less urgent in any case.
53 --
54 Duncan - List replies preferred. No HTML msgs.
55 "Every nonfree program has a lord, a master --
56 and if you use the program, he is your master." Richard Stallman


Subject Author
Re: [gentoo-portage-dev] RFC: emerge manpage options categorization Kent Fredric <kentfredric@×××××.com>
Re: [gentoo-portage-dev] RFC: emerge manpage options categorization Alexander Berntsen <bernalex@g.o>