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

[kentnl@gentoo.org]

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}
---
 app-portage/eclass-manpages/files/eclass-to-manpage.awk | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
index d6ed59efd9..772ee867d8 100644
--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
@@ -40,6 +40,7 @@
 # [@DEFAULT_UNSET]
 # [@INTERNAL]
 # [@REQUIRED]
+# @DEFAULT-ASSUMED: <interpreted value when not set>
 # @DEFAULT-VALUE: <initial value>
 # @DESCRIPTION:
 # <required; blurb about this variable>
@@ -50,6 +51,7 @@
 # [@DEFAULT_UNSET]
 # [@INTERNAL]
 # [@REQUIRED]
+# @DEFAULT-ASSUMED: <interpreted value when not set>
 # @DEFAULT-VALUE: <initial value>
 # @DESCRIPTION:
 # <required; blurb about this variable>
@@ -285,6 +287,7 @@ function _handle_variable() {
 	default_unset = 0
 	internal = 0
 	required = 0
+	default_assumed = ""
 	default_value = ""
 
 	# make sure people haven't specified this before (copy & paste error)
@@ -302,8 +305,12 @@ function _handle_variable() {
 			internal = 1
 		else if ($2 == "@REQUIRED")
 			required = 1
+		else if ($2 == "@DEFAULT-ASSUMED:") {
+			sub(/^# @[A-Z-]*:[[:space:]]*/,"")
+			default_assumed = $0
+		}
 		else if ($2 == "@DEFAULT-VALUE:") {
-			sub(/^# @[A-Z_]*:[[:space:]]*/,"")
+			sub(/^# @[A-Z-]*:[[:space:]]*/,"")
 			default_value = $0
 		}
 		else
@@ -343,6 +350,10 @@ function _handle_variable() {
 	if (required == 1)
 		val = val " (REQUIRED)"
 
+	if ( default_assumed != "" ) {
+		val = val " (UNSET -> \\fI" default_assumed "\\fR)"
+	}
+
 	if (internal == 1)
 		return ""
 
-- 
2.12.2