On Mon, 01 May 2017 18:02:56 +0200
Michał Górny <mgorny@gentoo.org> 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 )