#!/bin/sh

man() {
	cat << \EOT
NAME
  src2man - extract man pages from source files.
SYNOPSIS
  src2man [-n][-v volume][-r release] [srcfile ...]
DESCRIPTION
  src2man scans source file srcfile. Only C source files are supported
  for now. Comments blocks starting by "/** num", where num is a section
  number, are converted into a man file, using txt2man(1).

  The first line of the comment block must contain the name of the manpage,
  usually the function name, followed by a "-" and a short description.
  The following lines are the "DESCRIPTION" section content, except if they
  are in upper case, in which case they define a new section.

  If the next line after a comment block is a C function prototype, then a
  "SYNOPSIS" section will be filled using that prototype. This avoids to
  duplicate the prototype in the comment block.

  The best place for code documentation is in the source file, where the body is
  implemented, not the header file which only contains the prototype. src2man
  automatically searches for the presence of a prototype in the corresponding
  header file, and if found, will print a "#include" statement in the synopsis.
OPTIONS
  -n		No man page is created. The name of the manpages that would
  		be created are printed.
  -p volume   Specify the name of the volume to be printed in center header
  		of generated manpages.
  -r release	Specify the project and release number for the generated
		manpage.
EXAMPLE
  The following example displays C code and comments to generate a manpage
  foobar.3:

     /** 3
      * foobar - a sample dummy function
      * This line is now the first of the description section.
      * Note that function parameters parm1 and parm2 are highlighted
      * in the generated man page.
      */
     int foobar(char *parm1, int parm2)
     {
     	...
	return 0;
     }

SEE ALSO
  txt2man(1), bookman(1).
AUTHOR
  Marc Vertes <mvertes@free.fr>
EOT
}

nogen=0
release=unknown
while getopts :hnr:v: opt
do
	case $opt in
	n) nogen=1;;
	v) volume="$OPTARG";;
	r) release="$OPTARG";;
	*) man; exit;;
	esac
done
shift $(($OPTIND - 1))

#
# Extract manpages from source files. Man page content is enclosed in
# commment blocks starting by "/** sectnum"
#
awk -v release="$release" -v volume="$volume" -v nogen=$nogen '
/\/\*\* [0-9]/ {
	sect = $2
	getline
	sub(/^ \* */, "  ")
	title = $1
	name = $0
	inc = FILENAME
	sub(/.[cS]$/, ".h", inc)
	found = ""
	grep_cmd = "test -f " inc " && grep -wq " title "  " inc " \
		   2>/dev/null && echo ok || echo nok"
	grep_cmd | getline found
	# description section extraction.
	in_synop = 0
	synop = ""
	while (getline) {
		if ($0 ~ /^ *\*\//)
			break
		sub(/^ \* /, "")
		sub(/^ \*/, "")
		if ($1 ~ /^[A-Z ]+$/ && $1 != "SYNOPSIS")
			in_synop = 0
		if ($1 == "SYNOPSIS") {
			in_synop = 1
			continue
		}
		if ($1 == "DESCRIPTION")
			continue
		if (in_synop)
			synop = synop (synop ? "\n" : "") $0
		else
			desc = desc (desc ? "\n" : "") $0
	}
	# prototype extraction for synopsis.
	while (getline) {
		if (synop)
			break
		sub(/^[ \t]*/, "")
		synop = synop (synop ? "\n" : "") $0
		if ($0 ~/\)[ \t{}\;]*$/) {
			sub(/{[^}]}/, "", synop)
			sub(/[ \t]*$/, "", synop)
			if (found == "ok")
				synop = "#include \"" inc "\"\n" synop
			if (synop !~ /\;$/) 
				synop = synop ";"
			break
		}
		if ($0 ~/^\/\*\* [0-9]/ || $0 ~ /^#/) {
			synop = ""
			break
		}
	}
	print title "." sect > "/dev/stderr"
	if (nogen) {
		name = synop = desc = sect = ""
		next
	}
	print "NAME\n" name (synop ? "\nSYNOPSIS\n  " synop : "") \
	      "\nDESCRIPTION\n" desc "\nFILE\n  " FILENAME | \
	      "txt2man -v \"" volume "\" -r " release " -s " sect \
	      " -t " title " > " title "." sect
	name = synop = desc = sect = ""
}
' $*