* [gentoo-commits] repo/gentoo:master commit in: app-doc/eclass-manpages/files/
@ 2019-03-26 19:33 Aaron Bauman
0 siblings, 0 replies; 3+ messages in thread
From: Aaron Bauman @ 2019-03-26 19:33 UTC (permalink / raw
To: gentoo-commits
commit: 2e32186bbee30a4a2e1c4f37c79c61897e53d8df
Author: Michael Mair-Keimberger <m.mairkeimberger <AT> gmail <DOT> com>
AuthorDate: Tue Mar 26 19:28:48 2019 +0000
Commit: Aaron Bauman <bman <AT> gentoo <DOT> org>
CommitDate: Tue Mar 26 19:32:52 2019 +0000
URL: https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=2e32186b
app-doc/eclass-manpages: remove unused file
Signed-off-by: Michael Mair-Keimberger <m.mairkeimberger <AT> gmail.com>
Closes: https://github.com/gentoo/gentoo/pull/11512
Signed-off-by: Aaron Bauman <bman <AT> gentoo.org>
.../eclass-manpages/files/eclass-to-manpage.awk | 457 ---------------------
1 file changed, 457 deletions(-)
diff --git a/app-doc/eclass-manpages/files/eclass-to-manpage.awk b/app-doc/eclass-manpages/files/eclass-to-manpage.awk
deleted file mode 100644
index b40eaf11209..00000000000
--- a/app-doc/eclass-manpages/files/eclass-to-manpage.awk
+++ /dev/null
@@ -1,457 +0,0 @@
-# Copyright 1999-2017 Gentoo Foundation
-# Distributed under the terms of the GNU General Public License v2
-
-# This awk converts the comment documentation found in eclasses
-# into man pages for easier/nicer reading.
-#
-# If you wish to have multiple paragraphs in a description, then
-# create empty comment lines. Paragraph parsing ends when the comment
-# block does.
-
-# The format of the eclass description:
-# @ECLASS: foo.eclass
-# @MAINTAINER:
-# <required; list of contacts, one per line>
-# @AUTHOR:
-# <optional; list of authors, one per line>
-# @BUGREPORTS:
-# <optional; description of how to report bugs;
-# default: tell people to use bugs.gentoo.org>
-# @VCSURL: <optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@>
-# @SUPPORTED_EAPIS: <optional; space-separated list of EAPIs>
-# @BLURB: <required; short description>
-# @DESCRIPTION:
-# <optional; long description>
-# @EXAMPLE:
-# <optional; example usage>
-
-# The format of functions:
-# @FUNCTION: foo
-# @USAGE: <required arguments to foo> [optional arguments to foo]
-# @RETURN: <whatever foo returns>
-# @MAINTAINER:
-# <optional; list of contacts, one per line>
-# [@INTERNAL]
-# @DESCRIPTION:
-# <required if no @RETURN; blurb about this function>
-
-# The format of function-specific variables:
-# @VARIABLE: foo
-# [@USER_VARIABLE] (set in make.conf, not ebuilds)
-# [@INTERNAL] (internal eclass use variable)
-# [@DEFAULT_UNSET]
-# [@REQUIRED]
-# @DESCRIPTION:
-# <required; blurb about this variable>
-# foo="<default value>"
-
-# The format of eclass variables:
-# @ECLASS-VARIABLE: foo
-# [@PRE_INHERIT] (the variable must be set before inheriting the eclass)
-# [@USER_VARIABLE] (set in make.conf, not ebuilds)
-# [@OUTPUT_VARIABLE] (set by eclass, to be read in ebuilds)
-# [@INTERNAL] (internal eclass use variable)
-# [@DEFAULT_UNSET]
-# [@REQUIRED]
-# @DESCRIPTION:
-# <required; blurb about this variable>
-# foo="<default value>"
-
-# Disable manpage generation:
-# @DEAD
-
-# Common features:
-# @CODE
-# In multiline paragraphs, you can create chunks of unformatted
-# code by using this marker at the start and end.
-# @CODE
-#
-# @ROFF <some roff macros>
-# If you want a little more manual control over the formatting, you can
-# insert roff macros directly into the output by using the @ROFF escape.
-
-function _stderr_msg(text, type, file, cnt) {
- if (_stderr_header_done != 1) {
- cnt = split(FILENAME, file, /\//)
- print "\n" file[cnt] ":" > "/dev/stderr"
- _stderr_header_done = 1
- }
-
- print " " type ":" NR ": " text > "/dev/stderr"
-}
-function warn(text) {
- _stderr_msg(text, "warning")
-}
-function fail(text) {
- _stderr_msg(text, "error")
- exit(1)
-}
-function xfail(text) {
- _stderr_msg(text, "error (ignoring)")
- exit(77)
-}
-
-function eat_line() {
- ret = $0
- sub(/^# @[A-Z]*:[[:space:]]*/,"",ret)
- getline
- return ret
-}
-function eat_paragraph() {
- code = 0
- ret = ""
- getline
- while ($0 ~ /^#/) {
- # Only allow certain tokens in the middle of paragraphs
- if ($2 ~ /^@/ && $2 !~ /^@(CODE|ROFF)$/)
- break
-
- sub(/^#[[:space:]]?/, "", $0)
-
- # Escape . at start of line #420153
- if ($0 ~ /^[.]/)
- $0 = "\\&" $0
-
- # Translate @CODE into @ROFF
- if ($1 == "@CODE" && NF == 1) {
- if (code)
- $0 = "@ROFF .fi"
- else
- $0 = "@ROFF .nf"
- code = !code
- }
-
- # Allow people to specify *roff commands directly
- if ($1 == "@ROFF")
- sub(/^@ROFF[[:space:]]*/, "", $0)
-
- ret = ret "\n" $0
-
- # Handle the common case of trailing backslashes in
- # code blocks to cross multiple lines #335702
- if (code && $NF == "\\")
- ret = ret "\\"
- getline
- }
- sub(/^\n/,"",ret)
- return ret
-}
-
-function pre_text(p) {
- return ".nf\n" p "\n.fi"
-}
-
-function man_text(p) {
- return gensub(/-/, "\\-", "g", p)
-}
-
-#
-# Handle an @ECLASS block
-#
-function handle_eclass() {
- eclass = $3
- eclass_maintainer = ""
- eclass_author = ""
- supported_eapis = ""
- blurb = ""
- desc = ""
- example = ""
-
- # Sanity check the eclass name. #537392
- if (eclass !~ /[.]eclass$/)
- fail(eclass ": @ECLASS name is missing a '.eclass' suffix")
-
- # first the man page header
- print ".\\\" -*- coding: utf-8 -*-"
- print ".\\\" ### DO NOT EDIT THIS FILE"
- print ".\\\" ### This man page is autogenerated by eclass-to-manpage.awk"
- print ".\\\" ### based on comments found in " eclass
- print ".\\\""
- print ".\\\" See eclass-to-manpage.awk for documentation on how to get"
- print ".\\\" your eclass nicely documented as well."
- print ".\\\""
- print ".TH \"" toupper(eclass) "\" 5 \"" strftime("%b %Y") "\" \"Portage\" \"portage\""
-
- # now eat the global data
- getline
- if ($2 == "@MAINTAINER:")
- eclass_maintainer = eat_paragraph()
- if ($2 == "@AUTHOR:")
- eclass_author = eat_paragraph()
- if ($2 == "@BUGREPORTS:")
- reporting_bugs = eat_paragraph()
- if ($2 == "@VCSURL:")
- vcs_url = eat_line()
- if ($2 == "@SUPPORTED_EAPIS:")
- supported_eapis = eat_line()
- if ($2 == "@BLURB:")
- blurb = eat_line()
- if ($2 == "@DESCRIPTION:")
- desc = eat_paragraph()
- if ($2 == "@EXAMPLE:")
- example = eat_paragraph()
- # in case they typo-ed the keyword, bail now
- if ($2 ~ /^@/)
- fail(eclass ": unknown keyword " $2)
-
- # finally display it
- print ".SH \"NAME\""
- print eclass " \\- " man_text(blurb)
- if (desc != "") {
- print ".SH \"DESCRIPTION\""
- print man_text(desc)
- }
- if (example != "") {
- print ".SH \"EXAMPLE\""
- print man_text(example)
- }
-
- # sanity checks
- if (blurb == "")
- fail(eclass ": no @BLURB found")
- if (eclass_maintainer == "")
- warn(eclass ": no @MAINTAINER found")
-}
-
-#
-# Handle a @FUNCTION block
-#
-function show_function_header() {
- if (_function_header_done != 1) {
- print ".SH \"FUNCTIONS\""
- _function_header_done = 1
- }
-}
-function handle_function() {
- func_name = $3
- usage = ""
- funcret = ""
- maintainer = ""
- internal = 0
- desc = ""
-
- # make sure people haven't specified this before (copy & paste error)
- if (all_funcs[func_name])
- fail(eclass ": duplicate definition found for function: " func_name)
- all_funcs[func_name] = func_name
-
- # grab the docs
- getline
- if ($2 == "@USAGE:")
- usage = eat_line()
- if ($2 == "@RETURN:")
- funcret = eat_line()
- if ($2 == "@MAINTAINER:")
- maintainer = eat_paragraph()
- if ($2 == "@INTERNAL") {
- internal = 1
- getline
- }
- if ($2 == "@DESCRIPTION:")
- desc = eat_paragraph()
-
- if (internal == 1)
- return
-
- show_function_header()
-
- # now print out the stuff
- print ".TP"
- print "\\fB" func_name "\\fR " man_text(usage)
- if (desc != "")
- print man_text(desc)
- if (funcret != "") {
- if (desc != "")
- print ""
- print "Return value: " funcret
- }
-
- if (blurb == "")
- fail(func_name ": no @BLURB found")
- if (desc == "" && funcret == "")
- fail(func_name ": no @DESCRIPTION found")
-}
-
-#
-# Handle @VARIABLE and @ECLASS-VARIABLE blocks
-#
-function _handle_variable() {
- var_name = $3
- desc = ""
- val = ""
- default_unset = 0
- internal = 0
- required = 0
-
- # additional variable classes
- pre_inherit = 0
- user_variable = 0
- output_variable = 0
-
- # make sure people haven't specified this before (copy & paste error)
- if (all_vars[var_name])
- fail(eclass ": duplicate definition found for variable: " var_name)
- all_vars[var_name] = var_name
-
- # grab the optional attributes
- opts = 1
- while (opts) {
- getline
- if ($2 == "@DEFAULT_UNSET")
- default_unset = 1
- else if ($2 == "@INTERNAL")
- internal = 1
- else if ($2 == "@REQUIRED")
- required = 1
- else if ($2 == "@PRE_INHERIT")
- pre_inherit = 1
- else if ($2 == "@USER_VARIABLE")
- user_variable = 1
- else if ($2 == "@OUTPUT_VARIABLE")
- output_variable = 1
- else
- opts = 0
- }
- if ($2 == "@DESCRIPTION:")
- desc = eat_paragraph()
-
- # extract the default variable value
- # first try var="val"
- op = "="
- regex = "^.*" var_name "=(.*)$"
- val = gensub(regex, "\\1", 1, $0)
- if (val == $0) {
- # next try : ${var:=val}
- op = "?="
- regex = "^[[:space:]]*:[[:space:]]*[$]{" var_name ":?=(.*)}"
- val = gensub(regex, "\\1", 1, $0)
- if (val == $0) {
- if (default_unset + required + internal + output_variable == 0)
- warn(var_name ": unable to extract default variable content: " $0)
- val = ""
- } else if (val !~ /^["']/ && val ~ / /) {
- if (default_unset == 1)
- warn(var_name ": marked as unset, but has value: " val)
- val = "\"" val "\""
- }
- }
- if (length(val))
- val = " " op " \\fI" val "\\fR"
- if (required == 1)
- val = val " (REQUIRED)"
- # TODO: group variables using those classes
- if (pre_inherit == 1)
- val = val " (SET BEFORE INHERIT)"
- if (user_variable == 1)
- val = val " (USER VARIABLE)"
- if (output_variable == 1)
- val = val " (GENERATED BY ECLASS)"
-
- # check for invalid combos
- if (internal + pre_inherit + user_variable + output_variable > 1)
- fail(var_name ": multiple variable classes specified")
-
- if (internal == 1)
- return ""
-
- # now accumulate the stuff
- ret = \
- ".TP" "\n" \
- "\\fB" var_name "\\fR" val "\n" \
- man_text(desc)
-
- if (desc == "")
- fail(var_name ": no @DESCRIPTION found")
-
- return ret
-}
-function handle_variable() {
- show_function_header()
- ret = _handle_variable()
- if (ret == "")
- return
- print ret
-}
-function handle_eclass_variable() {
- ret = _handle_variable()
- if (ret == "")
- return
- if (eclass_variables != "")
- eclass_variables = eclass_variables "\n"
- eclass_variables = eclass_variables ret
-}
-
-#
-# Spit out the common footer of manpage
-#
-function handle_footer() {
- if (eclass_variables != "") {
- print ".SH \"ECLASS VARIABLES\""
- print man_text(eclass_variables)
- }
- if (eclass_author != "") {
- print ".SH \"AUTHORS\""
- print pre_text(man_text(eclass_author))
- }
- if (eclass_maintainer != "") {
- print ".SH \"MAINTAINERS\""
- print pre_text(man_text(eclass_maintainer))
- }
- print ".SH \"REPORTING BUGS\""
- print reporting_bugs
- print ".SH \"FILES\""
- print ".BR " eclass
- print ".SH \"SEE ALSO\""
- print ".BR ebuild (5)"
- print pre_text(gensub("@ECLASS@", eclass, 1, vcs_url))
-}
-
-#
-# Init parser
-#
-BEGIN {
- state = "header"
- reporting_bugs = "Please report bugs via https://bugs.gentoo.org/"
- vcs_url = "https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@"
-}
-
-#
-# Main parsing routine
-#
-{
- if (state == "header") {
- if ($0 ~ /^# @ECLASS:/) {
- handle_eclass()
- state = "funcvar"
- } else if ($0 == "# @DEAD") {
- eclass = "dead"
- exit(77)
- } else if ($0 == "# @eclass-begin") {
- # White list old eclasses that haven't been updated so we can block
- # new ones from being added to the tree.
- if (eclass == "")
- xfail("java documentation not supported")
- fail("java documentation not supported")
- } else if ($0 ~ /^# @/)
- warn("Unexpected tag in \"" state "\" state: " $0)
- } else if (state == "funcvar") {
- if ($0 ~ /^# @FUNCTION:/)
- handle_function()
- else if ($0 ~ /^# @VARIABLE:/)
- handle_variable()
- else if ($0 ~ /^# @ECLASS-VARIABLE:/)
- handle_eclass_variable()
- else if ($0 ~ /^# @/)
- warn("Unexpected tag in \"" state "\" state: " $0)
- }
-}
-
-#
-# Tail end
-#
-END {
- if (eclass == "")
- xfail("eclass not documented yet (no @ECLASS found)")
- else if (eclass != "dead")
- handle_footer()
-}
^ permalink raw reply related [flat|nested] 3+ messages in thread
* [gentoo-commits] repo/gentoo:master commit in: app-doc/eclass-manpages/files/
@ 2019-03-26 20:10 Aaron Bauman
0 siblings, 0 replies; 3+ messages in thread
From: Aaron Bauman @ 2019-03-26 20:10 UTC (permalink / raw
To: gentoo-commits
commit: 65cc7207f87a9f1ef488d7985eeb182f1802d4d7
Author: Aaron Bauman <bman <AT> gentoo <DOT> org>
AuthorDate: Tue Mar 26 20:08:47 2019 +0000
Commit: Aaron Bauman <bman <AT> gentoo <DOT> org>
CommitDate: Tue Mar 26 20:10:12 2019 +0000
URL: https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=65cc7207
Revert "app-doc/eclass-manpages: remove unused file"
This reverts commit 2e32186bbee30a4a2e1c4f37c79c61897e53d8df.
This should really not be stored here. I am reverting it to ensure the
maintainers can find a new home for it.
Signed-off-by: Aaron Bauman <bman <AT> gentoo.org>
.../eclass-manpages/files/eclass-to-manpage.awk | 457 +++++++++++++++++++++
1 file changed, 457 insertions(+)
diff --git a/app-doc/eclass-manpages/files/eclass-to-manpage.awk b/app-doc/eclass-manpages/files/eclass-to-manpage.awk
new file mode 100644
index 00000000000..b40eaf11209
--- /dev/null
+++ b/app-doc/eclass-manpages/files/eclass-to-manpage.awk
@@ -0,0 +1,457 @@
+# Copyright 1999-2017 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+
+# This awk converts the comment documentation found in eclasses
+# into man pages for easier/nicer reading.
+#
+# If you wish to have multiple paragraphs in a description, then
+# create empty comment lines. Paragraph parsing ends when the comment
+# block does.
+
+# The format of the eclass description:
+# @ECLASS: foo.eclass
+# @MAINTAINER:
+# <required; list of contacts, one per line>
+# @AUTHOR:
+# <optional; list of authors, one per line>
+# @BUGREPORTS:
+# <optional; description of how to report bugs;
+# default: tell people to use bugs.gentoo.org>
+# @VCSURL: <optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@>
+# @SUPPORTED_EAPIS: <optional; space-separated list of EAPIs>
+# @BLURB: <required; short description>
+# @DESCRIPTION:
+# <optional; long description>
+# @EXAMPLE:
+# <optional; example usage>
+
+# The format of functions:
+# @FUNCTION: foo
+# @USAGE: <required arguments to foo> [optional arguments to foo]
+# @RETURN: <whatever foo returns>
+# @MAINTAINER:
+# <optional; list of contacts, one per line>
+# [@INTERNAL]
+# @DESCRIPTION:
+# <required if no @RETURN; blurb about this function>
+
+# The format of function-specific variables:
+# @VARIABLE: foo
+# [@USER_VARIABLE] (set in make.conf, not ebuilds)
+# [@INTERNAL] (internal eclass use variable)
+# [@DEFAULT_UNSET]
+# [@REQUIRED]
+# @DESCRIPTION:
+# <required; blurb about this variable>
+# foo="<default value>"
+
+# The format of eclass variables:
+# @ECLASS-VARIABLE: foo
+# [@PRE_INHERIT] (the variable must be set before inheriting the eclass)
+# [@USER_VARIABLE] (set in make.conf, not ebuilds)
+# [@OUTPUT_VARIABLE] (set by eclass, to be read in ebuilds)
+# [@INTERNAL] (internal eclass use variable)
+# [@DEFAULT_UNSET]
+# [@REQUIRED]
+# @DESCRIPTION:
+# <required; blurb about this variable>
+# foo="<default value>"
+
+# Disable manpage generation:
+# @DEAD
+
+# Common features:
+# @CODE
+# In multiline paragraphs, you can create chunks of unformatted
+# code by using this marker at the start and end.
+# @CODE
+#
+# @ROFF <some roff macros>
+# If you want a little more manual control over the formatting, you can
+# insert roff macros directly into the output by using the @ROFF escape.
+
+function _stderr_msg(text, type, file, cnt) {
+ if (_stderr_header_done != 1) {
+ cnt = split(FILENAME, file, /\//)
+ print "\n" file[cnt] ":" > "/dev/stderr"
+ _stderr_header_done = 1
+ }
+
+ print " " type ":" NR ": " text > "/dev/stderr"
+}
+function warn(text) {
+ _stderr_msg(text, "warning")
+}
+function fail(text) {
+ _stderr_msg(text, "error")
+ exit(1)
+}
+function xfail(text) {
+ _stderr_msg(text, "error (ignoring)")
+ exit(77)
+}
+
+function eat_line() {
+ ret = $0
+ sub(/^# @[A-Z]*:[[:space:]]*/,"",ret)
+ getline
+ return ret
+}
+function eat_paragraph() {
+ code = 0
+ ret = ""
+ getline
+ while ($0 ~ /^#/) {
+ # Only allow certain tokens in the middle of paragraphs
+ if ($2 ~ /^@/ && $2 !~ /^@(CODE|ROFF)$/)
+ break
+
+ sub(/^#[[:space:]]?/, "", $0)
+
+ # Escape . at start of line #420153
+ if ($0 ~ /^[.]/)
+ $0 = "\\&" $0
+
+ # Translate @CODE into @ROFF
+ if ($1 == "@CODE" && NF == 1) {
+ if (code)
+ $0 = "@ROFF .fi"
+ else
+ $0 = "@ROFF .nf"
+ code = !code
+ }
+
+ # Allow people to specify *roff commands directly
+ if ($1 == "@ROFF")
+ sub(/^@ROFF[[:space:]]*/, "", $0)
+
+ ret = ret "\n" $0
+
+ # Handle the common case of trailing backslashes in
+ # code blocks to cross multiple lines #335702
+ if (code && $NF == "\\")
+ ret = ret "\\"
+ getline
+ }
+ sub(/^\n/,"",ret)
+ return ret
+}
+
+function pre_text(p) {
+ return ".nf\n" p "\n.fi"
+}
+
+function man_text(p) {
+ return gensub(/-/, "\\-", "g", p)
+}
+
+#
+# Handle an @ECLASS block
+#
+function handle_eclass() {
+ eclass = $3
+ eclass_maintainer = ""
+ eclass_author = ""
+ supported_eapis = ""
+ blurb = ""
+ desc = ""
+ example = ""
+
+ # Sanity check the eclass name. #537392
+ if (eclass !~ /[.]eclass$/)
+ fail(eclass ": @ECLASS name is missing a '.eclass' suffix")
+
+ # first the man page header
+ print ".\\\" -*- coding: utf-8 -*-"
+ print ".\\\" ### DO NOT EDIT THIS FILE"
+ print ".\\\" ### This man page is autogenerated by eclass-to-manpage.awk"
+ print ".\\\" ### based on comments found in " eclass
+ print ".\\\""
+ print ".\\\" See eclass-to-manpage.awk for documentation on how to get"
+ print ".\\\" your eclass nicely documented as well."
+ print ".\\\""
+ print ".TH \"" toupper(eclass) "\" 5 \"" strftime("%b %Y") "\" \"Portage\" \"portage\""
+
+ # now eat the global data
+ getline
+ if ($2 == "@MAINTAINER:")
+ eclass_maintainer = eat_paragraph()
+ if ($2 == "@AUTHOR:")
+ eclass_author = eat_paragraph()
+ if ($2 == "@BUGREPORTS:")
+ reporting_bugs = eat_paragraph()
+ if ($2 == "@VCSURL:")
+ vcs_url = eat_line()
+ if ($2 == "@SUPPORTED_EAPIS:")
+ supported_eapis = eat_line()
+ if ($2 == "@BLURB:")
+ blurb = eat_line()
+ if ($2 == "@DESCRIPTION:")
+ desc = eat_paragraph()
+ if ($2 == "@EXAMPLE:")
+ example = eat_paragraph()
+ # in case they typo-ed the keyword, bail now
+ if ($2 ~ /^@/)
+ fail(eclass ": unknown keyword " $2)
+
+ # finally display it
+ print ".SH \"NAME\""
+ print eclass " \\- " man_text(blurb)
+ if (desc != "") {
+ print ".SH \"DESCRIPTION\""
+ print man_text(desc)
+ }
+ if (example != "") {
+ print ".SH \"EXAMPLE\""
+ print man_text(example)
+ }
+
+ # sanity checks
+ if (blurb == "")
+ fail(eclass ": no @BLURB found")
+ if (eclass_maintainer == "")
+ warn(eclass ": no @MAINTAINER found")
+}
+
+#
+# Handle a @FUNCTION block
+#
+function show_function_header() {
+ if (_function_header_done != 1) {
+ print ".SH \"FUNCTIONS\""
+ _function_header_done = 1
+ }
+}
+function handle_function() {
+ func_name = $3
+ usage = ""
+ funcret = ""
+ maintainer = ""
+ internal = 0
+ desc = ""
+
+ # make sure people haven't specified this before (copy & paste error)
+ if (all_funcs[func_name])
+ fail(eclass ": duplicate definition found for function: " func_name)
+ all_funcs[func_name] = func_name
+
+ # grab the docs
+ getline
+ if ($2 == "@USAGE:")
+ usage = eat_line()
+ if ($2 == "@RETURN:")
+ funcret = eat_line()
+ if ($2 == "@MAINTAINER:")
+ maintainer = eat_paragraph()
+ if ($2 == "@INTERNAL") {
+ internal = 1
+ getline
+ }
+ if ($2 == "@DESCRIPTION:")
+ desc = eat_paragraph()
+
+ if (internal == 1)
+ return
+
+ show_function_header()
+
+ # now print out the stuff
+ print ".TP"
+ print "\\fB" func_name "\\fR " man_text(usage)
+ if (desc != "")
+ print man_text(desc)
+ if (funcret != "") {
+ if (desc != "")
+ print ""
+ print "Return value: " funcret
+ }
+
+ if (blurb == "")
+ fail(func_name ": no @BLURB found")
+ if (desc == "" && funcret == "")
+ fail(func_name ": no @DESCRIPTION found")
+}
+
+#
+# Handle @VARIABLE and @ECLASS-VARIABLE blocks
+#
+function _handle_variable() {
+ var_name = $3
+ desc = ""
+ val = ""
+ default_unset = 0
+ internal = 0
+ required = 0
+
+ # additional variable classes
+ pre_inherit = 0
+ user_variable = 0
+ output_variable = 0
+
+ # make sure people haven't specified this before (copy & paste error)
+ if (all_vars[var_name])
+ fail(eclass ": duplicate definition found for variable: " var_name)
+ all_vars[var_name] = var_name
+
+ # grab the optional attributes
+ opts = 1
+ while (opts) {
+ getline
+ if ($2 == "@DEFAULT_UNSET")
+ default_unset = 1
+ else if ($2 == "@INTERNAL")
+ internal = 1
+ else if ($2 == "@REQUIRED")
+ required = 1
+ else if ($2 == "@PRE_INHERIT")
+ pre_inherit = 1
+ else if ($2 == "@USER_VARIABLE")
+ user_variable = 1
+ else if ($2 == "@OUTPUT_VARIABLE")
+ output_variable = 1
+ else
+ opts = 0
+ }
+ if ($2 == "@DESCRIPTION:")
+ desc = eat_paragraph()
+
+ # extract the default variable value
+ # first try var="val"
+ op = "="
+ regex = "^.*" var_name "=(.*)$"
+ val = gensub(regex, "\\1", 1, $0)
+ if (val == $0) {
+ # next try : ${var:=val}
+ op = "?="
+ regex = "^[[:space:]]*:[[:space:]]*[$]{" var_name ":?=(.*)}"
+ val = gensub(regex, "\\1", 1, $0)
+ if (val == $0) {
+ if (default_unset + required + internal + output_variable == 0)
+ warn(var_name ": unable to extract default variable content: " $0)
+ val = ""
+ } else if (val !~ /^["']/ && val ~ / /) {
+ if (default_unset == 1)
+ warn(var_name ": marked as unset, but has value: " val)
+ val = "\"" val "\""
+ }
+ }
+ if (length(val))
+ val = " " op " \\fI" val "\\fR"
+ if (required == 1)
+ val = val " (REQUIRED)"
+ # TODO: group variables using those classes
+ if (pre_inherit == 1)
+ val = val " (SET BEFORE INHERIT)"
+ if (user_variable == 1)
+ val = val " (USER VARIABLE)"
+ if (output_variable == 1)
+ val = val " (GENERATED BY ECLASS)"
+
+ # check for invalid combos
+ if (internal + pre_inherit + user_variable + output_variable > 1)
+ fail(var_name ": multiple variable classes specified")
+
+ if (internal == 1)
+ return ""
+
+ # now accumulate the stuff
+ ret = \
+ ".TP" "\n" \
+ "\\fB" var_name "\\fR" val "\n" \
+ man_text(desc)
+
+ if (desc == "")
+ fail(var_name ": no @DESCRIPTION found")
+
+ return ret
+}
+function handle_variable() {
+ show_function_header()
+ ret = _handle_variable()
+ if (ret == "")
+ return
+ print ret
+}
+function handle_eclass_variable() {
+ ret = _handle_variable()
+ if (ret == "")
+ return
+ if (eclass_variables != "")
+ eclass_variables = eclass_variables "\n"
+ eclass_variables = eclass_variables ret
+}
+
+#
+# Spit out the common footer of manpage
+#
+function handle_footer() {
+ if (eclass_variables != "") {
+ print ".SH \"ECLASS VARIABLES\""
+ print man_text(eclass_variables)
+ }
+ if (eclass_author != "") {
+ print ".SH \"AUTHORS\""
+ print pre_text(man_text(eclass_author))
+ }
+ if (eclass_maintainer != "") {
+ print ".SH \"MAINTAINERS\""
+ print pre_text(man_text(eclass_maintainer))
+ }
+ print ".SH \"REPORTING BUGS\""
+ print reporting_bugs
+ print ".SH \"FILES\""
+ print ".BR " eclass
+ print ".SH \"SEE ALSO\""
+ print ".BR ebuild (5)"
+ print pre_text(gensub("@ECLASS@", eclass, 1, vcs_url))
+}
+
+#
+# Init parser
+#
+BEGIN {
+ state = "header"
+ reporting_bugs = "Please report bugs via https://bugs.gentoo.org/"
+ vcs_url = "https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@"
+}
+
+#
+# Main parsing routine
+#
+{
+ if (state == "header") {
+ if ($0 ~ /^# @ECLASS:/) {
+ handle_eclass()
+ state = "funcvar"
+ } else if ($0 == "# @DEAD") {
+ eclass = "dead"
+ exit(77)
+ } else if ($0 == "# @eclass-begin") {
+ # White list old eclasses that haven't been updated so we can block
+ # new ones from being added to the tree.
+ if (eclass == "")
+ xfail("java documentation not supported")
+ fail("java documentation not supported")
+ } else if ($0 ~ /^# @/)
+ warn("Unexpected tag in \"" state "\" state: " $0)
+ } else if (state == "funcvar") {
+ if ($0 ~ /^# @FUNCTION:/)
+ handle_function()
+ else if ($0 ~ /^# @VARIABLE:/)
+ handle_variable()
+ else if ($0 ~ /^# @ECLASS-VARIABLE:/)
+ handle_eclass_variable()
+ else if ($0 ~ /^# @/)
+ warn("Unexpected tag in \"" state "\" state: " $0)
+ }
+}
+
+#
+# Tail end
+#
+END {
+ if (eclass == "")
+ xfail("eclass not documented yet (no @ECLASS found)")
+ else if (eclass != "dead")
+ handle_footer()
+}
^ permalink raw reply related [flat|nested] 3+ messages in thread
* [gentoo-commits] repo/gentoo:master commit in: app-doc/eclass-manpages/files/
@ 2019-03-27 17:22 Michał Górny
0 siblings, 0 replies; 3+ messages in thread
From: Michał Górny @ 2019-03-27 17:22 UTC (permalink / raw
To: gentoo-commits
commit: 396b2f8aeea0a241ea74d3b0a4508c4f7ca34241
Author: Joonas Niilola <juippis <AT> gmail <DOT> com>
AuthorDate: Wed Mar 27 14:06:09 2019 +0000
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Wed Mar 27 17:22:14 2019 +0000
URL: https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=396b2f8a
app-doc/eclass-manpages: display @SUPPORTED_EAPIS
Package-Manager: Portage-2.3.62, Repoman-2.3.12
Signed-off-by: Joonas Niilola <juippis <AT> gmail.com>
Closes: https://github.com/gentoo/gentoo/pull/11516
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
app-doc/eclass-manpages/files/eclass-to-manpage.awk | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/app-doc/eclass-manpages/files/eclass-to-manpage.awk b/app-doc/eclass-manpages/files/eclass-to-manpage.awk
index b40eaf11209..53e05973e16 100644
--- a/app-doc/eclass-manpages/files/eclass-to-manpage.awk
+++ b/app-doc/eclass-manpages/files/eclass-to-manpage.awk
@@ -1,4 +1,4 @@
-# Copyright 1999-2017 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# This awk converts the comment documentation found in eclasses
@@ -93,7 +93,7 @@ function xfail(text) {
function eat_line() {
ret = $0
- sub(/^# @[A-Z]*:[[:space:]]*/,"",ret)
+ sub(/^# @[^:]+:[[:space:]]*/,"",ret)
getline
return ret
}
@@ -201,6 +201,10 @@ function handle_eclass() {
print ".SH \"DESCRIPTION\""
print man_text(desc)
}
+ if (supported_eapis != "") {
+ print ".SH \"SUPPORTED EAPIS\""
+ print man_text(supported_eapis)
+ }
if (example != "") {
print ".SH \"EXAMPLE\""
print man_text(example)
^ permalink raw reply related [flat|nested] 3+ messages in thread
end of thread, other threads:[~2019-03-27 17:22 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-03-26 19:33 [gentoo-commits] repo/gentoo:master commit in: app-doc/eclass-manpages/files/ Aaron Bauman
-- strict thread matches above, loose matches on Subject: below --
2019-03-26 20:10 Aaron Bauman
2019-03-27 17:22 Michał Górny
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox