From 9857b1c9ea73f2c1db8a5e878e549404ede7fa14 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dag-Erling=20Sm=C3=B8rgrav?= <des@des.no>
Date: Sat, 31 Mar 2012 21:16:40 +0000
Subject: [PATCH] Add support for custom sections, including a custom RETURN
 VALUES section which suppresses the auto-generated one.

Allow blank lines between list items.

If the name of a cross-referenced function is preceded by an
exclamation mark, leave it out of the SEE ALSO section.


git-svn-id: svn+ssh://svn.openpam.org/svn/openpam/trunk@542 185d5e19-27fe-0310-9dcf-9bff6b9f3609
---
 misc/gendoc.pl | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/misc/gendoc.pl b/misc/gendoc.pl
index 83e1027..702ce6e 100644
--- a/misc/gendoc.pl
+++ b/misc/gendoc.pl
@@ -136,6 +136,7 @@ sub parse_source($) {
     my $inlist;
     my $intaglist;
     my $inliteral;
+    my $customrv;
     my %xref;
     my @errors;
     my $author;
@@ -211,12 +212,19 @@ sub parse_source($) {
 	s/\\(.)/$1/gs;
 	if (m/^$/) {
 	    # paragraph separator
+	    if ($inlist || $intaglist) {
+		# either a blank line between list items, or a blank
+		# line after the final list item.  The latter case
+		# will be handled further down.
+		next;
+	    }
+	    if ($man =~ m/\n\.Sh [^\n]+\n$/s) {
+		# a blank line after a section header
+		next;
+	    }
 	    if ($man ne "" && $man !~ m/\.Pp\n$/s) {
 		if ($inliteral) {
 		    $man .= "\0\n";
-		} elsif ($inlist || $intaglist) {
-		    $man .= ".El\n.Pp\n";
-		    $inlist = $intaglist = 0;
 		} else {
 		    $man .= ".Pp\n";
 		}
@@ -229,6 +237,14 @@ sub parse_source($) {
 	    ++$xref{$sect}->{$page};
 	    next;
 	}
+	if (s/^([A-Z][0-9A-Z -]+)$/.Sh $1/) {
+	    if ($1 eq "RETURN VALUES") {
+		$customrv = $1;
+	    }
+	    $man =~ s/\n\.Pp$/\n/s;
+	    $man .= "$_\n";
+	    next;
+	}
 	if (s/^\s+-\s+//) {
 	    # item in bullet list
 	    if ($inliteral) {
@@ -291,6 +307,7 @@ sub parse_source($) {
 	s/\s*=(struct \w+(?: \*)?)\b\s*/\n.Vt $1\n/gs;
 	s/\s*:([a-z_]+)\b\s*/\n.Va $1\n/gs;
 	s/\s*;([a-z_]+)\b\s*/\n.Dv $1\n/gs;
+	s/\s*=!([a-z_]+)\b\s*/\n.Xr $1 3\n/gs;
 	while (s/\s*=([a-z_]+)\b\s*/\n.Xr $1 3\n/s) {
 	    ++$xref{3}->{$1};
 	}
@@ -331,6 +348,7 @@ sub parse_source($) {
 	'xref'		=> \%xref,
 	'errors'	=> \@errors,
 	'author'	=> $author,
+	'customrv'	=> $customrv,
     };
     if ($source =~ m/^ \* NODOC\s*$/m) {
 	$FUNCTIONS{$func}->{'nodoc'} = 1;
@@ -451,7 +469,9 @@ sub gendoc($) {
 $func->{'man'}
 ";
     my @errors = @{$func->{'errors'}};
-    if ($func->{'type'} eq "int" && @errors) {
+    if ($func->{'customrv'}) {
+	# leave it
+    } elsif ($func->{'type'} eq "int" && @errors) {
 	$mdoc .= ".Sh RETURN VALUES
 The
 .Nm