documentation updates

8 files changed, 329 insertions, 143 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 2065badd87..52c853fec8 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -27,7 +27,7 @@ One needs to trust one or more CAs for his secure communications. In
 that case only the certificates issued by the trusted authorities are
 acceptable.  See the figure above for a typical example.  The API for
 handling @acronym{X.509} certificates is described at section
-@ref{sec:x509api}.  Some examples are listed below.
+@ref{sec-x509api}.  Some examples are listed below.
 
 @menu
 * X.509 certificates::
@@ -125,7 +125,7 @@ private keys with the @code{gnutls_x509_privkey_t} type.  All the
 available functions for @acronym{X.509} certificate handling have
 their prototypes in @file{gnutls/x509.h}. An example program to
 demonstrate the @acronym{X.509} parsing capabilities can be found at
-section @ref{ex:x509-info}.
+section @ref{ex-x509-info}.
 
 @node Verifying X.509 certificate paths
 @subsection Verifying @acronym{X.509} Certificate Paths
@@ -208,7 +208,7 @@ Although the verification of a certificate path indicates that the
 certificate is signed by trusted authority, does not reveal anything
 about the peer's identity. It is required to verify if the
 certificate's owner is the one you expect. For more information
-consult @xcite{RFC2818} and section @ref{ex:verify} for an example.
+consult @xcite{RFC2818} and section @ref{ex-verify} for an example.
 
 @node PKCS #10 certificate requests
 @subsection @acronym{PKCS} #10 Certificate Requests
@@ -224,7 +224,7 @@ such as PKIX's @xcite{RFC4211} are not currently supported.
 
 In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled
 using the @code{gnutls_x509_crq_t} type.  An example of a certificate
-request generation can be found at section @ref{ex:crq}.
+request generation can be found at section @ref{ex-crq}.
 
 @node PKCS #12 structures
 @subsection @acronym{PKCS} #12 Structures
@@ -242,7 +242,7 @@ keys or encrypted data.  An Bag of type encrypted should be decrypted
 in order for its data to be accessed.
 
 An example of a @acronym{PKCS} #12 structure generation can be found
-at section @ref{ex:pkcs12}.
+at section @ref{ex-pkcs12}.
 
 @node The OpenPGP trust model
 @section The @acronym{OpenPGP} Trust Model
