From 9674c9502c5b4471432c134d40368bde11e2b386 Mon Sep 17 00:00:00 2001
From: Simon Josefsson <simon@josefsson.org>
Date: Tue, 9 Sep 2003 17:32:13 +0000
Subject: [PATCH] Improve man pages, unfortunately somewhat Shishi specific for
 the moment. Remove leading SPC in paragraphs.

---
 doc/gdoc | 52 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/doc/gdoc b/doc/gdoc
index 8584a3c1..00321957 100755
--- a/doc/gdoc
+++ b/doc/gdoc
@@ -86,6 +86,7 @@
 # 2. x^y with ${x}^{y}$.
 # 3. xxx\: with xxx:
 
+use POSIX qw(strftime);
 
 # match expressions used to find embedded type information
 $type_constant = "\\\%(\\w+)";
@@ -159,6 +160,7 @@ $output_mode = "man";
 %highlights = %highlights_man;
 $blankline = $blankline_man;
 $modulename = "API Documentation";
+$version = strftime "%Y-%m-%d", localtime;
 $function_only = 0;
 while ($ARGV[0] =~ m/^-(.*)/) {
     $cmd = shift @ARGV;
@@ -188,6 +190,8 @@ while ($ARGV[0] =~ m/^-(.*)/) {
 	$blankline = $blankline_sgml;
     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
 	$modulename = shift @ARGV;
+    } elsif ($cmd eq "-version") {
+	$version = shift @ARGV;
     } elsif ($cmd eq "-function") { # to only output specific functions
 	$function_only = 1;
 	$function = shift @ARGV;
@@ -245,6 +249,10 @@ sub output_highlight {
     my $contents = join "\n", @_;
     my $line;
 
+    if (substr($contents, 0, 1) eq " ") {
+	$contents = substr($contents, 1);
+    }
+
     $contents =~ s:{:\@{:gs if ($output_mode eq "texinfo");
     $contents =~ s:}:\@}:gs if ($output_mode eq "texinfo");
     eval $dohighlight;
@@ -505,32 +513,55 @@ sub output_man {
     my ($parameter, $section);
     my $count;
 
-    print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" GNOME\n";
+    print ".TH \"$args{'function'}\" 3 \"$args{'version'}\" \"GNU\" \"". uc($args{'module'}) . "\"\n";
 
-    print ".SH Function\n";
+    print ".SH NAME\n";
 
-    print ".I \"".$args{'functiontype'}."\"\n";
-    print ".B \"".$args{'function'}."\"\n";
-    print "(\n";
+    print $args{'function'}."\n";
+
+    print ".SH SYNOPSIS\n";
+    print ".B #include <". lc($args{'module'}) . ".h>\n";
+    print ".sp\n";
+    print ".BI \"".$args{'functiontype'}." ".$args{'function'}."(";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
-	print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n";
+	print $args{'parametertypes'}{$parameter}." \" ".$parameter." \"";
 	if ($count != $#{$args{'parameterlist'}}) {
 	    $count++;
-	    print ",\n";
+	    print ", ";
 	}
     }
-    print ")\n";
+    print ");\"\n";
 
-    print ".SH Arguments\n";
+    print ".SH ARGUMENTS\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
 	output_highlight($args{'parameters'}{$parameter});
     }
     foreach $section (@{$args{'sectionlist'}}) {
-	print ".SH \"$section\"\n";
+	print ".SH \"" . uc($section) . "\"\n";
 	output_highlight($args{'sections'}{$section});
     }
+    print ".SH \"REPORTING BUGS\"\n";
+    print "Report bugs to <bug-shishi\@josefsson.org>.\n";
+    print ".SH COPYRIGHT\n";
+    print "Copyright \\(co 2002, 2003 Simon Josefsson.\n";
+    print ".br\n";
+    print "Permission is granted to copy, distribute and/or modify this document\n";
+    print "under the terms of the GNU Free Documentation License, Version 1.1\n";
+    print "or any later version published by the Free Software Foundation.\n";
+    print ".SH \"SEE ALSO\"\n";
+    print "The full documentation for\n";
+    print ".B " . ucfirst($args{'module'}) . "\n";
+    print "is maintained as a Texinfo manual.  If the\n";
+    print ".B info\n";
+    print "and\n";
+    print ".B " . lc($args{'module'}) . "\n";
+    print "programs are properly installed at your site, the command\n";
+    print ".IP\n";
+    print ".B info " . lc($args{'module'}) . "\n";
+    print ".PP\n";
+    print "should give you access to the complete manual.\n";
 }
 
 ##
@@ -612,6 +643,7 @@ sub dump_function {
     if ($function_only==0 || defined($function_table{$function_name})) {
 	output_function({'function' => $function_name,
 			 'module' => $modulename,
+			 'version' => $version,
 			 'functiontype' => $return_type,
 			 'parameterlist' => \@parameterlist,
 			 'parameters' => \%parameters,
-- 
2.11.4.GIT