From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id DDF9E138CBD for ; Thu, 12 Mar 2015 02:19:21 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id D3C24E087A; Thu, 12 Mar 2015 02:19:20 +0000 (UTC) Received: from plane.gmane.org (plane.gmane.org [80.91.229.3]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 2F558E0877 for ; Thu, 12 Mar 2015 02:19:20 +0000 (UTC) Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1YVsiT-0004Ee-Ve for gentoo-portage-dev@lists.gentoo.org; Thu, 12 Mar 2015 03:19:18 +0100 Received: from ip68-231-22-224.ph.ph.cox.net ([68.231.22.224]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 12 Mar 2015 03:19:17 +0100 Received: from 1i5t5.duncan by ip68-231-22-224.ph.ph.cox.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 12 Mar 2015 03:19:17 +0100 X-Injected-Via-Gmane: http://gmane.org/ To: gentoo-portage-dev@lists.gentoo.org From: Duncan <1i5t5.duncan@cox.net> Subject: [gentoo-portage-dev] RFC: emerge manpage options categorization Date: Thu, 12 Mar 2015 02:19:12 +0000 (UTC) Message-ID: Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-portage-dev@lists.gentoo.org Reply-to: gentoo-portage-dev@lists.gentoo.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: ip68-231-22-224.ph.ph.cox.net User-Agent: Pan/0.140 (Chocolate Salty Balls; GIT 10ca3f5) X-Archives-Salt: 055905b5-9865-4037-9f9e-fde5abbb863e X-Archives-Hash: a270a7daa636875a3d30bf59a8d1baeb 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=, --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