3 ## Copyright (c) 2002, 2003 Simon Josefsson ##
4 ## added -texinfo, -listfunc ##
6 ## various improvements ##
7 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8 ## hacked to allow -tex option --nmav ##
10 ## This software falls under the GNU Public License. Please read ##
11 ## the COPYING file for more information ##
14 # This will read a 'c' file and scan for embedded comments in the
15 # style of gnome comments (+minor extensions - see below).
17 # This program is modified by Nikos Mavroyanopoulos, for the gnutls
20 # Note: This only supports 'c'.
23 # gdoc [ -docbook | -html | -text | -man | -tex | -texinfo | -listfunc ]
24 # [ -sourceversion verno ] [ -includefuncprefix ] [ -bugsto address ]
25 # [ -seeinfo infonode ] [ -copyright notice ] [ -verbatimcopying ]
26 # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
28 # Set output format using one of -docbook, -html, -text, -man, -tex,
29 # -texinfo, or -listfunc. Default is man.
32 # Version number for source code, e.g. '1.0.4'. Used in 'man' headers.
33 # Defaults to using current date.
36 # For man pages, generate a #include <FILE.h> based on the function
37 # prefix. For example, a function gss_init_sec_context will generate
38 # an include statement of #include <gss.h>.
41 # For man pages, include a section about reporting bugs and mention
42 # the given e-mail address, e.g 'bug-libidn@gnu.org'.
45 # For man pages, include a section that point to an info manual
46 # for more information.
49 # For man pages, include a copyright section with the given
50 # notice after a preamble. Use, e.g., '2002, 2003 Simon Josefsson'.
53 # For man pages, and when the -copyright parameter is used,
54 # add a licensing statement that say verbatim copying is permitted.
57 # If set, then only generate documentation for the given function(s). All
58 # other functions are ignored.
60 # c files - list of 'c' files to process
62 # All output goes to stdout, with errors to stderr.
66 # In the following table, (...)? signifies optional structure.
67 # (...)* signifies 0 or more structure elements
69 # * function_name(:)? (- short description)?
70 # (* @parameterx: (description of parameter x)?)*
72 # * (Description:)? (Description of function)?
73 # * (Section header: (section description)? )*
76 # So .. the trivial example would be:
82 # If the Description: header tag is ommitted, then there must be a blank line
83 # after the last parameter specification.
86 # * my_function - does my stuff
87 # * @my_arg: its mine damnit
89 # * Does my stuff explained.
94 # * my_function - does my stuff
95 # * @my_arg: its mine damnit
96 # * Description: Does my stuff explained.
100 # All descriptions can be multiline, apart from the short function description.
102 # All descriptive text is further processed, scanning for the following special
103 # patterns, which are highlighted appropriately.
105 # 'funcname()' - function
106 # '$ENVVAR' - environmental variable
107 # '&struct_name' - name of a structure
108 # '@parameter' - name of a parameter
109 # '%CONST' - name of a constant.
112 # Extensions for LaTeX:
114 # 1. the symbol '->' will be replaced with a rightarrow
115 # 2. x^y with ${x}^{y}$.
118 use POSIX
qw(strftime);
120 # match expressions used to find embedded type information
121 $type_constant = "\\\%(\\w+)";
122 $type_func = "(\\w+\\(\\))";
123 $type_param = "\\\@(\\w+)";
124 $type_struct = "\\\&(\\w+)";
125 $type_env = "(\\\$\\w+)";
128 # Output conversion substitutions.
129 # One for each output format
131 # these work fairly well
132 %highlights_html = ( $type_constant, "<i>\$1</i>",
133 $type_func, "<b>\$1</b>",
134 $type_struct, "<i>\$1</i>",
135 $type_param, "<tt><b>\$1</b></tt>" );
136 $blankline_html = "<p>";
138 %highlights_texinfo = ( $type_constant, "\\\@var{\$1}",
139 $type_func, "\\\@code{\$1}",
140 $type_struct, "\\\@code{\$1}",
141 $type_param, "\\\@code{\$1}" );
142 $blankline_texinfo = "";
144 %highlights_tex = ( $type_constant, "{\\\\it \$1}",
145 $type_func, "{\\\\bf \$1}",
146 $type_struct, "{\\\\it \$1}",
147 $type_param, "{\\\\bf \$1}" );
148 $blankline_tex = "\\\\";
150 # sgml, docbook format
151 %highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
152 $type_func, "<function>\$1</function>",
153 $type_struct, "<structname>\$1</structname>",
154 $type_env, "<envar>\$1</envar>",
155 $type_param, "<parameter>\$1</parameter>" );
156 $blankline_sgml = "</para><para>\n";
158 # these are pretty rough
159 %highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n",
160 $type_func, "\\n.B \\\"\$1\\\"\\n",
161 $type_struct, "\\n.I \\\"\$1\\\"\\n",
162 $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" );
166 %highlights_text = ( $type_constant, "\$1",
169 $type_param, "\$1" );
170 $blankline_text = "";
174 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex | -texinfo -listfunc ]\n";
175 print " [ -sourceversion verno ] [ -includefuncprefix ]\n";
176 print " [ -bugsto address ] [ -seeinfo infonode ] [ -copyright notice]\n";
177 print " [ -verbatimcopying ]\n";
178 print " [ -function funcname [ -function funcname ...] ]\n";
179 print " c source file(s) > outputfile\n";
189 $output_mode = "man";
190 %highlights = %highlights_man;
191 $blankline = $blankline_man;
192 $modulename = "API Documentation";
193 $sourceversion = strftime
"%Y-%m-%d", localtime;
195 while ($ARGV[0] =~ m/^-(.*)/) {
197 if ($cmd eq "-html") {
198 $output_mode = "html";
199 %highlights = %highlights_html;
200 $blankline = $blankline_html;
201 } elsif ($cmd eq "-man") {
202 $output_mode = "man";
203 %highlights = %highlights_man;
204 $blankline = $blankline_man;
205 } elsif ($cmd eq "-tex") {
206 $output_mode = "tex";
207 %highlights = %highlights_tex;
208 $blankline = $blankline_tex;
209 } elsif ($cmd eq "-texinfo") {
210 $output_mode = "texinfo";
211 %highlights = %highlights_texinfo;
212 $blankline = $blankline_texinfo;
213 } elsif ($cmd eq "-text") {
214 $output_mode = "text";
215 %highlights = %highlights_text;
216 $blankline = $blankline_text;
217 } elsif ($cmd eq "-docbook") {
218 $output_mode = "sgml";
219 %highlights = %highlights_sgml;
220 $blankline = $blankline_sgml;
221 } elsif ($cmd eq "-listfunc") {
222 $output_mode = "listfunc";
223 } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
224 $modulename = shift @ARGV;
225 } elsif ($cmd eq "-sourceversion") {
226 $sourceversion = shift @ARGV;
227 } elsif ($cmd eq "-includefuncprefix") {
228 $includefuncprefix = 1;
229 } elsif ($cmd eq "-bugsto") {
230 $bugsto = shift @ARGV;
231 } elsif ($cmd eq "-copyright") {
232 $copyright = shift @ARGV;
233 } elsif ($cmd eq "-verbatimcopying") {
234 $verbatimcopying = 1;
235 } elsif ($cmd eq "-seeinfo") {
236 $seeinfo = shift @ARGV;
237 } elsif ($cmd eq "-function") { # to only output specific functions
239 $function = shift @ARGV;
240 $function_table{$function} = 1;
241 } elsif ($cmd eq "-v") {
243 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
249 # dumps section contents to arrays/hashes intended for that purpose.
253 my $contents = join "\n", @_;
255 if ($name =~ m/$type_constant/) {
257 # print STDERR "constant section '$1' = '$contents'\n";
258 $constants{$name} = $contents;
259 } elsif ($name =~ m/$type_param/) {
260 # print STDERR "parameter def '$1' = '$contents'\n";
262 $parameters{$name} = $contents;
264 # print STDERR "other section '$name' = '$contents'\n";
265 $sections{$name} = $contents;
266 push @sectionlist, $name;
273 # parameters, a hash.
274 # function => "function name"
275 # parameterlist => @list of parameters
276 # parameters => %parameter descriptions
277 # sectionlist => @list of sections
278 # sections => %descriont descriptions
290 $output =~ s
,\
$1,$match1,g
;
291 $output =~ s
,\
$2,$match2,g
;
292 $output =~ s
,\
$3,$match3,g
;
293 $output =~ s
,\
$4,$match4,g
;
295 eval "\$return = qq/$output/";
297 # print "pattern $pattern matched 1=$match1 2=$match2 3=$match3 4=$match4 replace $repl yielded $output interpolated $return\n";
302 sub output_highlight
{
303 my $contents = join "\n", @_;
306 foreach $pattern (keys %highlights) {
307 # print "scanning pattern $pattern ($highlights{$pattern})\n";
308 $contents =~ s
:$pattern:repstr
($pattern, $highlights{$pattern}, $1, $2, $3, $4):gse
;
310 foreach $line (split "\n", $contents) {
312 print $lineprefix, $blankline;
314 print $lineprefix, $line;
321 my $contents = join "\n", @_;
325 foreach $pattern (keys %highlights) {
326 # print "scanning pattern $pattern ($highlights{$pattern})\n";
327 $contents =~ s
:$pattern:repstr
($pattern, $highlights{$pattern}, $1, $2, $3, $4):gse
;
329 foreach $line (split "\n", $contents) {
331 $ret = $ret . $lineprefix . $blankline;
333 $ret = $ret . $lineprefix . $line;
344 my ($parameter, $section);
347 print "\@deftypefun {" . $args{'functiontype'} . "} ";
348 print "{".$args{'function'}."} ";
351 foreach $parameter (@
{$args{'parameterlist'}}) {
352 print $args{'parametertypes'}{$parameter}." \@var{".$parameter."}";
353 if ($count != $#{$args{'parameterlist'}}) {
359 foreach $parameter (@
{$args{'parameterlist'}}) {
360 if ($args{'parameters'}{$parameter}) {
361 print "\@var{".$parameter."}: ";
362 output_highlight
($args{'parameters'}{$parameter});
366 foreach $section (@
{$args{'sectionlist'}}) {
367 print "\n\@strong{$section:} " if $section ne $section_default;
368 $args{'sections'}{$section} =~ s
:([{}]):\@\
1:gs
;
369 output_highlight
($args{'sections'}{$section});
371 print "\@end deftypefun\n\n";
377 my ($parameter, $section);
379 print "\n\n<a name=\"". $args{'function'} . "\"> </a><h2>Function</h2>\n";
381 print "<i>".$args{'functiontype'}."</i>\n";
382 print "<b>".$args{'function'}."</b>\n";
385 foreach $parameter (@
{$args{'parameterlist'}}) {
386 print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
387 if ($count != $#{$args{'parameterlist'}}) {
394 print "<h3>Arguments</h3>\n";
396 foreach $parameter (@
{$args{'parameterlist'}}) {
397 print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
399 output_highlight
($args{'parameters'}{$parameter});
402 foreach $section (@
{$args{'sectionlist'}}) {
403 print "<h3>$section</h3>\n";
405 output_highlight
($args{'sections'}{$section});
414 my ($parameter, $section);
416 my $func = $args{'function'};
425 print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
427 $type = $args{'functiontype'};
430 print "{\\it ".$type."}\n";
431 print "{\\bf ".$func."}\n";
434 foreach $parameter (@
{$args{'parameterlist'}}) {
435 $param = $args{'parametertypes'}{$parameter};
436 $param2 = $parameter;
438 $param2 =~ s/_/\\_/g;
440 print "{\\it ".$param."} {\\bf ".$param2."}";
441 if ($count != $#{$args{'parameterlist'}}) {
448 print "\n{\\large{Arguments}}\n";
450 print "\\begin{itemize}\n";
452 foreach $parameter (@
{$args{'parameterlist'}}) {
453 $param1 = $args{'parametertypes'}{$parameter};
454 $param1 =~ s/_/\\_/g;
455 $param2 = $parameter;
456 $param2 =~ s/_/\\_/g;
459 print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
462 $param3 = $args{'parameters'}{$parameter};
463 $param3 =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
465 $out = just_highlight
($param3);
470 print "\\item void\n";
472 print "\\end{itemize}\n";
474 foreach $section (@
{$args{'sectionlist'}}) {
477 $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
479 print "\n{\\large{$sec}}\\\\\n";
480 print "\\begin{rmfamily}\n";
482 $sec = $args{'sections'}{$section};
484 $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
485 $sec =~ s/->/\$\\rightarrow\$/g;
486 $sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
488 $out = just_highlight
($sec);
492 print "\\end{rmfamily}\n";
498 # output in sgml DocBook
501 my ($parameter, $section);
505 $id = $args{'module'}."-".$args{'function'};
506 $id =~ s/[^A-Za-z0-9]/-/g;
508 print "<refentry>\n";
510 print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
511 print "</refmeta>\n";
512 print "<refnamediv>\n";
513 print " <refname>".$args{'function'}."</refname>\n";
514 print " <refpurpose>\n";
515 print " ".$args{'purpose'}."\n";
516 print " </refpurpose>\n";
517 print "</refnamediv>\n";
519 print "<refsynopsisdiv>\n";
520 print " <title>Synopsis</title>\n";
521 print " <funcsynopsis>\n";
522 print " <funcdef>".$args{'functiontype'}." ";
523 print "<function>".$args{'function'}." ";
524 print "</function></funcdef>\n";
526 # print "<refsect1>\n";
527 # print " <title>Synopsis</title>\n";
528 # print " <funcsynopsis>\n";
529 # print " <funcdef>".$args{'functiontype'}." ";
530 # print "<function>".$args{'function'}." ";
531 # print "</function></funcdef>\n";
534 if ($#{$args{'parameterlist'}} >= 0) {
535 foreach $parameter (@
{$args{'parameterlist'}}) {
536 print " <paramdef>".$args{'parametertypes'}{$parameter};
537 print " <parameter>$parameter</parameter></paramdef>\n";
542 print " </funcsynopsis>\n";
543 print "</refsynopsisdiv>\n";
544 # print "</refsect1>\n";
547 print "<refsect1>\n <title>Arguments</title>\n";
548 # print "<para>\nArguments\n";
549 if ($#{$args{'parameterlist'}} >= 0) {
550 print " <variablelist>\n";
551 foreach $parameter (@
{$args{'parameterlist'}}) {
552 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
553 print " <listitem>\n <para>\n";
555 output_highlight
($args{'parameters'}{$parameter});
556 print " </para>\n </listitem>\n </varlistentry>\n";
558 print " </variablelist>\n";
560 print " <para>\n None\n </para>\n";
562 print "</refsect1>\n";
564 # print out each section
566 foreach $section (@
{$args{'sectionlist'}}) {
567 print "<refsect1>\n <title>$section</title>\n <para>\n";
568 # print "<para>\n$section\n";
569 if ($section =~ m/EXAMPLE/i) {
570 print "<example><para>\n";
572 output_highlight
($args{'sections'}{$section});
574 if ($section =~ m/EXAMPLE/i) {
575 print "</para></example>\n";
577 print " </para>\n</refsect1>\n";
587 my ($parameter, $section);
590 print ".TH \"$args{'function'}\" 3 \"$args{'sourceversion'}\" \"". $args{'module'} . "\" \"". $args{'module'} . "\"\n";
594 print $args{'function'}."\n";
596 print ".SH SYNOPSIS\n";
597 print ".B #include <". lc((split /_/, $args{'function'})[0]) . ".h>\n"
598 if $args{'includefuncprefix'};
600 print ".BI \"".$args{'functiontype'}." ".$args{'function'}."(";
602 foreach $parameter (@
{$args{'parameterlist'}}) {
603 print $args{'parametertypes'}{$parameter}." \" ".$parameter." \"";
604 if ($count != $#{$args{'parameterlist'}}) {
611 print ".SH ARGUMENTS\n";
612 foreach $parameter (@
{$args{'parameterlist'}}) {
613 print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
614 output_highlight
($args{'parameters'}{$parameter});
616 foreach $section (@
{$args{'sectionlist'}}) {
617 print ".SH \"" . uc($section) . "\"\n";
618 output_highlight
($args{'sections'}{$section});
621 if ($args{'bugsto'}) {
622 print ".SH \"REPORTING BUGS\"\n";
623 print "Report bugs to <". $args{'bugsto'} . ">.\n";
626 if ($args{'copyright'}) {
627 print ".SH COPYRIGHT\n";
628 print "Copyright \\(co ". $args{'copyright'} . ".\n";
629 if ($args{'verbatimcopying'}) {
631 print "Permission is granted to make and distribute verbatim copies of this\n";
632 print "manual provided the copyright notice and this permission notice are\n";
633 print "preserved on all copies.\n";
637 if ($args{'seeinfo'}) {
638 print ".SH \"SEE ALSO\"\n";
639 print "The full documentation for\n";
640 print ".B " . $args{'module'} . "\n";
641 print "is maintained as a Texinfo manual. If the\n";
644 print ".B " . $args{'module'} . "\n";
645 print "programs are properly installed at your site, the command\n";
647 print ".B info " . $args{'seeinfo'} . "\n";
649 print "should give you access to the complete manual.\n";
653 sub output_listfunc
{
655 print $args{'function'} . "\n";
662 my ($parameter, $section);
664 print "Function = ".$args{'function'}."\n";
665 print " return type: ".$args{'functiontype'}."\n\n";
666 foreach $parameter (@
{$args{'parameterlist'}}) {
667 print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n";
668 print " -> ".$args{'parameters'}{$parameter}."\n";
670 foreach $section (@
{$args{'sectionlist'}}) {
671 print " $section:\n";
673 output_highlight
($args{'sections'}{$section});
678 # generic output function - calls the right one based
679 # on current output mode.
680 sub output_function
{
682 eval "output_".$output_mode."(\@_);";
687 # takes a function prototype and spits out all the details
688 # stored in the global arrays/hsahes.
690 my $prototype = shift @_;
692 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
693 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
694 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
695 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
696 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/) {
701 # print STDERR "ARGS = '$args'\n";
703 foreach $arg (split ',', $args) {
704 # strip leading/trailing spaces
707 # print STDERR "SCAN ARG: '$arg'\n";
708 @args = split('\s', $arg);
710 # print STDERR " -> @args\n";
712 # print STDERR " -> @args\n";
713 if ($param =~ m/^(\*+)(.*)/) {
717 if ($param =~ m/^(.*)(\[\])$/) {
721 # print STDERR " :> @args\n";
722 $type = join " ", @args;
724 if ($parameters{$param} eq "" && $param != "void") {
725 $parameters{$param} = "-- undescribed --";
726 print STDERR
"Warning($lineno): Function parameter '$param' not described in '$function_name'\n";
729 push @parameterlist, $param;
730 $parametertypes{$param} = $type;
732 # print STDERR "param = '$param', type = '$type'\n";
735 print STDERR
"Error($lineno): cannot understand prototype: '$prototype'\n";
739 if ($function_only==0 || defined($function_table{$function_name})) {
740 output_function
({'function' => $function_name,
741 'module' => $modulename,
742 'sourceversion' => $sourceversion,
743 'includefuncprefix' => $includefuncprefix,
745 'copyright' => $copyright,
746 'verbatimcopying' => $verbatimcopying,
747 'seeinfo' => $seeinfo,
748 'functiontype' => $return_type,
749 'parameterlist' => \
@parameterlist,
750 'parameters' => \
%parameters,
751 'parametertypes' => \
%parametertypes,
752 'sectionlist' => \
@sectionlist,
753 'sections' => \
%sections,
754 'purpose' => $function_purpose
759 ######################################################################
763 # 1 - looking for function name
764 # 2 - scanning field start.
765 # 3 - scanning prototype.
769 $doc_special = "\@\%\$\&";
771 $doc_start = "^/\\*\\*\$";
773 $doc_com = "\\s*\\*\\s*";
774 $doc_func = $doc_com."(\\w+):?";
775 $doc_sect = $doc_com."([".$doc_special."[:upper:]][\\w ]+):(.*)";
776 $doc_content = $doc_com."(.*)";
785 $section_default = "Description"; # default section
786 $section = $section_default;
789 foreach $file (@ARGV) {
790 if (!open(IN
,"<$file")) {
791 print STDERR
"Error: Cannot open file $file\n";
799 $state = 1; # next line is always the function name
801 } elsif ($state == 1) { # this line is the function name (always)
806 $function_purpose = $1;
808 $function_purpose = "";
811 print STDERR
"Info($lineno): Scanning doc for $function\n";
814 print STDERR
"WARN($lineno): Cannot understand $_ on line $lineno",
815 " - I thought it was a doc line\n";
818 } elsif ($state == 2) { # look for head: lines, and include content
823 if ($contents ne "") {
824 dump_section
($section, $contents);
825 $section = $section_default;
828 $contents = $newcontents;
829 if ($contents ne "") {
832 $section = $newsection;
833 } elsif (/$doc_end/) {
835 if ($contents ne "") {
836 dump_section
($section, $contents);
837 $section = $section_default;
841 # print STDERR "end of doc comment, looking for prototype\n";
844 } elsif (/$doc_content/) {
845 # miguel-style comment kludge, look for blank lines after
846 # @parameter line to signify start of description
847 if ($1 eq "" && $section =~ m/^@/) {
848 dump_section
($section, $contents);
849 $section = $section_default;
852 $contents .= $1."\n";
855 # i dont know - bad line? ignore.
856 print STDERR
"WARNING($lineno): bad line: $_";
858 } elsif ($state == 3) { # scanning for function { (end of prototype)
859 if (m
#\s*/\*\s+MACDOC\s*#io) {
866 $prototype =~ s@
/\*.*?\*/@
@gos; # strip comments.
867 $prototype =~ s@
[\r\n]+@
@gos; # strip newlines/cr's.
868 $prototype =~ s@
^ +@
@gos; # strip leading spaces
869 dump_function
($prototype);
874 %parametertypes = ();