CVS gss/doc

[gss-commit]

Update of /home/cvs/gss/doc
In directory dopio:/tmp/cvs-serv11291

Modified Files:
        gdoc 
Log Message:
Sync some fixes from libidn.


--- /home/cvs/gss/doc/gdoc      2004/01/25 17:54:22     1.21
+++ /home/cvs/gss/doc/gdoc      2004/11/21 18:18:58     1.22
@@ -21,7 +21,8 @@
 
 # usage:
 # gdoc [ -docbook | -html | -text | -man | -tex | -texinfo | -listfunc ]
-#      [ -sourceversion verno ] [ -includefuncprefix ] [ -bugsto address ]
+#      [ -sourceversion verno ] [ -include file | -includefuncprefix ]
+#      [ -bugsto address ]
 #      [ -seeinfo infonode ] [ -copyright notice ] [ -verbatimcopying ]
 #      [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
 #
@@ -32,10 +33,14 @@
 #       Version number for source code, e.g. '1.0.4'.  Used in 'man' headers.
 #       Defaults to using current date.
 #
+#  -include FILE
+#       For man pages, mention #include <FILE.h> in the synopsis.
+#
 #  -includefuncprefix
-#       For man pages, generate a #include <FILE.h> based on the function
-#       prefix.  For example, a function gss_init_sec_context will generate
-#       an include statement of #include <gss.h>.
+#       For man pages, mention a #include <FILE.h> in the synopsis.
+#       The FILE derived from the function prefix.  For example, a
+#       function gss_init_sec_context will generate an include
+#       statement of #include <gss.h>.
 #
 #  -bugsto address
 #       For man pages, include a section about reporting bugs and mention
@@ -103,8 +108,8 @@
 # patterns, which are highlighted appropriately.
 #
 # 'funcname()' - function
-# '$ENVVAR' - environmental variable
-# '&struct_name' - name of a structure
+# '$ENVVAR' - environmental variable OBSOLETE (?)
+# '#struct_name' - name of a structure
 # '@parameter' - name of a parameter
 # '%CONST' - name of a constant.
 
@@ -121,7 +126,7 @@
 $type_constant = "\\\%(\\w+)";
 $type_func = "(\\w+\\(\\))";
 $type_param = "\\\@(\\w+)";
-$type_struct = "\\\&(\\w+)";
+$type_struct = "\\\#(\\w+)";
 $type_env = "(\\\$\\w+)";
 
 
@@ -135,7 +140,7 @@
                     $type_param, "<tt><b>\$1</b></tt>" );
 $blankline_html = "<p>";
 
-%highlights_texinfo = ( $type_constant, "address@hidden",
+%highlights_texinfo = ( $type_constant, "address@hidden",
                        $type_func, "address@hidden",
                        $type_struct, "address@hidden",
                        $type_param, "address@hidden" );
@@ -156,10 +161,10 @@
 $blankline_sgml = "</para><para>\n";
 
 # these are pretty rough
-%highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n",
-                   $type_func, "\\n.B \\\"\$1\\\"\\n",
-                   $type_struct, "\\n.I \\\"\$1\\\"\\n",
-                   $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" );
+%highlights_man = ( $type_constant, "\\\\fB\$1\\\\fP",
+                   $type_func, "\\\\fB\$1\\\\fP",
+                   $type_struct, "\\\\fB\$1\\\\fP",
+                   $type_param, "\\\\fI\$1\\\\fP" );
 $blankline_man = "";
 
 # text-mode
@@ -172,7 +177,7 @@
 
 sub usage {
     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex | 
-texinfo  -listfunc ]\n";
-    print "         [ -sourceversion verno ] [ -includefuncprefix ]\n";
+    print "         [ -sourceversion verno ] [ -include file | 
-includefuncprefix ]\n";
     print "         [ -bugsto address ] [ -seeinfo infonode ] [ -copyright 
notice]\n";
     print "         [ -verbatimcopying ]\n";
     print "         [ -function funcname [ -function funcname ...] ]\n";
@@ -220,11 +225,12 @@
        $blankline = $blankline_sgml;
     } elsif ($cmd eq "-listfunc") {
        $output_mode = "listfunc";
-    } elsif ($cmd eq "-module") {
-       # not needed for sgml, inherits from calling document
+    } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling 
document
        $modulename = shift @ARGV;
     } elsif ($cmd eq "-sourceversion") {
        $sourceversion = shift @ARGV;
+    } elsif ($cmd eq "-include") {
+       $include = shift @ARGV;
     } elsif ($cmd eq "-includefuncprefix") {
        $includefuncprefix = 1;
     } elsif ($cmd eq "-bugsto") {
@@ -277,7 +283,7 @@
 #  parameters => %parameter descriptions
 #  sectionlist => @list of sections
 #  sections => %descriont descriptions
-#
+#  
 
 sub repstr {
     $pattern = shift;
@@ -369,7 +375,6 @@
            chop;
            print "address@hidden".$parameter."}: " . $_ . "\n";
            unlink "tmp";
-
        }
     }
     foreach $section (@{$args{'sectionlist'}}) {
@@ -472,7 +477,7 @@
 #      print "\n";
 
        $param3 = $args{'parameters'}{$parameter};
-       $param3 =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
+       $param3 =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
 
        $out = just_highlight($param3);
        $out =~ s/_/\\_/g;
@@ -486,14 +491,14 @@
     foreach $section (@{$args{'sectionlist'}}) {
        $sec = $section;
        $sec =~ s/_/\\_/g;
-       $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
+       $sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
 
        print "\n{\\large{$sec}}\\\\\n";
        print "\\begin{rmfamily}\n";
 
        $sec = $args{'sections'}{$section};
        $sec =~ s/\\:/:/g;
-       $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
+       $sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
        $sec =~ s/->/\$\\rightarrow\$/g;
        $sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
 
@@ -599,13 +604,21 @@
     my ($parameter, $section);
     my $count;
 
+    print ".\\\" DO NOT MODIFY THIS FILE!  It was generated by gdoc.\n";
     print ".TH \"$args{'function'}\" 3 \"$args{'sourceversion'}\" \"". 
$args{'module'} . "\" \"". $args{'module'} . "\"\n";
 
     print ".SH NAME\n";
 
-    print $args{'function'}."\n";
+    print $args{'function'};
+    if ($args{'purpose'}) {
+       print " \\- " . $args{'purpose'} . "\n";
+    } else {
+       print " \\- API function\n";
+    }
 
     print ".SH SYNOPSIS\n";
+    print ".B #include <". $args{'include'} . ">\n"
+       if $args{'include'};
     print ".B #include <". lc((split /_/, $args{'function'})[0]) . ".h>\n"
        if $args{'includefuncprefix'};
     print ".sp\n";
@@ -752,6 +765,7 @@
        output_function({'function' => $function_name,
                         'module' => $modulename,
                         'sourceversion' => $sourceversion,
+                        'include' => $include,
                         'includefuncprefix' => $includefuncprefix,
                         'bugsto' => $bugsto,
                         'copyright' => $copyright,
@@ -778,7 +792,7 @@
 $state = 0;
 $section = "";
 
-$doc_special = "address@hidden&";
+$doc_special = "address@hidden";
 
 $doc_start = "^/\\*\\*\$";
 $doc_end = "\\*/";
@@ -814,7 +828,7 @@
            if (/$doc_func/o) {
                $function = $1;
                $state = 2;
-               if (/-(.*)/) {
+               if (/-\s*(.*)/) {
                    $function_purpose = $1;
                } else {
                    $function_purpose = "";