Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @DEFAULT-ASSUMED

["Michał Górny" <mgorny@gentoo.org>]

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

On pon, 2017-05-01 at 09:38 +1200, kentnl@gentoo.org wrote:
> From: Kent Fredric <kentnl@gentoo.org>
> 
> @DEFAULT-ASSUMED allows eclasses to document any implied value
> that internal code will assume when the ENV var is undefined.
> 
> @DEFAULT-ASSUMED should typically be used in conjunction with
> @DEFAULT-UNSET, but it can be used in conjunction with either
> @DEFAULT-VALUE or normal value extraction.
> 
> For instance:
> 
>   @VARIABLE: DIST_TEST
>   @DEFAULT-ASSUMED: "do parallel"
> 
> This inserts an additional suffix to the generated man page heading
> line so it renders as follows:
> 
>   DIST_TEST     (UNSET -> "do parallel")
> 
> But indicates that the value itself is not explicitly set by the eclass
> and ebuilds should not assume it to have a value.
> 
> For instance, upon seeing such an indication, ebuild authors should
> be able to tell that doing
> 
>   DIST_TEST+=" network"
> 
> Would end up producing
> 
>   DIST_TEST=" network"
> 
> Not
> 
>   DIST_TEST="do parallel network"
> 
> This is primarily for usecases where the variable is not assigned
> anywhere in the top level file, but consuming functions imply a value:
> 
>   has "parallel" ${DIST_TEST:-do parallel}

Well, I don't think there's really a good reason to expose this
in an explicit tag. It's going to be a little bit confusing at least
(your rendering isn't immediately obvious for users), and I don't really
see the problem being solved here.

As far as I can see, it applies to quite a specific corner case, when:

a. you want to assume a default value for the variable,

b. the assumed default is simple enough to be expressed directly, i.e.
unconditional,

c. but at the same time you stil want to keep it unset in global scope
for some reason.

Even if you have a very good reason for all the three conditions to be
met, I think that in the majority of cases you will need to explain what
particular values mean.

That being the case, I don't really see an advantage of explicitly
listing default value with potentially confusing syntax when the same
problem was already solved in a readable and non-confusing way by
explaining it in the body.

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.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 963 bytes --]