# Copyright 1999-2007 Gentoo Foundation # Distributed under the terms of the GNU General Public License v2 # $Header: /var/cvsroot/gentoo-x86/app-portage/eclass-manpages/files/eclass-to-manpage.awk,v 1.11 2007/09/01 21:31:39 vapier Exp $ # 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: # # @BLURB: # @DESCRIPTION: # # @EXAMPLE: # # The format of functions: # @FUNCTION: foo # @USAGE: [optional arguments to foo] # @RETURN: # @MAINTAINER: # # @DESCRIPTION: # # The format of function-specific variables: # @VARIABLE: foo # @DESCRIPTION: # # foo="" # The format of eclass variables: # @ECLASS-VARIABLE: foo # @DESCRIPTION: # # foo="" # Common features: # @CODE # In multiline paragraphs, you can create chunks of unformatted # code by using this marker at the start and end. # @CODE function _stderr_msg(text, type) { print FILENAME ":" NR ":" type ": " text > "/dev/stderr" } function warn(text) { _stderr_msg(text, "warning") } function fail(text) { _stderr_msg(text, "error") exit(1) } function eat_line() { ret = $0 sub(/^# @[A-Z]*:[[:space:]]*/,"",ret) sub(//, "\\>", ret) getline return ret } function eat_paragraph() { code = 0 ret = "" getline while ($0 ~ /^#([[:space:]]*$|[[:space:]][^@])/) { sub(/^#[[:space:]]?/, "", $0) sub(//, "\\>", $0) if ($0 == "") ret = ret "

" $0 else ret = ret "\n" $0 getline if ($0 ~ /^# @CODE$/) { if (code) ret = ret "\n

" else ret = ret "\n

"
			code = !code
			getline
		}
	}
	sub(/^\n/,"",ret)
	return ret
}

function chapter(title, p) {
	print ""
	print "" toupper(title) ""
	print "
"
	print "
" p "
"
	print "
"
	print ""
}

#
# Handle an @ECLASS block
#
function handle_eclass() {
	eclass = $3
	eclass_maintainer = ""
	blurb = ""
	desc = ""
	example = ""

	# first the man page header
	print ""
	print ""
	print ""
	print "Documentation for " eclass ""
	print ""
	print "1.0"
	print "" strftime("%Y-%m-%d") ""

	# now eat the global data
	getline
	if ($2 == "@MAINTAINER:")
		eclass_maintainer = eat_paragraph()
	if ($2 == "@BLURB:")
		blurb = eat_line()
	if ($2 == "@DESCRIPTION:")
		desc = eat_paragraph()
	if ($2 == "@EXAMPLE:")
		example = eat_paragraph()

	# finally display it
	print ""
	print "" eclass_maintainer ""
	print ""
	chapter("NAME", "" eclass " - " blurb)
	chapter("DESCRIPTION", desc)
	if (example != "") {
		chapter("EXAMPLE", example)
	}

	# sanity checks
	if (blurb == "")
		fail(eclass ": no @BLURB found")
	if (desc == "")
		fail(eclass ": no @DESCRIPTION found")
	if (eclass_maintainer == "")
		warn(eclass ": no @MAINTAINER found")
}

#
# Handle a @FUNCTION block
#
function _handle_function() {
	func_name = $3
	usage = ""
	funcret = ""
	maintainer = ""
	desc = ""

	# grab the docs
	getline
	if ($2 == "@USAGE:")
		usage = eat_line()
	if ($2 == "@RETURN:")
		funcret = eat_line()
	if ($2 == "@MAINTAINER:")
		maintainer = eat_paragraph()
	if ($2 == "@DESCRIPTION:")
		desc = eat_paragraph()

	# now print out the stuff
	tag = "
" func_name " " usage "
"
	data = "
" desc

	if (funcret != "") {
		if (desc != "")
			data = data ""
		data = data "Return value: " funcret
	}

	data = data "
"

	if (blurb == "")
		fail(func_name ": no @BLURB found")
	if (desc == "" && funcret == "")
		fail(func_name ": no @DESCRIPTION found")

	return tag "" data
}

function handle_function() {
	if (functions != "")
		functions = functions "\n"
	functions = functions _handle_function()
}

#
# Handle @VARIABLE and @ECLASS-VARIABLE blocks
#
function _handle_variable() {
	var_name = $3
	desc = ""
	val = ""

	# grab the docs
	getline
	if ($2 == "@DESCRIPTION:")
		desc = eat_paragraph()

	# extract the default variable value
	val = $0
	regex = "^.*" var_name "="
	sub(regex, "", val)
	if ($0 == val) {
		val = ""
	} else
		val = " = " val

	# now accumulate the stuff
	ret = "
" var_name "" val "
" desc "
"

	if (desc == "")
		fail(var_name ": no @DESCRIPTION found")

	return ret
}

function handle_variable() {
	if (variables != "")
		variables = variables "\n"
	variables = variables _handle_variable()
}

function handle_eclass_variable() {
	if (eclass_variables != "")
		eclass_variables = eclass_variables "\n"
	eclass_variables = eclass_variables _handle_variable()
}

#
# Spit out the common footer of manpage
#
function handle_footer() {
	if (functions != "")
		chapter("FUNCTIONS", functions)
	if (variables != "")
		chapter("VARIABLES", variables)
	if (eclass_variables != "")
		chapter("ECLASS VARIABLES", eclass_variables)

	if (eclass_maintainer != "")
		chapter("MAINTAINERS", eclass_maintainer)

	chapter("REPORTING BUGS", "Please report bugs via http://bugs.gentoo.org/")
	chapter("FILES", "/usr/portage/eclass/" eclass "")
	chapter("SEE ALSO", "ebuild (5)")
	print ""
}

#
# Init parser
#
BEGIN {
	state = "header"
}

#
# Main parsing routine
#
{
	if (state == "header") {
		if ($0 ~ /^# @ECLASS:/) {
			handle_eclass()
			state = "funcvar"
		} 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 == "")
		fail("eclass not documented yet (no @ECLASS found)");
	else
		handle_footer()
}