On Mon, 01 May 2017 18:02:56 +0200 Michał Górny <[email protected]> wrote:
> In other words, I don't think that:
>
> DIST_TEST (UNSET -> "do parallel")
>
> is more readable than:
>
> DIST_TEST (UNSET)
> ...
> If unset, "do parallel" is assumed.
>
> --
(This time on list)
If I were to take a second approach, producing a map of specific values
for a varible and their interpretations, so that the manpage emitter
could elegantly turn them into a bullet-pointed list of some
description, would that be a worthwhile alternative?
DIST_TEST
Values:
- UNSET same as "do parallel"
- "do ..." enable tests
- "parallel ..." enable tests and parallelism
- "network ..." don't attempt to suppress network tests
- "verbose ..." increase test verbosity
GENTOO_DEPEND_ON_PERL
Values:
- UNSET same as "yes"
- "yes" depend on perl, including a slot operator for rebuild
- "noslotop" depend on perl, but without including the slot operator
The main objective here for me is to encourage a more clear convention
for documenting the purpose of the variable that is consistent across
eclasses, that doesn't require full reading of the DESCRIPTION to
cherry pick understandings of various isolated parts.
( Mostly, as they're typically not well structured for skim reading )
You may note the value map for DIST_TEST as stated is more-or-less
already in place for perl-module.eclass, albeit its just a hand
formatted table.
I just figure we could do more with this tree-wide if the data was
declared up-front, ( like line-wrapping the description side, using
styles for the "key" parts, etc, )
But I won't waste time throwing together such an idea if its not likely
to be deemed useful.
( I don't even want to think about what the syntax would be to document
it atm, ewww )
pgpH9c7i2il0u.pgp
Description: OpenPGP digital signature