@@ -321,7 +321,7 @@ MD5.  These algorithms have been broken and should not be trusted.
 
 @node PKCS #11 tokens
 @section @acronym{PKCS #11} tokens
-@anchor{sec:pkcs11}
+@anchor{sec-pkcs11}
 @cindex @acronym{PKCS #11} tokens
 
 @subsection Introduction
@@ -509,7 +509,7 @@ to a token. This can be achieved with the following functions
 @subsection Using a @acronym{PKCS #11} token with TLS
 
 It is possible to use a @acronym{PKCS #11} token to a TLS
-session, as shown in @ref{ex:pkcs11-client}. In addition
+session, as shown in @ref{ex-pkcs11-client}. In addition
 the following functions can be used to load PKCS #11 key and
 certificates.
 
@@ -524,7 +524,7 @@ certificates.
 
 @node Abstract data types
 @section Abstract data types
-@anchor{sec:abstract}
+@anchor{sec-abstract}
 @cindex Abstract types
 
 Since there are many forms of a public or private keys supported by @acronym{GnuTLS} such as
diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi
index f73bc571e9..057f3a0824 100644
--- a/doc/cha-functions.texi
+++ b/doc/cha-functions.texi
@@ -21,7 +21,7 @@ The prototypes for the following functions lie in
 
 @node X.509 certificate functions
 @section @acronym{X.509} Certificate Functions
-@anchor{sec:x509api}
+@anchor{sec-x509api}
 @cindex @acronym{X.509} Functions
 
 The following functions are to be used for @acronym{X.509} certificate handling.
@@ -42,7 +42,7 @@ lie in @file{gnutls/extra.h}.
 @node OpenPGP functions
 @section @acronym{OpenPGP} Functions
 @cindex @acronym{OpenPGP} functions
-@anchor{sec:openpgpapi}
+@anchor{sec-openpgpapi}
 
 The following functions are to be used for @acronym{OpenPGP}
 certificate handling.  Their prototypes lie in
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 27a4ff73ad..e8c6a0bab3 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -223,7 +223,7 @@ if called after a successful @ref{gnutls_handshake}.
 
 @node Verifying peer's certificate
 @subsection Verifying Peer's Certificate
-@anchor{ex:verify}
+@anchor{ex-verify}
 
 A @acronym{TLS} session is not secure just after the handshake
 procedure has finished.  It must be considered secure, only after the
@@ -252,7 +252,7 @@ certificate selection callback.
 
 @node Client using a PKCS #11 token with TLS
 @subsection Using a @acronym{PKCS #11} token with TLS
-@anchor{ex:pkcs11-client}
+@anchor{ex-pkcs11-client}
 
 This example will demonstrate how to load keys and certificates
 from a @acronym{PKCS} #11 token, and use it with a TLS connection.
@@ -262,7 +262,7 @@ from a @acronym{PKCS} #11 token, and use it with a TLS connection.
 
 @node Client with Resume capability example
 @subsection Client with Resume Capability Example
-@anchor{ex:resume-client}
+@anchor{ex-resume-client}
 
 This is a modification of the simple client example. Here we
 demonstrate the use of session resumption. The client tries to connect
@@ -368,7 +368,7 @@ current session.
 
 @node X.509 certificate parsing example
 @subsection @acronym{X.509} Certificate Parsing Example
-@anchor{ex:x509-info}
+@anchor{ex-x509-info}
 
 To demonstrate the @acronym{X.509} parsing capabilities an example program is
 listed below.  That program reads the peer's certificate, and prints
@@ -378,7 +378,7 @@ information about it.
 
 @node Certificate request generation
 @subsection Certificate Request Generation
-@anchor{ex:crq}
+@anchor{ex-crq}
 
 The following example is about generating a certificate request, and a
 private key. A certificate request can be later be processed by a CA,
@@ -388,7 +388,7 @@ which should return a signed certificate.
 
 @node PKCS #12 structure generation
 @subsection @acronym{PKCS} #12 Structure Generation
-@anchor{ex:pkcs12}
+@anchor{ex-pkcs12}
 
 The following example is about generating a @acronym{PKCS} #12
 structure.
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index d3de6b367c..3b62a3c6a8 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -570,7 +570,7 @@ resuming} is a feature of the @acronym{TLS} protocol which allows a
 client to connect to a server, after a successful handshake, without
 the expensive calculations.  This is achieved by using the previously
 established keys. @acronym{GnuTLS} supports this feature, and the
-example (@pxref{ex:resume-client}) illustrates a typical use of it.
+example (@ref{ex-resume-client}) illustrates a typical use of it.
 
 Keep in mind that sessions are expired after some time, for security
 reasons, thus it may be normal for a server not to resume a session
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index 6c783bef2f..cc55aa0c25 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -180,8 +180,8 @@ should allocate and free memory using the functions shown below.
 
 @itemize
 
-@item @ref{gnutls_malloc}
+@item @code{gnutls_malloc}
 
-@item @ref{gnutls_free}
+@item @code{gnutls_free}
 
 @end itemize
diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi
index cdbd82885c..8bc3c30fa4 100644
--- a/doc/cha-programs.texi
+++ b/doc/cha-programs.texi
@@ -865,7 +865,7 @@ The @file{p11tool} is a program that helps with accessing tokens
 and security modules that support the PKCS #11 API. It requires
 the individual PKCS #11 modules to be loaded either with the
 @code{--provider} option, or by setting up the GnuTLS configuration
-file for PKCS #11 as in @ref{sec:pkcs11}.
+file for PKCS #11 as in @ref{sec-pkcs11}.
 
 @verbatim
 p11tool help
diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc
index 13a37bd3b5..5d2d609699 100755
--- a/doc/scripts/gdoc
+++ b/doc/scripts/gdoc
@@ -1,12 +1,14 @@
 #!/usr/bin/perl
 
 ## Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Simon Josefsson
-##                    added -texinfo, -listfunc, -pkg-name
+##                    added -texinfo, -listfunc
 ##                    man page revamp
 ##                    various improvements
-## Copyright (c) 2001, 2002 Nikos Mavrogiannopoulos
-##                    added -tex
+## Copyright (c) 2001, 2002, 2013 Nikos Mavrogiannopoulos
+##                    added -tex, -pkg-site
 ## Copyright (c) 1998 Michael Zucchi
+## Copyright (c) 2013 Adam Sampson
+##                    made highlighting not depend on hash order, for Perl 5.18
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -27,7 +29,7 @@
 # usage:
 # gdoc [ -docbook | -html | -text | -man | -tex | -texinfo | -listfunc ]
 #      [ -sourceversion verno ] [ -include file | -includefuncprefix ]
-#      [ -bugsto address ] [ -pkg-name packagename ]
+#      [ -bugsto address ] [ -pkg-site website ]
 #      [ -seeinfo infonode ] [ -copyright notice ] [ -verbatimcopying ]
 #      [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
 #
@@ -51,9 +53,9 @@
 #       For man pages, include a section about reporting bugs and mention
 #       the given e-mail address, e.g 'bug-libidn@gnu.org'.
 #
-#  -pkg-name packagename
+#  -pkg-site web-site
 #       For man pages when -bugsto is used, also include help URLs to the
-#       the project's home page.  For example, "GNU Libidn".
+#       the project's home page. 
 #
 #  -seeinfo infonode
 #       For man pages, include a section that point to an info manual
@@ -132,63 +134,73 @@
 use POSIX qw(strftime);
 
 # match expressions used to find embedded type information
-$type_constant = "((?<!\")\\\%(\\w+))";
-$type_func = "(\\w+\\(\\))";
-$type_param = "\\\@(\\w+)";
-$type_struct = "\\\#(\\w+)";
-$type_env = "(\\\$\\w+)";
+$type_constant = '(?<!\%)\%([A-Za-z0-9_]+)';
+$type_func = "([A-Za-z0-9_]+\\(\\))";
+$type_param = '(?<!\@)\@([A-Za-z0-9_]+)\s*';
+$type_struct = "\\\#([A-Za-z0-9_]+)";
+$type_env = "(\\\$[A-Za-z0-9_]+)";
 
 
 # Output conversion substitutions.
 #  One for each output format
 
 # these work fairly well
-%highlights_html = ( $type_constant, "<i>\$2</i>",
-		     $type_func, "<b>\$1</b>",
-		     $type_struct, "<i>\$1</i>",
-		     $type_param, "<tt><b>\$1</b></tt>" );
+@highlights_html = ( [$type_constant, '"<i>$1</i>"'],
+		     [$type_func, '"<b>$1</b>"'],
+		     [$type_struct, '"<i>$1</i>"'],
+		     [$type_param, '" <tt><b>$1</b></tt> "'],
+		     ['\%\%', '"\%"']
+		     );
 $blankline_html = "<p>";
 
-%highlights_texinfo = ( $type_constant, "\\\@code{\$2}",
-			$type_func, "\\\@code{\$1}",
-			$type_struct, "\\\@code{\$1}",
-			$type_param, "\\\@code{\$1}" );
+@highlights_texinfo = ( [$type_param, '" \@code{$1} "'],
+			[$type_constant, '"\@code{$1} "'],
+			[$type_func, '"\@code{$1} "'],
+			[$type_struct, '"\@code{$1} "'],
+			['\%\%', '"\%"'],
+			 );
 $blankline_texinfo = "";
 
-%highlights_tex = ( $type_constant, "{\\\\it \$2}",
-		     $type_func, "{\\\\bf \$1}",
-		     $type_struct, "{\\\\it \$1}",
-		     $type_param, "{\\\\bf \$1}" );
+@highlights_tex = ( [$type_param, '" {\\\bf $1} "'],
+		[$type_constant, '"{\\\it $1}"'],
+		[$type_func, '"{\\\bf $1}"'],
+		[$type_struct, '"{\\\it $1}"'],
+		['\@\@', '"\@"']
+		      );
 $blankline_tex = "\\\\";
 
 # sgml, docbook format
-%highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$2</replaceable>",
-		     $type_func, "<function>\$1</function>",
-		     $type_struct, "<structname>\$1</structname>",
-		     $type_env, "<envar>\$1</envar>",
-		     $type_param, "<parameter>\$1</parameter>" );
+@highlights_sgml = ( [$type_constant, '"<replaceable class=\"option\">$1</replaceable>"'],
+		     [$type_func, '"<function>$1</function>"'],
+		     [$type_struct, '"<structname>$1</structname>"'],
+		     [$type_env, '"<envar>$1</envar>"'],
+		     [$type_param, '" <parameter>$1</parameter> "'] );
 $blankline_sgml = "</para><para>\n";
 
 # these are pretty rough
-%highlights_man = ( $type_constant, "\\\\fB\$2\\\\fP",
-		    $type_func, "\\\\fB\$1\\\\fP",
-		    $type_struct, "\\\\fB\$1\\\\fP",
-		    $type_param, "\\\\fI\$1\\\\fP" );
+@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
-%highlights_text = ( $type_constant, "\$2",
-		     $type_func, "\$1",
-		     $type_struct, "\$1",
-		     $type_param, "\$1" );
+@highlights_text = ( [$type_constant, '"$1"'],
+		     [$type_func, '"$1"'],
+		     [$type_struct, '"$1"'],
+		     [$type_param, '"$1 "'],
+		     ['\%\%', '"\%"'],
+		     ['\@\@', '"\@"']);
 $blankline_text = "";
-
+my $lineprefix = "";
 
 sub usage {
     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex | -texinfo  -listfunc ]\n";
     print "         [ -sourceversion verno ] [ -include file | -includefuncprefix ]\n";
     print "         [ -bugsto address ] [ -seeinfo infonode ] [ -copyright notice]\n";
-    print "         [ -verbatimcopying ] [ -pkg-name packagename ]\n";
+    print "         [ -verbatimcopying ] [ -pkg-site website ]\n";
     print "         [ -function funcname [ -function funcname ...] ]\n";
     print "         c source file(s) > outputfile\n";
     exit 1;
@@ -201,7 +213,7 @@ if ($#ARGV==-1) {
 
 $verbose = 0;
 $output_mode = "man";
-%highlights = %highlights_man;
+@highlights = @highlights_man;
 $blankline = $blankline_man;
 $modulename = "API Documentation";
 $sourceversion = strftime "%Y-%m-%d", localtime;
@@ -210,27 +222,27 @@ while ($ARGV[0] =~ m/^-(.*)/) {
     $cmd = shift @ARGV;
     if ($cmd eq "-html") {
 	$output_mode = "html";
-	%highlights = %highlights_html;
+	@highlights = @highlights_html;
 	$blankline = $blankline_html;
     } elsif ($cmd eq "-man") {
 	$output_mode = "man";
-	%highlights = %highlights_man;
+	@highlights = @highlights_man;
 	$blankline = $blankline_man;
     } elsif ($cmd eq "-tex") {
 	$output_mode = "tex";
-	%highlights = %highlights_tex;
+	@highlights = @highlights_tex;
 	$blankline = $blankline_tex;
     } elsif ($cmd eq "-texinfo") {
 	$output_mode = "texinfo";
-	%highlights = %highlights_texinfo;
+	@highlights = @highlights_texinfo;
 	$blankline = $blankline_texinfo;
     } elsif ($cmd eq "-text") {
 	$output_mode = "text";
-	%highlights = %highlights_text;
+	@highlights = @highlights_text;
 	$blankline = $blankline_text;
     } elsif ($cmd eq "-docbook") {
 	$output_mode = "sgml";
-	%highlights = %highlights_sgml;
+	@highlights = @highlights_sgml;
 	$blankline = $blankline_sgml;
     } elsif ($cmd eq "-listfunc") {
 	$output_mode = "listfunc";
@@ -244,8 +256,8 @@ while ($ARGV[0] =~ m/^-(.*)/) {
 	$includefuncprefix = 1;
     } elsif ($cmd eq "-bugsto") {
 	$bugsto = shift @ARGV;
-    } elsif ($cmd eq "-pkg-name") {
-	$pkgname = shift @ARGV;
+    } elsif ($cmd eq "-pkg-site") {
+	$pkgsite = shift @ARGV;
     } elsif ($cmd eq "-copyright") {
 	$copyright = shift @ARGV;
     } elsif ($cmd eq "-verbatimcopying") {
@@ -270,6 +282,8 @@ sub dump_section {
     my $name = shift @_;
     my $contents = join "\n", @_;
 
+    $name = " $name";
+
     if ($name =~ m/$type_constant/) {
 	$name = $1;
 #	print STDERR "constant section '$1' = '$contents'\n";
@@ -280,6 +294,7 @@ sub dump_section {
 	$parameters{$name} = $contents;
     } else {
 #	print STDERR "other section '$name' = '$contents'\n";
+	$name =~ tr/ //d;
 	$sections{$name} = $contents;
 	push @sectionlist, $name;
     }
@@ -296,35 +311,15 @@ sub dump_section {
 #  sections => %descriont descriptions
 #  
 
-sub repstr {
-    $pattern = shift;
-    $repl = shift;
-    $match1 = shift;
-    $match2 = shift;
-    $match3 = shift;
-    $match4 = shift;
-
-    $output = $repl;
-    $output =~ s,\$1,$match1,g;
-    $output =~ s,\$2,$match2,g;
-    $output =~ s,\$3,$match3,g;
-    $output =~ s,\$4,$match4,g;
-
-    eval "\$return = qq/$output/";
-
-#    print "pattern $pattern matched 1=$match1 2=$match2 3=$match3 4=$match4 replace $repl yielded $output interpolated $return\n";
-
-    $return;
-}
-
 sub just_highlight {
     my $contents = join "\n", @_;
     my $line;
     my $ret = "";
 
-    foreach $pattern (keys %highlights) {
-#	print "scanning pattern $pattern ($highlights{$pattern})\n";
-	$contents =~ s:$pattern:repstr($pattern, $highlights{$pattern}, $1, $2, $3, $4):gse;
+    foreach $highlight (@highlights) {
+	my ($pattern, $replace) = @$highlight;
+	#print "scanning pattern $pattern ($replace)\n";
+	$contents =~ s/$pattern/$replace/gees;
     }
     foreach $line (split "\n", $contents) {
 	if ($line eq ""){
@@ -370,13 +365,45 @@ sub output_texinfo {
 	}
     }
     foreach $section (@{$args{'sectionlist'}}) {
+	$section =~ s/\@//g;
 	print "\n\@strong{$section:} " if $section ne $section_default;
-	$args{'sections'}{$section} =~ s:([{}]):\@\1:gs;
+	$args{'sections'}{$section} =~ s:([{}]):\@$1:gs;
 	output_highlight($args{'sections'}{$section});
     }
     print "\@end deftypefun\n\n";
 }
 
+sub output_enum_texinfo {
+    my %args = %{$_[0]};
+    my ($parameter, $section);
+    my $count;
+    my $name = $args{'enum'};
+    my $param;
+    my $param2;
+    my $sec;
+    my $check;
+    my $type;
+
+    print "\n\@c $name\n";
+    print "\@table \@code\n";
+
+    $check=0;
+    foreach $parameter (@{$args{'parameterlist'}}) {
+        $param1 = $parameter;
+	$param1 =~ s/_/_\@-/g;
+
+	$check = 1;
+	print "\@item ".$param1."\n";
+#	print "\n";
+
+        $param2 = $args{'parameters'}{$parameter};
+	$out = just_highlight($param2);
+	chomp $out;
+	print $out . "\n";
+    }
+    print "\@end table\n";
+}
+
 # output in html
 sub output_html {
     my %args = %{$_[0]};
@@ -428,7 +455,9 @@ sub output_tex {
 
     $func =~ s/_/\\_/g;
 
-    print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
+    print "\n\n\\begin{function}\n";
+    print "\\functionTitle{". $func . "}\n";
+    print "\\index{". $func . "}\n";
 
     $type = $args{'functiontype'};
     $type =~ s/_/\\_/g;
@@ -451,9 +480,8 @@ sub output_tex {
     }
     print ")\n";
 
-    print "\n{\\large{Arguments}}\n";
+    print "\n\\begin{functionArguments}\n";
 
-    print "\\begin{itemize}\n";
     $check=0;
     foreach $parameter (@{$args{'parameterlist'}}) {
         $param1 = $args{'parametertypes'}{$parameter};
@@ -462,11 +490,12 @@ sub output_tex {
 	$param2 =~ s/_/\\_/g;
 
 	$check = 1;
-	print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
+	print "\\functionArgument {\\it ".$param1."} {\\bf ".$param2."}: \n";
 #	print "\n";
 
 	$param3 = $args{'parameters'}{$parameter};
-	$param3 =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
+	$param3 =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+	$param3 =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
 
 	$out = just_highlight($param3);
 	$out =~ s/_/\\_/g;
@@ -475,31 +504,72 @@ sub output_tex {
     if ($check==0) {
 	print "\\item void\n";
     }
-    print "\\end{itemize}\n";
+    print "\\end{functionArguments}\n";
 
     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\\begin{function${sec}}\n";
+	$out = $args{'sections'}{$section};
+
+	$out =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+	$out =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
+	$out =~ s/\@([a-zA-Z\_]+)/{\\bf $1}/g;
+	$out =~ s/_/\\_\\-/g;
+        $out =~ s/\$/\\\$/g;
+	$out =~ s/#/\\#/g;
+	$out =~ s/\n\n/\n/g;
+	$out =~ s/\\:/:/g;
+	$out =~ s/\-\>/\$\\rightarrow\$/g;
+	$out =~ s/([0-9]+)\^([0-9]+)/\$\{$1\}\^\{$2\}\$/g;
+
+	print $out;
+	print "\\end{function${sec}}\n";
+    }
+    print "\\end{function}\n\n";
+}
 
-	print "\n{\\large{$sec}}\\\\\n";
-	print "\\begin{rmfamily}\n";
+sub output_enum_tex {
+    my %args = %{$_[0]};
+    my ($parameter, $section);
+    my $count;
+    my $name = $args{'enum'};
+    my $param;
+    my $param2;
+    my $sec;
+    my $check;
+    my $type;
 
-	$sec = $args{'sections'}{$section};
-	$sec =~ s/\\:/:/g;
-	$sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
-	$sec =~ s/->/\$\\rightarrow\$/g;
-	$sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
+    print "\n\n\\begin{enum}\n";
+    $name =~ s/_/\\_/g;
+    print "\\enumTitle{". $name . "}\n";
+    print "\\index{". $name . "}\n";
 
-	$out = just_highlight($sec);
-	$out =~ s/_/\\_/g;
+    print "\n\\begin{enumList}\n";
 
-	print $out;
-	print "\\end{rmfamily}\n";
+    $check=0;
+    foreach $parameter (@{$args{'parameterlist'}}) {
+        $param1 = $parameter;
+	$param1 =~ s/_/\\_\\-/g;
+
+	$check = 1;
+	print "\\enumElement{".$param1."}{";
+#	print "\n";
+
+        $param2 = $args{'parameters'}{$parameter};
+	$param2 =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+	$param2 =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
+	$out = just_highlight($param2);
+	$out =~ s/_/\\_/g;
+	chomp $out;
+	print $out . "}\n";
     }
-    print "\n";
-}
+    print "\\end{enumList}\n";
 
+    print "\\end{enum}\n\n";
+}
 
 # output in sgml DocBook
 sub output_sgml {
@@ -639,11 +709,13 @@ sub output_man {
     if ($args{'bugsto'}) {
 	print ".SH \"REPORTING BUGS\"\n";
 	print "Report bugs to <". $args{'bugsto'} . ">.\n";
-	if ($args{'pkgname'}) {
-	    print $args{'pkgname'} . " home page: " .
-		"http://www.gnu.org/software/" . $args{'module'} . "/\n";
+        #print ".br\n";
+	#print "General guidelines for reporting bugs: http://www.gnu.org/gethelp/\n";
+        print ".br\n";
+	if ($args{'pkgsite'}) {
+	    print "Home page: " . $args{'pkgsite'} . "\n";
 	}
-	print "General help using GNU software: http://www.gnu.org/gethelp/\n";
+	print "\n";
     }
 
     if ($args{'copyright'}) {
@@ -661,15 +733,14 @@ sub output_man {
 	print ".SH \"SEE ALSO\"\n";
 	print "The full documentation for\n";
 	print ".B " . $args{'module'} . "\n";
-	print "is maintained as a Texinfo manual.  If the\n";
-	print ".B info\n";
-	print "and\n";
-	print ".B " . $args{'module'} . "\n";
-	print "programs are properly installed at your site, the command\n";
-	print ".IP\n";
-	print ".B info " . $args{'seeinfo'} . "\n";
+	print "is maintained as a Texinfo manual.\n";
+	if ($args{'pkgsite'}) {
+		print "If the /usr/share/doc/". $args{'module'} . "/\n";
+		print "directory does not contain the HTML form visit\n";
+		print ".B\n";
+		print ".IP " . $args{'pkgsite'} . "/manual/\n";
+	}
 	print ".PP\n";
-	print "should give you access to the complete manual.\n";
     }
 }
 
@@ -705,6 +776,10 @@ sub output_function {
     eval "output_".$output_mode."(\@_);";
 }
 
+sub output_enum {
+    eval "output_enum_".$output_mode."(\@_);";
+}
+
 
 ##
 # takes a function prototype and spits out all the details
@@ -744,7 +819,7 @@ sub dump_function {
 #	    print STDERR " :> @args\n";
 	    $type = join " ", @args;
 
-	    if ($parameters{$param} eq "" && $param != "void") {
+	    if ((!defined($parameters{$param}) || $parameters{$param} eq "") && $param ne "void") {
 		$parameters{$param} = "-- undescribed --";
 		print STDERR "warning: $lineno: Function parameter '$param' not described in '$function_name'\n";
 	    }
@@ -766,7 +841,7 @@ sub dump_function {
 			 'include' => $include,
 			 'includefuncprefix' => $includefuncprefix,
 			 'bugsto' => $bugsto,
-			 'pkgname' => $pkgname,
+			 'pkgsite' => $pkgsite,
 			 'copyright' => $copyright,
 			 'verbatimcopying' => $verbatimcopying,
 			 'seeinfo' => $seeinfo,
@@ -781,6 +856,56 @@ sub dump_function {
     }
 }
 
+sub dump_enum {
+    my $prototype = shift @_;
+
+    if (($prototype =~ m/^\s*typedef\s+enum\s*[a-zA-Z0-9_~:]*\s*\{([\-a-zA-Z0-9_~=,:\s\(\)\<]+)\s*\}\s*([a-zA-Z0-9_]+);.*/)) {
+#        || $prototype =~ m/^\s*enum\s+([a-zA-Z0-9_~:]+).*/) {
+        $args = $1;
+	$name = $2;
+
+	foreach $arg (split ',', $args) {
+	    # strip leading/trailing spaces
+	    $arg =~ s/^\s*//;
+	    $arg =~ s/\s*$//;
+	    $arg =~ s/([A-Za-z0-9_]+)\s*=.*/$1/g;
+#	    print STDERR "SCAN ARG: '$arg'\n";
+
+            next if $arg eq '';
+	    if ((!defined($parameters{$arg}) || $parameters{$arg} eq "")) {
+		$parameters{$arg} = "-- undescribed --";
+		print STDERR "warning: $lineno: Enumeration parameter '$arg' not described in '$name'\n";
+	    }
+
+	    push @parameterlist, $arg;
+
+#	    print STDERR "param = '$arg'\n";
+	}
+    } else {
+#	print STDERR "warning: $lineno: Cannot understand enumeration: '$prototype'\n";
+	return;
+    }
+
+    output_enum({'enum' => $name,
+			 'module' => $modulename,
+			 'sourceversion' => $sourceversion,
+			 'include' => $include,
+			 'includefuncprefix' => $includefuncprefix,
+			 'bugsto' => $bugsto,
+			 'pkgsite' => $pkgsite,
+			 'copyright' => $copyright,
+			 'verbatimcopying' => $verbatimcopying,
+			 'seeinfo' => $seeinfo,
+			 'functiontype' => $return_type,
+			 'parameterlist' => \@parameterlist,
+			 'parameters' => \%parameters,
+			 'parametertypes' => \%parametertypes,
+			 'sectionlist' => \@sectionlist,
+			 'sections' => \%sections,
+			 'purpose' => $function_purpose
+			 });
+}
+
 ######################################################################
 # main
 # states
@@ -797,7 +922,7 @@ $doc_start = "^/\\*\\*\$";
 $doc_end = "\\*/";
 $doc_com = "\\s*\\*\\s*";
 $doc_func = $doc_com."(\\w+):?";
-$doc_sect = $doc_com."([".$doc_special."[:upper:]][\\w ]+):\\s*(.*)";
+$doc_sect = $doc_com."([".$doc_special."[:upper:]][\\w]+):\\s*(.*)";
 $doc_content = $doc_com."(.*)";
 
 %constants = ();
@@ -809,25 +934,30 @@ $doc_content = $doc_com."(.*)";
 $contents = "";
 $section_default = "Description";	# default section
 $section = $section_default;
+$enum = 0;
 
 $lineno = 0;
+
 foreach $file (@ARGV) {
     if (!open(IN,"<$file")) {
 	print STDERR "Error: Cannot open file $file\n";
 	next;
     }
-    while (<IN>) {
+    while ($line = <IN>) {
 	$lineno++;
 
 	if ($state == 0) {
-	    if (/$doc_start/o) {
+	    if ($line =~ /$doc_start/o) {
 		$state = 1;		# next line is always the function name
+#	    print STDERR "XXX: start of doc comment\n";
 	    }
 	} elsif ($state == 1) {	# this line is the function name (always)
-	    if (/$doc_func/o) {
+	    if ($line =~ /$doc_func/o) {
 		$function = $1;
 		$state = 2;
-		if (/-\s*(.*)/) {
+#	    print STDERR "XXX: start of doc comment, looking for prototype\n";
+
+		if ($line =~ /-\s*(.*)/) {
 		    $function_purpose = $1;
 		} else {
 		    $function_purpose = "";
@@ -841,11 +971,11 @@ foreach $file (@ARGV) {
 		$state = 0;
 	    }
 	} elsif ($state == 2) {	# look for head: lines, and include content
-	    if (/$doc_sect/o) {
+	    if ($line =~ /$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;
 
-		if ($contents ne "") {
+		if ($contents ne '') {
 		    dump_section($section, $contents);
 		    $section = $section_default;
 		}
@@ -855,7 +985,7 @@ foreach $file (@ARGV) {
 		    $contents .= "\n";
 		}
 		$section = $newsection;
-	    } elsif (/$doc_end/) {
+	    } elsif ($line =~ /$doc_end/) {
 
 		if ($contents ne "") {
 		    dump_section($section, $contents);
@@ -863,13 +993,12 @@ foreach $file (@ARGV) {
 		    $contents = "";
 		}
 
-#	    print STDERR "end of doc comment, looking for prototype\n";
-		$prototype = "";
+		$prototype = '';
 		$state = 3;
-	    } elsif (/$doc_content/) {
+	    } elsif ($line =~ /$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" && $section =~ m/^@/) {
+		if ($1 eq '' && $section =~ m/^@/) {
 		    dump_section($section, $contents);
 		    $section = $section_default;
 		    $contents = "";
@@ -881,16 +1010,25 @@ foreach $file (@ARGV) {
 		print STDERR "warning: $lineno: Bad line: $_";
 	    }
 	} elsif ($state == 3) {	# scanning for function { (end of prototype)
-	    if (m#\s*/\*\s+MACDOC\s*#io) {
+	    if ($line =~ /([a-zA-Z\s]+)enum(.*)$/) {
+	        $enum = 1;
+	    }
+
+	    if ($line =~ m#\s*/\*\s+MACDOC\s*#io) {
 	      # do nothing
 	    }
-	    elsif (/([^\{]*)/) {
+	    elsif ($enum == 1 && $line =~ /(\s*\{).*/) {
+		$prototype = "typedef enum {";
+	    }
+	    elsif ($line =~ /([^\{]*)/) {
 		$prototype .= $1;
 	    }
-	    if (/\{/) {
+
+	    if ($enum == 0 && $line =~ /;/) {
 		$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
 		$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
 		$prototype =~ s@^ +@@gos; # strip leading spaces
+
 		dump_function($prototype);
 
 		$function = "";
@@ -901,9 +1039,31 @@ foreach $file (@ARGV) {
 		%sections = ();
 		@sectionlist = ();
 		$prototype = "";
+		$enum = 0;
 
 		$state = 0;
 	    }
+	    elsif ($enum == 1 && $line =~ /\}/) {
+		$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
+		$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
+		$prototype =~ s@^ +@@gos; # strip leading spaces
+
+		dump_enum($prototype);
+
+		$function = "";
+		%constants = ();
+		%parameters = ();
+		%parametertypes = ();
+		@parameterlist = ();
+		%sections = ();
+		@sectionlist = ();
+		$prototype = "";
+		$enum = 0;
+
+		$state = 0;
+	    }
+    
 	}
     }
+
 }
diff --git a/doc/scripts/sort2.pl b/doc/scripts/sort2.pl
index a4c71ef05e..bd9fed4594 100755
--- a/doc/scripts/sort2.pl
+++ b/doc/scripts/sort2.pl
@@ -1,15 +1,41 @@
 #!/usr/bin/perl
 
+# Copyright (C) 2004-2012 Free Software Foundation, Inc.
+#
+# This file is part of GnuTLS.
+#
+# This file is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This file is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this file; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
 sub key_of_record {
   local($record) = @_;
 
   # Split record into lines:
   my @lines = split /\n/, $record;
+  my $max = @lines;
+  if ($max > 5) {
+    $max = 5;
+  }
+  
+  if ($max < 2) {
+    return "";
+  }
 
   my ($i) = 1;
   my ($key) = $lines[$i];
 
-  while( !($key =~ /^\@deftypefun/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
+  while( !($key =~ /^\@deftypefun/) && ($i < $max)) { $i=$i+1; $key = $lines[$i]; }
 
   $key = $1 if $key =~ /^\@deftypefun {.*} {(.*)}/;
 
@@ -18,7 +44,7 @@ sub key_of_record {
   return $key;
 }
 
-$/="@end deftypefun";          # Records are separated by blank lines.
+$/="\@end deftypefun";          # Records are separated by blank lines.
 @records = <>;  # Read in whole file, one record per array element.
 
 @records = sort { key_of_record($a) cmp key_of_record($b) } @records;