From 6a624468643e98d3b5fed716b6422f2ef4e0fcfd Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Wed, 13 Nov 2013 13:34:51 +0100 Subject: updated gdoc from gnutls --- doc/gdoc | 365 +++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 261 insertions(+), 104 deletions(-) (limited to 'doc/gdoc') diff --git a/doc/gdoc b/doc/gdoc index 975a85d..e3db762 100755 --- a/doc/gdoc +++ b/doc/gdoc @@ -1,15 +1,16 @@ -eval '(exit $?0)' && eval 'exec perl -S "$0" ${1+"$@"}' - & eval 'exec perl -S "$0" $argv:q' +eval '(exit $?0)' && eval 'exec perl "$0" ${1+"$@"}' + & eval 'exec perl "$0" $argv:q' if 0; -# Generate documentation from source code. -## Copyright (c) 2002-2011 Simon Josefsson +## Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Simon Josefsson ## added -texinfo, -listfunc, -pkg-name ## man page revamp ## various improvements ## Copyright (c) 2001, 2002 Nikos Mavrogiannopoulos ## added -tex ## 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 @@ -135,57 +136,59 @@ eval '(exit $?0)' && eval 'exec perl -S "$0" ${1+"$@"}' 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, "\$1", - $type_func, "\$1", - $type_struct, "\$1", - $type_param, "\$1" ); +@highlights_html = ( [$type_constant, '"$1"'], + [$type_func, '"$1"'], + [$type_struct, '"$1"'], + [$type_param, '" $1 "'] ); $blankline_html = "

"; -%highlights_texinfo = ( $type_constant, "\\\@code{\$1}", - $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 \$1}", - $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, "\$1", - $type_func, "\$1", - $type_struct, "\$1", - $type_env, "\$1", - $type_param, "\$1" ); +@highlights_sgml = ( [$type_constant, '"$1"'], + [$type_func, '"$1"'], + [$type_struct, '"$1"'], + [$type_env, '"$1"'], + [$type_param, '" $1 "'] ); $blankline_sgml = "\n"; # these are pretty rough -%highlights_man = ( $type_constant, "\\\\fB\$1\\\\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, "\$1", - $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"; @@ -204,7 +207,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; @@ -213,27 +216,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"; @@ -273,6 +276,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"; @@ -283,6 +288,7 @@ sub dump_section { $parameters{$name} = $contents; } else { # print STDERR "other section '$name' = '$contents'\n"; + $name =~ tr/ //d; $sections{$name} = $contents; push @sectionlist, $name; } @@ -299,35 +305,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 ""){ @@ -373,13 +359,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]}; @@ -431,7 +449,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; @@ -454,9 +474,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}; @@ -465,11 +484,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; @@ -478,31 +498,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 "\n{\\large{$sec}}\\\\\n"; - print "\\begin{rmfamily}\n"; + print $out; + print "\\end{function${sec}}\n"; + } + print "\\end{function}\n\n"; +} - $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; +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; - $out = just_highlight($sec); - $out =~ s/_/\\_/g; + print "\n\n\\begin{enum}\n"; + $name =~ s/_/\\_/g; + print "\\enumTitle{". $name . "}\n"; + print "\\index{". $name . "}\n"; - print $out; - print "\\end{rmfamily}\n"; + print "\n\\begin{enumList}\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 { @@ -642,11 +703,14 @@ sub output_man { if ($args{'bugsto'}) { print ".SH \"REPORTING BUGS\"\n"; print "Report bugs to <". $args{'bugsto'} . ">.\n"; + print ".br\n"; + print "General guidelines for reporting bugs: http://www.gnu.org/gethelp/\n"; + print ".br\n"; if ($args{'pkgname'}) { print $args{'pkgname'} . " home page: " . "http://www.gnu.org/software/" . $args{'module'} . "/\n"; } - print "General help using GNU software: http://www.gnu.org/gethelp/\n"; + print "\n"; } if ($args{'copyright'}) { @@ -673,6 +737,10 @@ sub output_man { print ".B info " . $args{'seeinfo'} . "\n"; print ".PP\n"; print "should give you access to the complete manual.\n"; + print "As an alternative you may obtain the manual from:\n"; + print ".IP\n"; + print ".B http://www.gnu.org/software/" . $args{'module'} . "/manual/\n"; + print ".PP\n"; } } @@ -708,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 @@ -747,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"; } @@ -784,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, + 'pkgname' => $pkgname, + 'copyright' => $copyright, + 'verbatimcopying' => $verbatimcopying, + 'seeinfo' => $seeinfo, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameters' => \%parameters, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $function_purpose + }); +} + ###################################################################### # main # states @@ -800,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 = (); @@ -812,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 () { + while ($line = ) { $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 = ""; @@ -844,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; } @@ -858,7 +985,7 @@ foreach $file (@ARGV) { $contents .= "\n"; } $section = $newsection; - } elsif (/$doc_end/) { + } elsif ($line =~ /$doc_end/) { if ($contents ne "") { dump_section($section, $contents); @@ -866,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 = ""; @@ -884,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 = ""; @@ -904,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; + } + } } + } -- cgit v1.2.3