2003-05-04 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / doc / gdoc
1 #!/usr/bin/perl
2
3 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
4 ##                    hacked to allow -tex option --nmav         ##
5 ##                                                               ##
6 ## This software falls under the GNU Public License. Please read ##
7 ##              the COPYING file for more information            ##
8
9 #
10 # This will read a 'c' file and scan for embedded comments in the
11 # style of gnome comments (+minor extensions - see below).
12 #
13
14 # Note: This only supports 'c'.
15
16 # usage:
17 # gdoc [ -docbook | -html | -text | -man ]
18 #      [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
19 #
20 #  Set output format using one of -docbook -html -text or -man.  Default is man.
21 #
22 #  -function funcname
23 #       If set, then only generate documentation for the given function(s).  All
24 #       other functions are ignored.
25 #
26 #  c files - list of 'c' files to process
27 #
28 #  All output goes to stdout, with errors to stderr.
29
30 #
31 # format of comments.
32 # In the following table, (...)? signifies optional structure.
33 #                         (...)* signifies 0 or more structure elements
34 # /**
35 #  * function_name(:)? (- short description)?
36 # (* @parameterx: (description of parameter x)?)*
37 # (* a blank line)?
38 #  * (Description:)? (Description of function)?
39 #  * (section header: (section description)? )*
40 #  (*)?*/
41 #
42 # So .. the trivial example would be:
43 #
44 # /**
45 #  * my_function
46 #  **/
47 #
48 # If the Description: header tag is ommitted, then there must be a blank line
49 # after the last parameter specification.
50 # e.g.
51 # /**
52 #  * my_function - does my stuff
53 #  * @my_arg: its mine damnit
54 #  *
55 #  * Does my stuff explained. 
56 #  */
57 #
58 #  or, could also use:
59 # /**
60 #  * my_function - does my stuff
61 #  * @my_arg: its mine damnit
62 #  * Description: Does my stuff explained. 
63 #  */
64 # etc.
65 #
66 # All descriptions can be multiline, apart from the short function description.
67 #
68 # All descriptive text is further processed, scanning for the following special
69 # patterns, which are highlighted appropriately.
70 #
71 # 'funcname()' - function
72 # '$ENVVAR' - environmental variable
73 # '&struct_name' - name of a structure
74 # '@parameter' - name of a parameter
75 # '%CONST' - name of a constant.
76
77 # match expressions used to find embedded type information
78 $type_constant = "\\\%(\\w+)";
79 #$type_func = "(\\w+\\(\\))";
80 $type_func = "(\\(w||\\\\)+\\(\\))";
81 $type_param = "\\\@(\\w+)";
82 $type_struct = "\\\&(\\w+)";
83 $type_env = "(\\\$\\w+)";
84
85
86 # Output conversion substitutions.
87 #  One for each output format
88
89 # these work fairly well
90 %highlights_html = ( $type_constant, "<i>\$1</i>",
91                      $type_func, "<b>\$1</b>",
92                      $type_struct, "<i>\$1</i>",
93                      $type_param, "<tt><b>\$1</b></tt>" );
94 $blankline_html = "<p>";
95
96 %highlights_tex = ( $type_constant, "{\\\\it \$1}",
97                      $type_func, "{\\\\bf \$1}",
98                      $type_struct, "{\\\\it \$1}",
99                      $type_param, "{\\\\bf \$1}" );
100 $blankline_tex = "\\par";
101
102 # sgml, docbook format
103 %highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
104                      $type_func, "<function>\$1</function>",
105                      $type_struct, "<structname>\$1</structname>",
106                      $type_env, "<envar>\$1</envar>",
107                      $type_param, "<parameter>\$1</parameter>" );
108 $blankline_sgml = "</para><para>\n";
109
110 # these are pretty rough
111 %highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n",
112                     $type_func, "\\n.B \\\"\$1\\\"\\n",
113                     $type_struct, "\\n.I \\\"\$1\\\"\\n",
114                     $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" );
115 $blankline_man = "";
116
117 # text-mode
118 %highlights_text = ( $type_constant, "\$1",
119                      $type_func, "\$1",
120                      $type_struct, "\$1",
121                      $type_param, "\$1" );
122 $blankline_text = "";
123
124
125 sub usage {
126     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex ]\n";
127     print "         [ -function funcname [ -function funcname ...] ]\n";
128     print "         c source file(s) > outputfile\n";
129     exit 1;
130 }
131
132 # read arguments
133 if ($#ARGV==-1) {
134     usage();
135 }
136
137 $verbose = 0;
138 $output_mode = "man";
139 %highlights = %highlights_man;
140 $blankline = $blankline_man;
141 $modulename = "API Documentation";
142 $function_only = 0;
143 while ($ARGV[0] =~ m/^-(.*)/) {
144     $cmd = shift @ARGV;
145     if ($cmd eq "-html") {
146         $output_mode = "html";
147         %highlights = %highlights_html;
148         $blankline = $blankline_html;
149     } elsif ($cmd eq "-man") {
150         $output_mode = "man";
151         %highlights = %highlights_man;
152         $blankline = $blankline_man;
153     } elsif ($cmd eq "-tex") {
154         $output_mode = "tex";
155         %highlights = %highlights_tex;
156         $blankline = $blankline_tex;
157     } elsif ($cmd eq "-text") {
158         $output_mode = "text";
159         %highlights = %highlights_text;
160         $blankline = $blankline_text;
161     } elsif ($cmd eq "-docbook") {
162         $output_mode = "sgml";
163         %highlights = %highlights_sgml;
164         $blankline = $blankline_sgml;
165     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
166         $modulename = shift @ARGV;
167     } elsif ($cmd eq "-function") { # to only output specific functions
168         $function_only = 1;
169         $function = shift @ARGV;
170         $function_table{$function} = 1;
171     } elsif ($cmd eq "-v") {
172         $verbose = 1;
173     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
174         usage();
175     }
176 }
177
178
179 # generate a sequence of code that will splice in highlighting information
180 # using the s// operator.
181 $dohighlight = "";
182 foreach $pattern (keys %highlights) {
183 #    print "scanning pattern $pattern ($highlights{$pattern})\n";
184     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
185 }
186
187 ##
188 # dumps section contents to arrays/hashes intended for that purpose.
189 #
190 sub dump_section {
191     my $name = shift @_;
192     my $contents = join "\n", @_;
193
194     if ($name =~ m/$type_constant/) {
195         $name = $1;
196 #       print STDERR "constant section '$1' = '$contents'\n";
197         $constants{$name} = $contents;
198     } elsif ($name =~ m/$type_param/) {
199 #       print STDERR "parameter def '$1' = '$contents'\n";
200         $name = $1;
201         $parameters{$name} = $contents;
202     } else {
203 #       print STDERR "other section '$name' = '$contents'\n";
204         $sections{$name} = $contents;
205         push @sectionlist, $name;
206     }
207 }
208
209 ##
210 # output function
211 #
212 # parameters, a hash.
213 #  function => "function name"
214 #  parameterlist => @list of parameters
215 #  parameters => %parameter descriptions
216 #  sectionlist => @list of sections
217 #  sections => %descriont descriptions
218 #  
219
220 sub output_highlight {
221     my $contents = join "\n", @_;
222     my $line;
223
224     eval $dohighlight;
225     foreach $line (split "\n", $contents) {
226         if ($line eq ""){
227             print $lineprefix, $blankline;
228         } else {
229             print $lineprefix, $line;
230         }
231         print "\n";
232     }
233 }
234
235
236 # output in html
237 sub output_html {
238     my %args = %{$_[0]};
239     my ($parameter, $section);
240     my $count;
241     print "\n\n<a name=\"". $args{'function'} . "\">&nbsp</a><h2>Function</h2>\n";
242
243     print "<i>".$args{'functiontype'}."</i>\n";
244     print "<b>".$args{'function'}."</b>\n";
245     print "(";
246     $count = 0;
247     foreach $parameter (@{$args{'parameterlist'}}) {
248         print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
249         if ($count != $#{$args{'parameterlist'}}) {
250             $count++;
251             print ", ";
252         }
253     }
254     print ")\n";
255
256     print "<h3>Arguments</h3>\n";
257     print "<dl>\n";
258     foreach $parameter (@{$args{'parameterlist'}}) {
259         print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
260         print "<dd>";
261         output_highlight($args{'parameters'}{$parameter});
262     }
263     print "</dl>\n";
264     foreach $section (@{$args{'sectionlist'}}) {
265         print "<h3>$section</h3>\n";
266         print "<ul>\n";
267         output_highlight($args{'sections'}{$section});
268         print "</ul>\n";
269     }
270     print "<hr>\n";
271 }
272
273 # output in tex
274 sub output_tex {
275     my %args = %{$_[0]};
276     my ($parameter, $section);
277     my $count;
278     my $func = $args{'function'};
279     my $param;
280     my $param2;
281     my $sec;
282     my $check;
283     my $type;
284
285     $func =~ s/_/\\_/g;
286
287     print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
288
289     $type = $args{'functiontype'};
290     $type =~ s/_/\\_/g;
291
292     print "{\\it ".$type."}\n";
293     print "{\\bf ".$func."}\n";
294     print "(\n";
295     $count = 0;
296     foreach $parameter (@{$args{'parameterlist'}}) {
297         $param = $args{'parametertypes'}{$parameter};
298         $param2 = $parameter;
299         $param =~ s/_/\\_/g;
300         $param2 =~ s/_/\\_/g;
301
302         print "{\\it ".$param."} {\\bf ".$param2."}\n";
303         if ($count != $#{$args{'parameterlist'}}) {
304             $count++;
305             print ", ";
306         }
307     }
308     print ")\n";
309
310     print "\n{\\large{Arguments}}\n";
311
312     print "\\begin{itemize}\n";
313     $check=0;
314     foreach $parameter (@{$args{'parameterlist'}}) {
315         $param = $args{'parametertypes'}{$parameter};
316         $param =~ s/_/\\_/g;
317         $param2 = $parameter;
318         $param2 =~ s/_/\\_/g;
319
320         $check = 1;
321         print "\\item {\\it ".$param."} {\\bf ".$param2."}\n";
322         print "\n";
323
324         output_highlight($param{$parameter});
325     }
326     if ($check==0) {
327         print "\\item void\n";
328     }
329     print "\\end{itemize}\n";
330
331     foreach $section (@{$args{'sectionlist'}}) {
332         print "\n\\par{\\large{$section}}\\par\n";
333         print "\\begin{rmfamily}\n";
334
335         $sec = $args{'sections'}{$section};
336         $sec =~ s/_/\\_/g;
337         $sec =~ s/&/\\&/g;
338         output_highlight($sec);
339         print "\\end{rmfamily}\n";
340     }
341     print "\n";
342 }
343
344
345 # output in sgml DocBook
346 sub output_sgml {
347     my %args = %{$_[0]};
348     my ($parameter, $section);
349     my $count;
350     my $id;
351
352     $id = $args{'module'}."-".$args{'function'};
353     $id =~ s/[^A-Za-z0-9]/-/g;
354
355     print "<refentry>\n";
356     print "<refmeta>\n";
357     print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
358     print "</refmeta>\n";
359     print "<refnamediv>\n";
360     print " <refname>".$args{'function'}."</refname>\n";
361     print " <refpurpose>\n";
362     print "  ".$args{'purpose'}."\n";
363     print " </refpurpose>\n";
364     print "</refnamediv>\n";
365
366     print "<refsynopsisdiv>\n";
367     print " <title>Synopsis</title>\n";
368     print "  <funcsynopsis>\n";
369     print "   <funcdef>".$args{'functiontype'}." ";
370     print "<function>".$args{'function'}." ";
371     print "</function></funcdef>\n";
372
373 #    print "<refsect1>\n";
374 #    print " <title>Synopsis</title>\n";
375 #    print "  <funcsynopsis>\n";
376 #    print "   <funcdef>".$args{'functiontype'}." ";
377 #    print "<function>".$args{'function'}." ";
378 #    print "</function></funcdef>\n";
379
380     $count = 0;
381     if ($#{$args{'parameterlist'}} >= 0) {
382         foreach $parameter (@{$args{'parameterlist'}}) {
383             print "   <paramdef>".$args{'parametertypes'}{$parameter};
384             print " <parameter>$parameter</parameter></paramdef>\n";
385         }
386     } else {
387         print "  <void>\n";
388     }
389     print "  </funcsynopsis>\n";
390     print "</refsynopsisdiv>\n";
391 #    print "</refsect1>\n";
392
393     # print parameters
394     print "<refsect1>\n <title>Arguments</title>\n";
395 #    print "<para>\nArguments\n";
396     if ($#{$args{'parameterlist'}} >= 0) {
397         print " <variablelist>\n";
398         foreach $parameter (@{$args{'parameterlist'}}) {
399             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
400             print "   <listitem>\n    <para>\n";
401             $lineprefix="     ";
402             output_highlight($args{'parameters'}{$parameter});
403             print "    </para>\n   </listitem>\n  </varlistentry>\n";
404         }
405         print " </variablelist>\n";
406     } else {
407         print " <para>\n  None\n </para>\n";
408     }
409     print "</refsect1>\n";
410
411     # print out each section
412     $lineprefix="   ";
413     foreach $section (@{$args{'sectionlist'}}) {
414         print "<refsect1>\n <title>$section</title>\n <para>\n";
415 #       print "<para>\n$section\n";
416         if ($section =~ m/EXAMPLE/i) {
417             print "<example><para>\n";
418         }
419         output_highlight($args{'sections'}{$section});
420 #       print "</para>";
421         if ($section =~ m/EXAMPLE/i) {
422             print "</para></example>\n";
423         }
424         print " </para>\n</refsect1>\n";
425     }
426
427     print "\n\n";
428 }
429
430 ##
431 # output in man
432 sub output_man {
433     my %args = %{$_[0]};
434     my ($parameter, $section);
435     my $count;
436
437     print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" GNOME\n";
438
439     print ".SH Function\n";
440
441     print ".I \"".$args{'functiontype'}."\"\n";
442     print ".B \"".$args{'function'}."\"\n";
443     print "(\n";
444     $count = 0;
445     foreach $parameter (@{$args{'parameterlist'}}) {
446         print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n";
447         if ($count != $#{$args{'parameterlist'}}) {
448             $count++;
449             print ",\n";
450         }
451     }
452     print ")\n";
453
454     print ".SH Arguments\n";
455     foreach $parameter (@{$args{'parameterlist'}}) {
456         print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
457         output_highlight($args{'parameters'}{$parameter});
458     }
459     foreach $section (@{$args{'sectionlist'}}) {
460         print ".SH \"$section\"\n";
461         output_highlight($args{'sections'}{$section});
462     }
463 }
464
465 ##
466 # output in text
467 sub output_text {
468     my %args = %{$_[0]};
469     my ($parameter, $section);
470
471     print "Function = ".$args{'function'}."\n";
472     print "  return type: ".$args{'functiontype'}."\n\n";
473     foreach $parameter (@{$args{'parameterlist'}}) {
474         print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n";
475         print "    -> ".$args{'parameters'}{$parameter}."\n";
476     }
477     foreach $section (@{$args{'sectionlist'}}) {
478         print " $section:\n";
479         print "    -> ";
480         output_highlight($args{'sections'}{$section});
481     }
482 }
483
484 ##
485 # generic output function - calls the right one based
486 # on current output mode.
487 sub output_function {
488 #    output_html(@_);
489     eval "output_".$output_mode."(\@_);";
490 }
491
492
493 ##
494 # takes a function prototype and spits out all the details
495 # stored in the global arrays/hsahes.
496 sub dump_function {
497     my $prototype = shift @_;
498
499     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
500         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
501         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
502         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
503         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/)  {
504         $return_type = $1;
505         $function_name = $2;
506         $args = $3;
507
508 #       print STDERR "ARGS = '$args'\n";
509
510         foreach $arg (split ',', $args) {
511             # strip leading/trailing spaces
512             $arg =~ s/^\s*//;
513             $arg =~ s/\s*$//;
514 #           print STDERR "SCAN ARG: '$arg'\n";
515             @args = split('\s', $arg);
516
517 #           print STDERR " -> @args\n";
518             $param = pop @args;
519 #           print STDERR " -> @args\n";
520             if ($param =~ m/^(\*+)(.*)/) {
521                 $param = $2;
522                 push @args, $1;
523             }
524             $type = join " ", @args;
525
526             if ($parameters{$param} eq "") {
527                 $parameters{$param} = "-- undescribed --";
528                 print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n";
529             }
530
531             push @parameterlist, $param;
532             $parametertypes{$param} = $type;
533
534 #           print STDERR "param = '$param', type = '$type'\n";
535         }
536     } else {
537         print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
538         return;
539     }
540
541     if ($function_only==0 || defined($function_table{$function_name})) {
542         output_function({'function' => $function_name,
543                          'module' => $modulename,
544                          'functiontype' => $return_type,
545                          'parameterlist' => \@parameterlist,
546                          'parameters' => \%parameters,
547                          'parametertypes' => \%parametertypes,
548                          'sectionlist' => \@sectionlist,
549                          'sections' => \%sections,
550                          'purpose' => $function_purpose
551                          });
552     }
553 }
554
555 ######################################################################
556 # main
557 # states
558 # 0 - normal code
559 # 1 - looking for function name
560 # 2 - scanning field start.
561 # 3 - scanning prototype.
562 $state = 0;
563 $section = "";
564
565 $doc_special = "\@\%\$\&";
566
567 $doc_start = "^/\\*\\*\$";
568 $doc_end = "\\*/";
569 $doc_com = "\\s*\\*\\s*";
570 $doc_func = $doc_com."(\\w+):?";
571 $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
572 $doc_content = $doc_com."(.*)";
573
574 %constants = ();
575 %parameters = ();
576 @parameterlist = ();
577 %sections = ();
578 @sectionlist = ();
579
580 $contents = "";
581 $section_default = "Description";       # default section
582 $section = $section_default;
583
584 $lineno = 0;
585 foreach $file (@ARGV) {
586     if (!open(IN,"<$file")) {
587         print STDERR "Error: Cannot open file $file\n";
588         next;
589     }
590     while (<IN>) {
591         $lineno++;
592
593         if ($state == 0) {
594             if (/$doc_start/o) {
595                 $state = 1;             # next line is always the function name
596             }
597         } elsif ($state == 1) { # this line is the function name (always)
598             if (/$doc_func/o) {
599                 $function = $1;
600                 $state = 2;
601                 if (/-(.*)/) {
602                     $function_purpose = $1;
603                 } else {
604                     $function_purpose = "";
605                 }
606                 if ($verbose) {
607                     print STDERR "Info($lineno): Scanning doc for $function\n";
608                 }
609             } else {
610                 print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
611                 " - I thought it was a doc line\n";
612                 $state = 0;
613             }
614         } elsif ($state == 2) { # look for head: lines, and include content
615             if (/$doc_sect/o) {
616                 $newsection = $1;
617                 $newcontents = $2;
618
619                 if ($contents ne "") {
620                     dump_section($section, $contents);
621                     $section = $section_default;
622                 }
623
624                 $contents = $newcontents;
625                 if ($contents ne "") {
626                     $contents .= "\n";
627                 }
628                 $section = $newsection;
629             } elsif (/$doc_end/) {
630
631                 if ($contents ne "") {
632                     dump_section($section, $contents);
633                     $section = $section_default;
634                     $contents = "";
635                 }
636
637 #           print STDERR "end of doc comment, looking for prototype\n";
638                 $prototype = "";
639                 $state = 3;
640             } elsif (/$doc_content/) {
641                 # miguel-style comment kludge, look for blank lines after
642                 # @parameter line to signify start of description
643                 if ($1 eq "" && $section =~ m/^@/) {
644                     dump_section($section, $contents);
645                     $section = $section_default;
646                     $contents = "";
647                 } else {
648                     $contents .= $1."\n";
649                 }
650             } else {
651                 # i dont know - bad line?  ignore.
652                 print STDERR "WARNING($lineno): bad line: $_"; 
653             }
654         } elsif ($state == 3) { # scanning for function { (end of prototype)
655             if (m#\s*/\*\s+MACDOC\s*#io) {
656               # do nothing
657             }
658             elsif (/([^\{]*)/) {
659                 $prototype .= $1;
660             }
661             if (/\{/) {
662                 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
663                 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
664                 $prototype =~ s@^ +@@gos; # strip leading spaces
665                 dump_function($prototype);
666
667                 $function = "";
668                 %constants = ();
669                 %parameters = ();
670                 %parametertypes = ();
671                 @parameterlist = ();
672                 %sections = ();
673                 @sectionlist = ();
674                 $prototype = "";
675
676                 $state = 0;
677             }
678         }
679     }
680 }
681