1 |
On Mon, 01 May 2017 18:02:56 +0200 |
2 |
Michał Górny <mgorny@g.o> wrote: |
3 |
|
4 |
> In other words, I don't think that: |
5 |
> |
6 |
> DIST_TEST (UNSET -> "do parallel") |
7 |
> |
8 |
> is more readable than: |
9 |
> |
10 |
> DIST_TEST (UNSET) |
11 |
> ... |
12 |
> If unset, "do parallel" is assumed. |
13 |
> |
14 |
> -- |
15 |
|
16 |
(This time on list) |
17 |
|
18 |
If I were to take a second approach, producing a map of specific values |
19 |
for a varible and their interpretations, so that the manpage emitter |
20 |
could elegantly turn them into a bullet-pointed list of some |
21 |
description, would that be a worthwhile alternative? |
22 |
|
23 |
|
24 |
DIST_TEST |
25 |
|
26 |
Values: |
27 |
- UNSET same as "do parallel" |
28 |
- "do ..." enable tests |
29 |
- "parallel ..." enable tests and parallelism |
30 |
- "network ..." don't attempt to suppress network tests |
31 |
- "verbose ..." increase test verbosity |
32 |
|
33 |
|
34 |
GENTOO_DEPEND_ON_PERL |
35 |
|
36 |
Values: |
37 |
- UNSET same as "yes" |
38 |
- "yes" depend on perl, including a slot operator for rebuild |
39 |
- "noslotop" depend on perl, but without including the slot operator |
40 |
|
41 |
The main objective here for me is to encourage a more clear convention |
42 |
for documenting the purpose of the variable that is consistent across |
43 |
eclasses, that doesn't require full reading of the DESCRIPTION to |
44 |
cherry pick understandings of various isolated parts. |
45 |
|
46 |
( Mostly, as they're typically not well structured for skim reading ) |
47 |
|
48 |
You may note the value map for DIST_TEST as stated is more-or-less |
49 |
already in place for perl-module.eclass, albeit its just a hand |
50 |
formatted table. |
51 |
|
52 |
I just figure we could do more with this tree-wide if the data was |
53 |
declared up-front, ( like line-wrapping the description side, using |
54 |
styles for the "key" parts, etc, ) |
55 |
|
56 |
But I won't waste time throwing together such an idea if its not likely |
57 |
to be deemed useful. |
58 |
|
59 |
( I don't even want to think about what the syntax would be to document |
60 |
it atm, ewww ) |