app-portage/eclass-manpages: Move package to app-doc/eclass-manpages.

Closes: https://bugs.gentoo.org/680300
Acked-by: Michał Górny <mgorny@gentoo.org>
Signed-off-by: Ulrich Müller <ulm@gentoo.org>

8 files changed, 598 insertions, 6 deletions

diff --git a/app-doc/devmanual/devmanual-0_pre20141116.ebuild b/app-doc/devmanual/devmanual-0_pre20141116.ebuild
index e891efa24f23..15b7afe991b4 100644
--- a/app-doc/devmanual/devmanual-0_pre20141116.ebuild
+++ b/app-doc/devmanual/devmanual-0_pre20141116.ebuild
@@ -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
 
 EAPI=6
@@ -55,12 +55,12 @@ src_install() {
 
 pkg_postinst() {
 	readme.gentoo_print_elog
-	if ! has_version app-portage/eclass-manpages; then
+	if ! has_version app-doc/eclass-manpages; then
 		elog "The offline version of the devmanual does not include the"
 		elog "documentation for the eclasses. If you need it, then emerge"
 		elog "the following package:"
 		elog
-		elog "app-portage/eclass-manpages"
+		elog "app-doc/eclass-manpages"
 		elog
 	fi
 }
diff --git a/app-doc/devmanual/devmanual-9999.ebuild b/app-doc/devmanual/devmanual-9999.ebuild
index e891efa24f23..15b7afe991b4 100644
--- a/app-doc/devmanual/devmanual-9999.ebuild
+++ b/app-doc/devmanual/devmanual-9999.ebuild
@@ -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
 
 EAPI=6
@@ -55,12 +55,12 @@ src_install() {
 
 pkg_postinst() {
 	readme.gentoo_print_elog
-	if ! has_version app-portage/eclass-manpages; then
+	if ! has_version app-doc/eclass-manpages; then
 		elog "The offline version of the devmanual does not include the"
 		elog "documentation for the eclasses. If you need it, then emerge"
 		elog "the following package:"
 		elog
-		elog "app-portage/eclass-manpages"
+		elog "app-doc/eclass-manpages"
 		elog
 	fi
 }
diff --git a/app-doc/eclass-manpages/Manifest b/app-doc/eclass-manpages/Manifest
new file mode 100644
index 000000000000..693ca819202d
--- /dev/null
+++ b/app-doc/eclass-manpages/Manifest
@@ -0,0 +1 @@
+DIST eclass-manpages-20180812.tar.xz 419912 BLAKE2B 35659ac43e43e71c600fb4955267c9d57ed36f29e0607150a8e8c061b158b6135a4b91f4e4c05fa178a03aa3068726ac13cd54e4cd135fbe152c8bebf81659bb SHA512 6d01070c6113e5d5f4102d466abaa03ae824350285ca71a5a4f84d859f6c473e8e92d3f5387b76c4bb5dc8bcedcc6b36a63e074d70725c87233dea4fa6a6d0c6
diff --git a/app-doc/eclass-manpages/eclass-manpages-20180812.ebuild b/app-doc/eclass-manpages/eclass-manpages-20180812.ebuild
new file mode 100644
index 000000000000..db10d2aba060
--- /dev/null
+++ b/app-doc/eclass-manpages/eclass-manpages-20180812.ebuild
@@ -0,0 +1,33 @@
+# Copyright 1999-2018 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+
+EAPI="6"
+
+DESCRIPTION="Collection of Gentoo eclass manpages"
+HOMEPAGE="https://www.gentoo.org/"
+SRC_URI="https://dev.gentoo.org/~mgorny/dist/${P}.tar.xz"
+
+LICENSE="GPL-2"
+SLOT="0"
+# Keep the keywords stabled. No need to change to ~arch.
+KEYWORDS="alpha amd64 arm arm64 hppa ia64 m68k ~mips ppc ppc64 s390 sh sparc x86 ~x86-fbsd ~amd64-linux ~x86-linux ~x64-macos ~x86-solaris"
+
+DEPEND="app-arch/xz-utils"
+
+# How to create a snapshot and upload it to your dev-space:
+#
+# mkdir eclass-manpages-$(date +%Y%m%d)
+# cp "$(portageq get_repo_path / gentoo)"/eclass/*.eclass eclass-manpages-$(date +%Y%m%d)/
+# tar -cf eclass-manpages-$(date +%Y%m%d).tar eclass-manpages-$(date +%Y%m%d)
+# xz -e eclass-manpages-$(date +%Y%m%d).tar
+# scp eclass-manpages-$(date +%Y%m%d).tar.xz dev.gentoo.org:public_html/dist/
+#
+# Then copy the ebuild and update your name in SRC_URI ;-).
+
+src_compile() {
+	env ECLASSDIR="${S}" bash "${FILESDIR}"/eclass-to-manpage.sh || die
+}
+
+src_install() {
+	doman *.5
+}
diff --git a/app-doc/eclass-manpages/eclass-manpages-99999999.ebuild b/app-doc/eclass-manpages/eclass-manpages-99999999.ebuild
new file mode 100644
index 000000000000..ea11ad476084
--- /dev/null
+++ b/app-doc/eclass-manpages/eclass-manpages-99999999.ebuild
@@ -0,0 +1,45 @@
+# Copyright 1999-2018 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+
+EAPI="6"
+
+DESCRIPTION="Collection of Gentoo eclass manpages"
+HOMEPAGE="https://www.gentoo.org/"
+SRC_URI=""
+
+LICENSE="GPL-2"
+SLOT="0"
+KEYWORDS=""
+IUSE=""
+
+DEPEND="
+	|| (
+		sys-apps/portage
+		sys-apps/portage-mgorny
+	)"
+
+S=${WORKDIR}
+
+genit() {
+	local e=${1:-${ECLASSDIR}}
+	einfo "Generating man pages from: ${e}"
+	# Need `bash` because the .sh isn't +x on the servers #451352
+	env ECLASSDIR=${e} bash "${FILESDIR}"/eclass-to-manpage.sh || die
+}
+
+src_compile() {
+	# First process any eclasses found in overlays.  Then process
+	# the main eclassdir last so that its output will clobber anything
+	# that might have come from overlays.  Main tree wins!
+	local o e
+	for o in $(portageq get_repos /) ; do
+		e="$(portageq get_repo_path / ${o})/eclass"
+		[[ -d ${e} ]] || continue
+		genit "${e}" || die
+	done
+	genit || die
+}
+
+src_install() {
+	doman *.5
+}
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 000000000000..b40eaf112091
--- /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()
+}
diff --git a/app-doc/eclass-manpages/files/eclass-to-manpage.sh b/app-doc/eclass-manpages/files/eclass-to-manpage.sh
new file mode 100755
index 000000000000..55d25aaaf4d3
--- /dev/null
+++ b/app-doc/eclass-manpages/files/eclass-to-manpage.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+
+: ${ECLASSDIR:=${0%/*}/../../../eclass}
+: ${FILESDIR:=${0%/*}}
+
+AWK="gawk"
+while [[ $# -gt 0 ]] ; do
+	case $1 in
+	-e) ECLASSDIR=$2; shift;;
+	-f) FILESDIR=$2; shift;;
+	-d) AWK="dgawk";;
+	*) break;;
+	esac
+	shift
+done
+
+if [[ ! -d ${ECLASSDIR} ]] ; then
+	echo "Usage: ${0##*/} [-e eclassdir] [-f eclass-to-manpage.awk FILESDIR] [eclasses]" 1>&2
+	exit 1
+fi
+
+[[ $# -eq 0 ]] && set -- "${ECLASSDIR}"/*.eclass
+
+ret=0
+for e in "$@" ; do
+	set -- \
+	${AWK} \
+		-f "${FILESDIR}"/eclass-to-manpage.awk \
+		${e}
+	if [[ ${AWK} == "gawk" ]] ; then
+		"$@" > ${e##*/}.5
+		tret=$?
+		if [[ ${tret} -ne 0 ]] ; then
+			rm -f ${e##*/}.5
+			if [[ ${tret} -ne 77 ]] ; then
+				echo "FAIL: ${e}"
+				ret=1
+			fi
+		fi
+	else
+		"$@"
+	fi
+done
+exit ${ret}
diff --git a/app-doc/eclass-manpages/metadata.xml b/app-doc/eclass-manpages/metadata.xml
new file mode 100644
index 000000000000..adfe3aaf03f3
--- /dev/null
+++ b/app-doc/eclass-manpages/metadata.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+	<maintainer type="person">
+		<email>mgorny@gentoo.org</email>
+		<name>Michał Górny</name>
+	</maintainer>
+	<maintainer type="project">
+		<email>tools-portage@gentoo.org</email>
+		<name>Gentoo Portage tools team</name>
+	</maintainer>
+</pkgmetadata>