1 |
From: Kent Fredric <kentnl@g.o> |
2 |
|
3 |
@DEFAULT-VALUE allows eclasses to document the default values they |
4 |
will inject when eclass-to-manpage can't extract it. |
5 |
|
6 |
When eclass-to-manpage *can* extract it, it adds a warning when |
7 |
the extracted value is different from that declared, (but the |
8 |
declared value still takes precedence) |
9 |
|
10 |
Note: there is a pre-exisitng poorly documented hack where |
11 |
|
12 |
# FOO=VALUE |
13 |
|
14 |
In a comment serves as a fallback for literal value parsing, which |
15 |
can supplement DEFAULT-VALUE in a less clear way. |
16 |
|
17 |
But due to the nature of this syntax, its not trivial to identify |
18 |
which eclasses are, and aren't using it as variables are routinely |
19 |
commented without intending them to be used as documentation. |
20 |
|
21 |
Some such commented assignments lurk in @CODE examples, which are |
22 |
surely not intended to be extracted as their values |
23 |
|
24 |
Subsequently, if present, @DEFAULT-VALUE will also trump any such |
25 |
commented assignments |
26 |
--- |
27 |
.../eclass-manpages/files/eclass-to-manpage.awk | 21 +++++++++++++++++---- |
28 |
1 file changed, 17 insertions(+), 4 deletions(-) |
29 |
|
30 |
diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk |
31 |
index 0d41f96327..d6ed59efd9 100644 |
32 |
--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk |
33 |
+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk |
34 |
@@ -40,6 +40,7 @@ |
35 |
# [@DEFAULT_UNSET] |
36 |
# [@INTERNAL] |
37 |
# [@REQUIRED] |
38 |
+# @DEFAULT-VALUE: <initial value> |
39 |
# @DESCRIPTION: |
40 |
# <required; blurb about this variable> |
41 |
# foo="<default value>" |
42 |
@@ -49,6 +50,7 @@ |
43 |
# [@DEFAULT_UNSET] |
44 |
# [@INTERNAL] |
45 |
# [@REQUIRED] |
46 |
+# @DEFAULT-VALUE: <initial value> |
47 |
# @DESCRIPTION: |
48 |
# <required; blurb about this variable> |
49 |
# foo="<default value>" |
50 |
@@ -283,6 +285,7 @@ function _handle_variable() { |
51 |
default_unset = 0 |
52 |
internal = 0 |
53 |
required = 0 |
54 |
+ default_value = "" |
55 |
|
56 |
# make sure people haven't specified this before (copy & paste error) |
57 |
if (all_vars[var_name]) |
58 |
@@ -299,6 +302,10 @@ function _handle_variable() { |
59 |
internal = 1 |
60 |
else if ($2 == "@REQUIRED") |
61 |
required = 1 |
62 |
+ else if ($2 == "@DEFAULT-VALUE:") { |
63 |
+ sub(/^# @[A-Z_]*:[[:space:]]*/,"") |
64 |
+ default_value = $0 |
65 |
+ } |
66 |
else |
67 |
opts = 0 |
68 |
} |
69 |
@@ -315,15 +322,21 @@ function _handle_variable() { |
70 |
op = "?=" |
71 |
regex = "^[[:space:]]*:[[:space:]]*[$]{" var_name ":?=(.*)}" |
72 |
val = gensub(regex, "\\1", 1, $0) |
73 |
- if (val == $0) { |
74 |
- if (default_unset + required + internal == 0) |
75 |
+ } |
76 |
+ if (default_value != "") { |
77 |
+ if ( val != $0 && default_value != val ) |
78 |
+ warn( var_name ": extracted different from DEFAULT-VALUE: " default_value " <=> " val ) |
79 |
+ op = "=" |
80 |
+ val = default_value |
81 |
+ } |
82 |
+ if ( val == $0 ) { |
83 |
+ if (default_unset + required + internal == 0) |
84 |
warn(var_name ": unable to extract default variable content: " $0) |
85 |
val = "" |
86 |
- } else if (val !~ /^["']/ && val ~ / /) { |
87 |
+ } else if (val !~ /^["']/ && val ~ / /) { |
88 |
if (default_unset == 1) |
89 |
warn(var_name ": marked as unset, but has value: " val) |
90 |
val = "\"" val "\"" |
91 |
- } |
92 |
} |
93 |
if (length(val)) |
94 |
val = " " op " \\fI" val "\\fR" |
95 |
-- |
96 |
2.12.2 |