From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id AEC8C139694 for ; Mon, 1 May 2017 16:03:19 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 5EF4E21C080; Mon, 1 May 2017 16:03:10 +0000 (UTC) Received: from smtp.gentoo.org (mail.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 05EEEE0D6C for ; Mon, 1 May 2017 16:03:09 +0000 (UTC) Received: from pomiot (d202-252.icpnet.pl [109.173.202.252]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: mgorny) by smtp.gentoo.org (Postfix) with ESMTPSA id A982233E4AD; Mon, 1 May 2017 16:03:06 +0000 (UTC) Message-ID: <1493654576.29015.1.camel@gentoo.org> Subject: Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @DEFAULT-ASSUMED From: =?UTF-8?Q?Micha=C5=82_G=C3=B3rny?= To: gentoo-dev@lists.gentoo.org Cc: vapier@gentoo.org, tools-portage@gentoo.org, Kent Fredric Date: Mon, 01 May 2017 18:02:56 +0200 In-Reply-To: <20170430213801.21789-1-kentnl@gentoo.org> References: <20170430213801.21789-1-kentnl@gentoo.org> Organization: Gentoo Content-Type: multipart/signed; micalg="pgp-sha512"; protocol="application/pgp-signature"; boundary="=-e3IFhU/NWT+lk8eclKDg" X-Mailer: Evolution 3.22.6 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 X-Archives-Salt: 3ea3ae10-6c53-4b81-85b1-1c57a0ffe596 X-Archives-Hash: ba4720333dcf06e530f10ce278f99ca5 --=-e3IFhU/NWT+lk8eclKDg Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On pon, 2017-05-01 at 09:38 +1200, kentnl@gentoo.org wrote: > From: Kent Fredric >=20 > @DEFAULT-ASSUMED allows eclasses to document any implied value > that internal code will assume when the ENV var is undefined. >=20 > @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. >=20 > For instance: >=20 > @VARIABLE: DIST_TEST > @DEFAULT-ASSUMED: "do parallel" >=20 > This inserts an additional suffix to the generated man page heading > line so it renders as follows: >=20 > DIST_TEST (UNSET -> "do parallel") >=20 > But indicates that the value itself is not explicitly set by the eclass > and ebuilds should not assume it to have a value. >=20 > For instance, upon seeing such an indication, ebuild authors should > be able to tell that doing >=20 > DIST_TEST+=3D" network" >=20 > Would end up producing >=20 > DIST_TEST=3D" network" >=20 > Not >=20 > DIST_TEST=3D"do parallel network" >=20 > This is primarily for usecases where the variable is not assigned > anywhere in the top level file, but consuming functions imply a value: >=20 > 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. --=20 Best regards, Micha=C5=82 G=C3=B3rny --=-e3IFhU/NWT+lk8eclKDg Content-Type: application/pgp-signature; name="signature.asc" Content-Description: This is a digitally signed message part Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- iQKTBAABCgB9FiEEXr8g+Zb7PCLMb8pAur8dX/jIEQoFAlkHXDBfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDVF QkYyMEY5OTZGQjNDMjJDQzZGQ0E0MEJBQkYxRDVGRjhDODExMEEACgkQur8dX/jI EQqaahAAx2nSN1+0HJIBV8dsicQ6UglTf6wuldnmAjWeIphwZEfYpcbJcn8mbgzC sV6cxoNyGvH7MHFp9L+XUZPnQCoChkm2TOmKI/LEYzltrXne1Ra7iBllEk3kmcn8 cnJQgN3RPWdG5loTnghIoNRW8IFWzic5ahanH6golk1vye3ntOiEz+rEUt6lgecx ESbQD6zyJZs2JNvnILtaKYw+WP43LBaa4ZUrNmG8BmNkd9DD3cEVuQu0JwhYaR6X EDlEmiGeY6RsOsrBEaJF1weybBMExUxJIfd8/pSAkwdBmqZ2j627iEzGBgpFEQ+j WAzl/og/07I39Hrm0JcAA+OCJb891FwLhcSpG3oJJWTZYKSISBbeA/lcI/1IiPwv H57Afr4hOy6XS/vc4iCyqpqoz/vGBIeXQL8TEfX4rflBE7CM4kkL9VZPa2TZ8MTf 0Jrb9Y/yq0SdiF82GaQVeBovzU4OIZ2D8zqsygULAjSv4aYx/fKsX+dZN0P4P1xG PbtdhF+Zp7CeF77ZiR2Y6X6zSn1dAOiteIdqJrpLb/1ERz9uMZrfnMVHVaYFECP4 WBx0+ZS+M890NbiPlH4mbqAUtxf2hxWL/4L/zRthKkkg5TDbEWfRpkoyPfOLYvfG B972E9L8IpTYewdn8M1jnQ6NNm7cBiyxaLbmy6uEi1rX37t+12M= =pl+0 -----END PGP SIGNATURE----- --=-e3IFhU/NWT+lk8eclKDg--