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

[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

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

[Kent Fredric]

[-- Attachment #1: Type: text/plain, Size: 553 bytes --]

On 12 March 2015 at 15:19, Duncan <1i5t5.duncan@cox.net> wrote:

> Comments?


A less radical change would be some sort of tagging notation on each
feature to indicate their usage.

That way, it doesn't impede the current audience who expects to be able to
browse the list alphabetically.

( I suggest this, because restructuring it radically will have potential
bikeshed drama of people not liking the new layout, so tag-style metadata
makes the levels visible without requiring a restructure )

-- 
Kent

*KENTNL* - https://metacpan.org/author/KENTNL

[-- Attachment #2: Type: text/html, Size: 1307 bytes --]

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

[Duncan]

Kent Fredric posted on Thu, 12 Mar 2015 15:23:59 +1300 as excerpted:

> On 12 March 2015 at 15:19, Duncan <1i5t5.duncan@cox.net> wrote:
> 
>> Comments?
> 
> 
> A less radical change would be some sort of tagging notation on each
> feature to indicate their usage.
> 
> That way, it doesn't impede the current audience who expects to be able
> to browse the list alphabetically.
> 
> ( I suggest this, because restructuring it radically will have potential
> bikeshed drama of people not liking the new layout, so tag-style
> metadata makes the levels visible without requiring a restructure )

Tags would be less radical, indeed, and an improvement from current, 
agreed.

But as envisioned, the alphabetic order of all options (including those 
listed in the other sections, as I mentioned in the original proposal) 
would be maintained in the all options section, precisely because it 
remains useful to have an alphabetically ordered full-reference section.

Tho as proposed, that all-options section may /optionally/ be moved into 
its own manpage, with an explicit note to that effect in the main 
manpage.  Among other things that would avoid an already long manpage 
made longer by repeated option descriptions.  But I don't feel strongly 
enough about such a split to make it a big deal if others don't like the 
idea, the the "optional" qualifier.

IOW, people that didn't like the new layout could simply refer to the all-
options section or separate manpage for the old alphabetically-ordered 
full reference layout, which should hopefully reduce resistance 
dramatically. =:^)

-- 
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

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 407 bytes --]

On 12 Mar 2015 13:52, Duncan wrote:
> Tho as proposed, that all-options section may /optionally/ be moved into 
> its own manpage, with an explicit note to that effect in the main 
> manpage.

i think splitting the content between two man pages is a pretty bad idea.
would be kind of easy to get duplicate content, and even if there was a
one line note at like the top, people would miss it.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Duncan]

Mike Frysinger posted on Tue, 02 Jun 2015 10:47:59 -0400 as excerpted:

> On 12 Mar 2015 13:52, Duncan wrote:
>> Tho as proposed, that all-options section may /optionally/ be moved
>> into its own manpage, with an explicit note to that effect in the main
>> manpage.
> 
> i think splitting the content between two man pages is a pretty bad
> idea.
> would be kind of easy to get duplicate content, and even if there was a
> one line note at like the top, people would miss it.

Thanks.  FWIW I have parts of this thread marked to followup later, so 
comments can still be useful if I actually do so (no promises).

-- 
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

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

[Alexander Berntsen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 12/03/15 03:19, Duncan wrote:
> Comments?
Sure. Patches welcome.

- -- 
Alexander
bernalex@gentoo.org
https://secure.plaimi.net/~alexander
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iF4EAREIAAYFAlUBd6kACgkQRtClrXBQc7WWiQD9H2aUo2mkl1e8NxZ5LFM4xPXq
AyfDA3D1MpevRTXGQ7EA/RRSfUQXncb+vQAYYtEBFAEOhYFapj4PHJSt9bFZsgE+
=MONi
-----END PGP SIGNATURE-----

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

[Duncan]

Alexander Berntsen posted on Thu, 12 Mar 2015 12:25:31 +0100 as excerpted:

> On 12/03/15 03:19, Duncan wrote:
>> Comments?
> Sure. Patches welcome.

LOL.  I was expecting that[1]. =:^)

While I don't know the (presumably) roff markup I've seen in the manpage 
patches, it'd definitely be useful to learn (and it seems a more 
realistic goal than say learning C), and I'm not opposed to doing so and 
then doing the work myself.

However, particularly since I /would/ have to learn the markup before 
actually coming up with the patches, it's still worth an RFC before-hand, 
to see if it's worth the trouble.  If people are wedded to the current 
layout...

Presumably if it is judged to be worth pursuing, the debate on what 
precise sections to use, and whether the all-options section should be 
split to its own manpage, can continue while I work on learning the 
markup.

---
[1] ... and privately speculating on how long it'd take to get that 
response.

-- 
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