git.oblomov.eu Git - linux-2.6/blob - scripts/kernel-doc

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4
   5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
   6 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
   7 ## Copyright (C) 2001  Simon Huggins                             ##
   8 ##                                                               ##
   9 ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
  10 ## Copyright (c) 2000 MontaVista Software, Inc.                  ##
  11 ##                                                               ##
  12 ## This software falls under the GNU General Public License.     ##
  13 ## Please read the COPYING file for more information             ##
  14
  15 # w.o. 03-11-2000: added the '-filelist' option.
  16
  17 # 18/01/2001 -  Cleanups
  18 #               Functions prototyped as foo(void) same as foo()
  19 #               Stop eval'ing where we don't need to.
  20 # -- huggie@earth.li
  21
  22 # 27/06/2001 -  Allowed whitespace after initial "/**" and
  23 #               allowed comments before function declarations.
  24 # -- Christian Kreibich <ck@whoop.org>
  25
  26 # Still to do:
  27 #       - add perldoc documentation
  28 #       - Look more closely at some of the scarier bits :)
  29
  30 # 26/05/2001 -  Support for separate source and object trees.
  31 #               Return error code.
  32 #               Keith Owens <kaos@ocs.com.au>
  33
  34 # 23/09/2001 - Added support for typedefs, structs, enums and unions
  35 #              Support for Context section; can be terminated using empty line
  36 #              Small fixes (like spaces vs. \s in regex)
  37 # -- Tim Jansen <tim@tjansen.de>
  38
  39
  40 #
  41 # This will read a 'c' file and scan for embedded comments in the
  42 # style of gnome comments (+minor extensions - see below).
  43 #
  44
  45 # Note: This only supports 'c'.
  46
  47 # usage:
  48 # kernel-doc [ -docbook | -html | -text | -man ]
  49 #           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
  50 # or
  51 #           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
  52 #
  53 #  Set output format using one of -docbook -html -text or -man.  Default is man.
  54 #
  55 #  -function funcname
  56 #       If set, then only generate documentation for the given function(s).  All
  57 #       other functions are ignored.
  58 #
  59 #  -nofunction funcname
  60 #       If set, then only generate documentation for the other function(s).
  61 #       Cannot be used together with -function
  62 #       (yes, that's a bug -- perl hackers can fix it 8))
  63 #
  64 #  c files - list of 'c' files to process
  65 #
  66 #  All output goes to stdout, with errors to stderr.
  67
  68 #
  69 # format of comments.
  70 # In the following table, (...)? signifies optional structure.
  71 #                         (...)* signifies 0 or more structure elements
  72 # /**
  73 #  * function_name(:)? (- short description)?
  74 # (* @parameterx: (description of parameter x)?)*
  75 # (* a blank line)?
  76 #  * (Description:)? (Description of function)?
  77 #  * (section header: (section description)? )*
  78 #  (*)?*/
  79 #
  80 # So .. the trivial example would be:
  81 #
  82 # /**
  83 #  * my_function
  84 #  **/
  85 #
  86 # If the Description: header tag is omitted, then there must be a blank line
  87 # after the last parameter specification.
  88 # e.g.
  89 # /**
  90 #  * my_function - does my stuff
  91 #  * @my_arg: its mine damnit
  92 #  *
  93 #  * Does my stuff explained.
  94 #  */
  95 #
  96 #  or, could also use:
  97 # /**
  98 #  * my_function - does my stuff
  99 #  * @my_arg: its mine damnit
 100 #  * Description: Does my stuff explained.
 101 #  */
 102 # etc.
 103 #
 104 # Beside functions you can also write documentation for structs, unions,
 105 # enums and typedefs. Instead of the function name you must write the name
 106 # of the declaration;  the struct/union/enum/typedef must always precede
 107 # the name. Nesting of declarations is not supported.
 108 # Use the argument mechanism to document members or constants.
 109 # e.g.
 110 # /**
 111 #  * struct my_struct - short description
 112 #  * @a: first member
 113 #  * @b: second member
 114 #  *
 115 #  * Longer description
 116 #  */
 117 # struct my_struct {
 118 #     int a;
 119 #     int b;
 120 # /* private: */
 121 #     int c;
 122 # };
 123 #
 124 # All descriptions can be multiline, except the short function description.
 125 #
 126 # You can also add additional sections. When documenting kernel functions you
 127 # should document the "Context:" of the function, e.g. whether the functions
 128 # can be called form interrupts. Unlike other sections you can end it with an
 129 # empty line.
 130 # Example-sections should contain the string EXAMPLE so that they are marked
 131 # appropriately in DocBook.
 132 #
 133 # Example:
 134 # /**
 135 #  * user_function - function that can only be called in user context
 136 #  * @a: some argument
 137 #  * Context: !in_interrupt()
 138 #  *
 139 #  * Some description
 140 #  * Example:
 141 #  *    user_function(22);
 142 #  */
 143 # ...
 144 #
 145 #
 146 # All descriptive text is further processed, scanning for the following special
 147 # patterns, which are highlighted appropriately.
 148 #
 149 # 'funcname()' - function
 150 # '$ENVVAR' - environmental variable
 151 # '&struct_name' - name of a structure (up to two words including 'struct')
 152 # '@parameter' - name of a parameter
 153 # '%CONST' - name of a constant.
 154
 155 my $errors = 0;
 156 my $warnings = 0;
 157
 158 # match expressions used to find embedded type information
 159 my $type_constant = '\%([-_\w]+)';
 160 my $type_func = '(\w+)\(\)';
 161 my $type_param = '\@(\w+)';
 162 my $type_struct = '\&((struct\s*)*[_\w]+)';
 163 my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';
 164 my $type_env = '(\$\w+)';
 165
 166 # Output conversion substitutions.
 167 #  One for each output format
 168
 169 # these work fairly well
 170 my %highlights_html = ( $type_constant, "<i>\$1</i>",
 171                         $type_func, "<b>\$1</b>",
 172                         $type_struct_xml, "<i>\$1</i>",
 173                         $type_env, "<b><i>\$1</i></b>",
 174                         $type_param, "<tt><b>\$1</b></tt>" );
 175 my $blankline_html = "<p>";
 176
 177 # XML, docbook format
 178 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
 179                         $type_constant, "<constant>\$1</constant>",
 180                         $type_func, "<function>\$1</function>",
 181                         $type_struct, "<structname>\$1</structname>",
 182                         $type_env, "<envar>\$1</envar>",
 183                         $type_param, "<parameter>\$1</parameter>" );
 184 my $blankline_xml = "</para><para>\n";
 185
 186 # gnome, docbook format
 187 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 188                          $type_func, "<function>\$1</function>",
 189                          $type_struct, "<structname>\$1</structname>",
 190                          $type_env, "<envar>\$1</envar>",
 191                          $type_param, "<parameter>\$1</parameter>" );
 192 my $blankline_gnome = "</para><para>\n";
 193
 194 # these are pretty rough
 195 my %highlights_man = ( $type_constant, "\$1",
 196                        $type_func, "\\\\fB\$1\\\\fP",
 197                        $type_struct, "\\\\fI\$1\\\\fP",
 198                        $type_param, "\\\\fI\$1\\\\fP" );
 199 my $blankline_man = "";
 200
 201 # text-mode
 202 my %highlights_text = ( $type_constant, "\$1",
 203                         $type_func, "\$1",
 204                         $type_struct, "\$1",
 205                         $type_param, "\$1" );
 206 my $blankline_text = "";
 207
 208
 209 sub usage {
 210     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
 211     print "         [ -function funcname [ -function funcname ...] ]\n";
 212     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
 213     print "         c source file(s) > outputfile\n";
 214     exit 1;
 215 }
 216
 217 # read arguments
 218 if ($#ARGV==-1) {
 219     usage();
 220 }
 221
 222 my $verbose = 0;
 223 my $output_mode = "man";
 224 my %highlights = %highlights_man;
 225 my $blankline = $blankline_man;
 226 my $modulename = "Kernel API";
 227 my $function_only = 0;
 228 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 229                 'July', 'August', 'September', 'October',
 230                 'November', 'December')[(localtime)[4]] .
 231   " " . ((localtime)[5]+1900);
 232
 233 # Essentially these are globals
 234 # They probably want to be tidied up made more localised or summat.
 235 # CAVEAT EMPTOR!  Some of the others I localised may not want to be which
 236 # could cause "use of undefined value" or other bugs.
 237 my ($function, %function_table,%parametertypes,$declaration_purpose);
 238 my ($type,$declaration_name,$return_type);
 239 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
 240
 241 # Generated docbook code is inserted in a template at a point where
 242 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
 243 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
 244 # We keep track of number of generated entries and generate a dummy
 245 # if needs be to ensure the expanded template can be postprocessed
 246 # into html.
 247 my $section_counter = 0;
 248
 249 my $lineprefix="";
 250
 251 # states
 252 # 0 - normal code
 253 # 1 - looking for function name
 254 # 2 - scanning field start.
 255 # 3 - scanning prototype.
 256 # 4 - documentation block
 257 my $state;
 258 my $in_doc_sect;
 259
 260 #declaration types: can be
 261 # 'function', 'struct', 'union', 'enum', 'typedef'
 262 my $decl_type;
 263
 264 my $doc_special = "\@\%\$\&";
 265
 266 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 267 my $doc_end = '\*/';
 268 my $doc_com = '\s*\*\s*';
 269 my $doc_decl = $doc_com.'(\w+)';
 270 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
 271 my $doc_content = $doc_com.'(.*)';
 272 my $doc_block = $doc_com.'DOC:\s*(.*)?';
 273
 274 my %constants;
 275 my %parameterdescs;
 276 my @parameterlist;
 277 my %sections;
 278 my @sectionlist;
 279
 280 my $contents = "";
 281 my $section_default = "Description";    # default section
 282 my $section_intro = "Introduction";
 283 my $section = $section_default;
 284 my $section_context = "Context";
 285
 286 my $undescribed = "-- undescribed --";
 287
 288 reset_state();
 289
 290 while ($ARGV[0] =~ m/^-(.*)/) {
 291     my $cmd = shift @ARGV;
 292     if ($cmd eq "-html") {
 293         $output_mode = "html";
 294         %highlights = %highlights_html;
 295         $blankline = $blankline_html;
 296     } elsif ($cmd eq "-man") {
 297         $output_mode = "man";
 298         %highlights = %highlights_man;
 299         $blankline = $blankline_man;
 300     } elsif ($cmd eq "-text") {
 301         $output_mode = "text";
 302         %highlights = %highlights_text;
 303         $blankline = $blankline_text;
 304     } elsif ($cmd eq "-docbook") {
 305         $output_mode = "xml";
 306         %highlights = %highlights_xml;
 307         $blankline = $blankline_xml;
 308     } elsif ($cmd eq "-gnome") {
 309         $output_mode = "gnome";
 310         %highlights = %highlights_gnome;
 311         $blankline = $blankline_gnome;
 312     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
 313         $modulename = shift @ARGV;
 314     } elsif ($cmd eq "-function") { # to only output specific functions
 315         $function_only = 1;
 316         $function = shift @ARGV;
 317         $function_table{$function} = 1;
 318     } elsif ($cmd eq "-nofunction") { # to only output specific functions
 319         $function_only = 2;
 320         $function = shift @ARGV;
 321         $function_table{$function} = 1;
 322     } elsif ($cmd eq "-v") {
 323         $verbose = 1;
 324     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 325         usage();
 326     } elsif ($cmd eq '-filelist') {
 327             $filelist = shift @ARGV;
 328     }
 329 }
 330
 331 # get kernel version from env
 332 sub get_kernel_version() {
 333     my $version;
 334
 335     if (defined($ENV{'KERNELVERSION'})) {
 336         $version = $ENV{'KERNELVERSION'};
 337     }
 338     return $version;
 339 }
 340 my $kernelversion = get_kernel_version();
 341
 342 # generate a sequence of code that will splice in highlighting information
 343 # using the s// operator.
 344 my $dohighlight = "";
 345 foreach my $pattern (keys %highlights) {
 346 #   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
 347     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
 348 }
 349
 350 ##
 351 # dumps section contents to arrays/hashes intended for that purpose.
 352 #
 353 sub dump_section {
 354     my $name = shift;
 355     my $contents = join "\n", @_;
 356
 357     if ($name =~ m/$type_constant/) {
 358         $name = $1;
 359 #       print STDERR "constant section '$1' = '$contents'\n";
 360         $constants{$name} = $contents;
 361     } elsif ($name =~ m/$type_param/) {
 362 #       print STDERR "parameter def '$1' = '$contents'\n";
 363         $name = $1;
 364         $parameterdescs{$name} = $contents;
 365     } else {
 366 #       print STDERR "other section '$name' = '$contents'\n";
 367         $sections{$name} = $contents;
 368         push @sectionlist, $name;
 369     }
 370 }
 371
 372 ##
 373 # output function
 374 #
 375 # parameterdescs, a hash.
 376 #  function => "function name"
 377 #  parameterlist => @list of parameters
 378 #  parameterdescs => %parameter descriptions
 379 #  sectionlist => @list of sections
 380 #  sections => %section descriptions
 381 #
 382
 383 sub output_highlight {
 384     my $contents = join "\n",@_;
 385     my $line;
 386
 387 #   DEBUG
 388 #   if (!defined $contents) {
 389 #       use Carp;
 390 #       confess "output_highlight got called with no args?\n";
 391 #   }
 392
 393 #   print STDERR "contents b4:$contents\n";
 394     eval $dohighlight;
 395     die $@ if $@;
 396     if ($output_mode eq "html") {
 397         $contents =~ s/\\\\//;
 398     }
 399 #   print STDERR "contents af:$contents\n";
 400
 401     foreach $line (split "\n", $contents) {
 402         if ($line eq ""){
 403             print $lineprefix, $blankline;
 404         } else {
 405             $line =~ s/\\\\\\/\&/g;
 406             print $lineprefix, $line;
 407         }
 408         print "\n";
 409     }
 410 }
 411
 412 #output sections in html
 413 sub output_section_html(%) {
 414     my %args = %{$_[0]};
 415     my $section;
 416
 417     foreach $section (@{$args{'sectionlist'}}) {
 418         print "<h3>$section</h3>\n";
 419         print "<blockquote>\n";
 420         output_highlight($args{'sections'}{$section});
 421         print "</blockquote>\n";
 422     }
 423 }
 424
 425 # output enum in html
 426 sub output_enum_html(%) {
 427     my %args = %{$_[0]};
 428     my ($parameter);
 429     my $count;
 430     print "<h2>enum ".$args{'enum'}."</h2>\n";
 431
 432     print "<b>enum ".$args{'enum'}."</b> {<br>\n";
 433     $count = 0;
 434     foreach $parameter (@{$args{'parameterlist'}}) {
 435         print " <b>".$parameter."</b>";
 436         if ($count != $#{$args{'parameterlist'}}) {
 437             $count++;
 438             print ",\n";
 439         }
 440         print "<br>";
 441     }
 442     print "};<br>\n";
 443
 444     print "<h3>Constants</h3>\n";
 445     print "<dl>\n";
 446     foreach $parameter (@{$args{'parameterlist'}}) {
 447         print "<dt><b>".$parameter."</b>\n";
 448         print "<dd>";
 449         output_highlight($args{'parameterdescs'}{$parameter});
 450     }
 451     print "</dl>\n";
 452     output_section_html(@_);
 453     print "<hr>\n";
 454 }
 455
 456 # output typedef in html
 457 sub output_typedef_html(%) {
 458     my %args = %{$_[0]};
 459     my ($parameter);
 460     my $count;
 461     print "<h2>typedef ".$args{'typedef'}."</h2>\n";
 462
 463     print "<b>typedef ".$args{'typedef'}."</b>\n";
 464     output_section_html(@_);
 465     print "<hr>\n";
 466 }
 467
 468 # output struct in html
 469 sub output_struct_html(%) {
 470     my %args = %{$_[0]};
 471     my ($parameter);
 472
 473     print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
 474     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
 475     foreach $parameter (@{$args{'parameterlist'}}) {
 476         if ($parameter =~ /^#/) {
 477                 print "$parameter<br>\n";
 478                 next;
 479         }
 480         my $parameter_name = $parameter;
 481         $parameter_name =~ s/\[.*//;
 482
 483         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 484         $type = $args{'parametertypes'}{$parameter};
 485         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 486             # pointer-to-function
 487             print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
 488         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 489             # bitfield
 490             print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
 491         } else {
 492             print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
 493         }
 494     }
 495     print "};<br>\n";
 496
 497     print "<h3>Members</h3>\n";
 498     print "<dl>\n";
 499     foreach $parameter (@{$args{'parameterlist'}}) {
 500         ($parameter =~ /^#/) && next;
 501
 502         my $parameter_name = $parameter;
 503         $parameter_name =~ s/\[.*//;
 504
 505         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 506         print "<dt><b>".$parameter."</b>\n";
 507         print "<dd>";
 508         output_highlight($args{'parameterdescs'}{$parameter_name});
 509     }
 510     print "</dl>\n";
 511     output_section_html(@_);
 512     print "<hr>\n";
 513 }
 514
 515 # output function in html
 516 sub output_function_html(%) {
 517     my %args = %{$_[0]};
 518     my ($parameter, $section);
 519     my $count;
 520
 521     print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
 522     print "<i>".$args{'functiontype'}."</i>\n";
 523     print "<b>".$args{'function'}."</b>\n";
 524     print "(";
 525     $count = 0;
 526     foreach $parameter (@{$args{'parameterlist'}}) {
 527         $type = $args{'parametertypes'}{$parameter};
 528         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 529             # pointer-to-function
 530             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
 531         } else {
 532             print "<i>".$type."</i> <b>".$parameter."</b>";
 533         }
 534         if ($count != $#{$args{'parameterlist'}}) {
 535             $count++;
 536             print ",\n";
 537         }
 538     }
 539     print ")\n";
 540
 541     print "<h3>Arguments</h3>\n";
 542     print "<dl>\n";
 543     foreach $parameter (@{$args{'parameterlist'}}) {
 544         my $parameter_name = $parameter;
 545         $parameter_name =~ s/\[.*//;
 546
 547         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 548         print "<dt><b>".$parameter."</b>\n";
 549         print "<dd>";
 550         output_highlight($args{'parameterdescs'}{$parameter_name});
 551     }
 552     print "</dl>\n";
 553     output_section_html(@_);
 554     print "<hr>\n";
 555 }
 556
 557 # output intro in html
 558 sub output_intro_html(%) {
 559     my %args = %{$_[0]};
 560     my ($parameter, $section);
 561     my $count;
 562
 563     foreach $section (@{$args{'sectionlist'}}) {
 564         print "<h3>$section</h3>\n";
 565         print "<ul>\n";
 566         output_highlight($args{'sections'}{$section});
 567         print "</ul>\n";
 568     }
 569     print "<hr>\n";
 570 }
 571
 572 sub output_section_xml(%) {
 573     my %args = %{$_[0]};
 574     my $section;
 575     # print out each section
 576     $lineprefix="   ";
 577     foreach $section (@{$args{'sectionlist'}}) {
 578         print "<refsect1>\n";
 579         print "<title>$section</title>\n";
 580         if ($section =~ m/EXAMPLE/i) {
 581             print "<informalexample><programlisting>\n";
 582         } else {
 583             print "<para>\n";
 584         }
 585         output_highlight($args{'sections'}{$section});
 586         if ($section =~ m/EXAMPLE/i) {
 587             print "</programlisting></informalexample>\n";
 588         } else {
 589             print "</para>\n";
 590         }
 591         print "</refsect1>\n";
 592     }
 593 }
 594
 595 # output function in XML DocBook
 596 sub output_function_xml(%) {
 597     my %args = %{$_[0]};
 598     my ($parameter, $section);
 599     my $count;
 600     my $id;
 601
 602     $id = "API-".$args{'function'};
 603     $id =~ s/[^A-Za-z0-9]/-/g;
 604
 605     print "<refentry id=\"$id\">\n";
 606     print "<refentryinfo>\n";
 607     print " <title>LINUX</title>\n";
 608     print " <productname>Kernel Hackers Manual</productname>\n";
 609     print " <date>$man_date</date>\n";
 610     print "</refentryinfo>\n";
 611     print "<refmeta>\n";
 612     print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
 613     print " <manvolnum>9</manvolnum>\n";
 614     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
 615     print "</refmeta>\n";
 616     print "<refnamediv>\n";
 617     print " <refname>".$args{'function'}."</refname>\n";
 618     print " <refpurpose>\n";
 619     print "  ";
 620     output_highlight ($args{'purpose'});
 621     print " </refpurpose>\n";
 622     print "</refnamediv>\n";
 623
 624     print "<refsynopsisdiv>\n";
 625     print " <title>Synopsis</title>\n";
 626     print "  <funcsynopsis><funcprototype>\n";
 627     print "   <funcdef>".$args{'functiontype'}." ";
 628     print "<function>".$args{'function'}." </function></funcdef>\n";
 629
 630     $count = 0;
 631     if ($#{$args{'parameterlist'}} >= 0) {
 632         foreach $parameter (@{$args{'parameterlist'}}) {
 633             $type = $args{'parametertypes'}{$parameter};
 634             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 635                 # pointer-to-function
 636                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
 637                 print "     <funcparams>$2</funcparams></paramdef>\n";
 638             } else {
 639                 print "   <paramdef>".$type;
 640                 print " <parameter>$parameter</parameter></paramdef>\n";
 641             }
 642         }
 643     } else {
 644         print "  <void/>\n";
 645     }
 646     print "  </funcprototype></funcsynopsis>\n";
 647     print "</refsynopsisdiv>\n";
 648
 649     # print parameters
 650     print "<refsect1>\n <title>Arguments</title>\n";
 651     if ($#{$args{'parameterlist'}} >= 0) {
 652         print " <variablelist>\n";
 653         foreach $parameter (@{$args{'parameterlist'}}) {
 654             my $parameter_name = $parameter;
 655             $parameter_name =~ s/\[.*//;
 656
 657             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 658             print "   <listitem>\n    <para>\n";
 659             $lineprefix="     ";
 660             output_highlight($args{'parameterdescs'}{$parameter_name});
 661             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 662         }
 663         print " </variablelist>\n";
 664     } else {
 665         print " <para>\n  None\n </para>\n";
 666     }
 667     print "</refsect1>\n";
 668
 669     output_section_xml(@_);
 670     print "</refentry>\n\n";
 671 }
 672
 673 # output struct in XML DocBook
 674 sub output_struct_xml(%) {
 675     my %args = %{$_[0]};
 676     my ($parameter, $section);
 677     my $id;
 678
 679     $id = "API-struct-".$args{'struct'};
 680     $id =~ s/[^A-Za-z0-9]/-/g;
 681
 682     print "<refentry id=\"$id\">\n";
 683     print "<refentryinfo>\n";
 684     print " <title>LINUX</title>\n";
 685     print " <productname>Kernel Hackers Manual</productname>\n";
 686     print " <date>$man_date</date>\n";
 687     print "</refentryinfo>\n";
 688     print "<refmeta>\n";
 689     print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
 690     print " <manvolnum>9</manvolnum>\n";
 691     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
 692     print "</refmeta>\n";
 693     print "<refnamediv>\n";
 694     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
 695     print " <refpurpose>\n";
 696     print "  ";
 697     output_highlight ($args{'purpose'});
 698     print " </refpurpose>\n";
 699     print "</refnamediv>\n";
 700
 701     print "<refsynopsisdiv>\n";
 702     print " <title>Synopsis</title>\n";
 703     print "  <programlisting>\n";
 704     print $args{'type'}." ".$args{'struct'}." {\n";
 705     foreach $parameter (@{$args{'parameterlist'}}) {
 706         if ($parameter =~ /^#/) {
 707             print "$parameter\n";
 708             next;
 709         }
 710
 711         my $parameter_name = $parameter;
 712         $parameter_name =~ s/\[.*//;
 713
 714         defined($args{'parameterdescs'}{$parameter_name}) || next;
 715         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 716         $type = $args{'parametertypes'}{$parameter};
 717         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 718             # pointer-to-function
 719             print "  $1 $parameter) ($2);\n";
 720         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 721             print "  $1 $parameter$2;\n";
 722         } else {
 723             print "  ".$type." ".$parameter.";\n";
 724         }
 725     }
 726     print "};";
 727     print "  </programlisting>\n";
 728     print "</refsynopsisdiv>\n";
 729
 730     print " <refsect1>\n";
 731     print "  <title>Members</title>\n";
 732
 733     print "  <variablelist>\n";
 734     foreach $parameter (@{$args{'parameterlist'}}) {
 735       ($parameter =~ /^#/) && next;
 736
 737       my $parameter_name = $parameter;
 738       $parameter_name =~ s/\[.*//;
 739
 740       defined($args{'parameterdescs'}{$parameter_name}) || next;
 741       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 742       print "    <varlistentry>";
 743       print "      <term>$parameter</term>\n";
 744       print "      <listitem><para>\n";
 745       output_highlight($args{'parameterdescs'}{$parameter_name});
 746       print "      </para></listitem>\n";
 747       print "    </varlistentry>\n";
 748     }
 749     print "  </variablelist>\n";
 750     print " </refsect1>\n";
 751
 752     output_section_xml(@_);
 753
 754     print "</refentry>\n\n";
 755 }
 756
 757 # output enum in XML DocBook
 758 sub output_enum_xml(%) {
 759     my %args = %{$_[0]};
 760     my ($parameter, $section);
 761     my $count;
 762     my $id;
 763
 764     $id = "API-enum-".$args{'enum'};
 765     $id =~ s/[^A-Za-z0-9]/-/g;
 766
 767     print "<refentry id=\"$id\">\n";
 768     print "<refentryinfo>\n";
 769     print " <title>LINUX</title>\n";
 770     print " <productname>Kernel Hackers Manual</productname>\n";
 771     print " <date>$man_date</date>\n";
 772     print "</refentryinfo>\n";
 773     print "<refmeta>\n";
 774     print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
 775     print " <manvolnum>9</manvolnum>\n";
 776     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
 777     print "</refmeta>\n";
 778     print "<refnamediv>\n";
 779     print " <refname>enum ".$args{'enum'}."</refname>\n";
 780     print " <refpurpose>\n";
 781     print "  ";
 782     output_highlight ($args{'purpose'});
 783     print " </refpurpose>\n";
 784     print "</refnamediv>\n";
 785
 786     print "<refsynopsisdiv>\n";
 787     print " <title>Synopsis</title>\n";
 788     print "  <programlisting>\n";
 789     print "enum ".$args{'enum'}." {\n";
 790     $count = 0;
 791     foreach $parameter (@{$args{'parameterlist'}}) {
 792         print "  $parameter";
 793         if ($count != $#{$args{'parameterlist'}}) {
 794             $count++;
 795             print ",";
 796         }
 797         print "\n";
 798     }
 799     print "};";
 800     print "  </programlisting>\n";
 801     print "</refsynopsisdiv>\n";
 802
 803     print "<refsect1>\n";
 804     print " <title>Constants</title>\n";
 805     print "  <variablelist>\n";
 806     foreach $parameter (@{$args{'parameterlist'}}) {
 807       my $parameter_name = $parameter;
 808       $parameter_name =~ s/\[.*//;
 809
 810       print "    <varlistentry>";
 811       print "      <term>$parameter</term>\n";
 812       print "      <listitem><para>\n";
 813       output_highlight($args{'parameterdescs'}{$parameter_name});
 814       print "      </para></listitem>\n";
 815       print "    </varlistentry>\n";
 816     }
 817     print "  </variablelist>\n";
 818     print "</refsect1>\n";
 819
 820     output_section_xml(@_);
 821
 822     print "</refentry>\n\n";
 823 }
 824
 825 # output typedef in XML DocBook
 826 sub output_typedef_xml(%) {
 827     my %args = %{$_[0]};
 828     my ($parameter, $section);
 829     my $id;
 830
 831     $id = "API-typedef-".$args{'typedef'};
 832     $id =~ s/[^A-Za-z0-9]/-/g;
 833
 834     print "<refentry id=\"$id\">\n";
 835     print "<refentryinfo>\n";
 836     print " <title>LINUX</title>\n";
 837     print " <productname>Kernel Hackers Manual</productname>\n";
 838     print " <date>$man_date</date>\n";
 839     print "</refentryinfo>\n";
 840     print "<refmeta>\n";
 841     print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
 842     print " <manvolnum>9</manvolnum>\n";
 843     print "</refmeta>\n";
 844     print "<refnamediv>\n";
 845     print " <refname>typedef ".$args{'typedef'}."</refname>\n";
 846     print " <refpurpose>\n";
 847     print "  ";
 848     output_highlight ($args{'purpose'});
 849     print " </refpurpose>\n";
 850     print "</refnamediv>\n";
 851
 852     print "<refsynopsisdiv>\n";
 853     print " <title>Synopsis</title>\n";
 854     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
 855     print "</refsynopsisdiv>\n";
 856
 857     output_section_xml(@_);
 858
 859     print "</refentry>\n\n";
 860 }
 861
 862 # output in XML DocBook
 863 sub output_intro_xml(%) {
 864     my %args = %{$_[0]};
 865     my ($parameter, $section);
 866     my $count;
 867
 868     my $id = $args{'module'};
 869     $id =~ s/[^A-Za-z0-9]/-/g;
 870
 871     # print out each section
 872     $lineprefix="   ";
 873     foreach $section (@{$args{'sectionlist'}}) {
 874         print "<refsect1>\n <title>$section</title>\n <para>\n";
 875         if ($section =~ m/EXAMPLE/i) {
 876             print "<example><para>\n";
 877         }
 878         output_highlight($args{'sections'}{$section});
 879         if ($section =~ m/EXAMPLE/i) {
 880             print "</para></example>\n";
 881         }
 882         print " </para>\n</refsect1>\n";
 883     }
 884
 885     print "\n\n";
 886 }
 887
 888 # output in XML DocBook
 889 sub output_function_gnome {
 890     my %args = %{$_[0]};
 891     my ($parameter, $section);
 892     my $count;
 893     my $id;
 894
 895     $id = $args{'module'}."-".$args{'function'};
 896     $id =~ s/[^A-Za-z0-9]/-/g;
 897
 898     print "<sect2>\n";
 899     print " <title id=\"$id\">".$args{'function'}."</title>\n";
 900
 901     print "  <funcsynopsis>\n";
 902     print "   <funcdef>".$args{'functiontype'}." ";
 903     print "<function>".$args{'function'}." ";
 904     print "</function></funcdef>\n";
 905
 906     $count = 0;
 907     if ($#{$args{'parameterlist'}} >= 0) {
 908         foreach $parameter (@{$args{'parameterlist'}}) {
 909             $type = $args{'parametertypes'}{$parameter};
 910             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 911                 # pointer-to-function
 912                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
 913                 print "     <funcparams>$2</funcparams></paramdef>\n";
 914             } else {
 915                 print "   <paramdef>".$type;
 916                 print " <parameter>$parameter</parameter></paramdef>\n";
 917             }
 918         }
 919     } else {
 920         print "  <void>\n";
 921     }
 922     print "  </funcsynopsis>\n";
 923     if ($#{$args{'parameterlist'}} >= 0) {
 924         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
 925         print "<tgroup cols=\"2\">\n";
 926         print "<colspec colwidth=\"2*\">\n";
 927         print "<colspec colwidth=\"8*\">\n";
 928         print "<tbody>\n";
 929         foreach $parameter (@{$args{'parameterlist'}}) {
 930             my $parameter_name = $parameter;
 931             $parameter_name =~ s/\[.*//;
 932
 933             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
 934             print "   <entry>\n";
 935             $lineprefix="     ";
 936             output_highlight($args{'parameterdescs'}{$parameter_name});
 937             print "    </entry></row>\n";
 938         }
 939         print " </tbody></tgroup></informaltable>\n";
 940     } else {
 941         print " <para>\n  None\n </para>\n";
 942     }
 943
 944     # print out each section
 945     $lineprefix="   ";
 946     foreach $section (@{$args{'sectionlist'}}) {
 947         print "<simplesect>\n <title>$section</title>\n";
 948         if ($section =~ m/EXAMPLE/i) {
 949             print "<example><programlisting>\n";
 950         } else {
 951         }
 952         print "<para>\n";
 953         output_highlight($args{'sections'}{$section});
 954         print "</para>\n";
 955         if ($section =~ m/EXAMPLE/i) {
 956             print "</programlisting></example>\n";
 957         } else {
 958         }
 959         print " </simplesect>\n";
 960     }
 961
 962     print "</sect2>\n\n";
 963 }
 964
 965 ##
 966 # output function in man
 967 sub output_function_man(%) {
 968     my %args = %{$_[0]};
 969     my ($parameter, $section);
 970     my $count;
 971
 972     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
 973
 974     print ".SH NAME\n";
 975     print $args{'function'}." \\- ".$args{'purpose'}."\n";
 976
 977     print ".SH SYNOPSIS\n";
 978     if ($args{'functiontype'} ne "") {
 979         print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
 980     } else {
 981         print ".B \"".$args{'function'}."\n";
 982     }
 983     $count = 0;
 984     my $parenth = "(";
 985     my $post = ",";
 986     foreach my $parameter (@{$args{'parameterlist'}}) {
 987         if ($count == $#{$args{'parameterlist'}}) {
 988             $post = ");";
 989         }
 990         $type = $args{'parametertypes'}{$parameter};
 991         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 992             # pointer-to-function
 993             print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
 994         } else {
 995             $type =~ s/([^\*])$/$1 /;
 996             print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
 997         }
 998         $count++;
 999         $parenth = "";
1000     }
1001
1002     print ".SH ARGUMENTS\n";
1003     foreach $parameter (@{$args{'parameterlist'}}) {
1004         my $parameter_name = $parameter;
1005         $parameter_name =~ s/\[.*//;
1006
1007         print ".IP \"".$parameter."\" 12\n";
1008         output_highlight($args{'parameterdescs'}{$parameter_name});
1009     }
1010     foreach $section (@{$args{'sectionlist'}}) {
1011         print ".SH \"", uc $section, "\"\n";
1012         output_highlight($args{'sections'}{$section});
1013     }
1014 }
1015
1016 ##
1017 # output enum in man
1018 sub output_enum_man(%) {
1019     my %args = %{$_[0]};
1020     my ($parameter, $section);
1021     my $count;
1022
1023     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1024
1025     print ".SH NAME\n";
1026     print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
1027
1028     print ".SH SYNOPSIS\n";
1029     print "enum ".$args{'enum'}." {\n";
1030     $count = 0;
1031     foreach my $parameter (@{$args{'parameterlist'}}) {
1032         print ".br\n.BI \"    $parameter\"\n";
1033         if ($count == $#{$args{'parameterlist'}}) {
1034             print "\n};\n";
1035             last;
1036         }
1037         else {
1038             print ", \n.br\n";
1039         }
1040         $count++;
1041     }
1042
1043     print ".SH Constants\n";
1044     foreach $parameter (@{$args{'parameterlist'}}) {
1045         my $parameter_name = $parameter;
1046         $parameter_name =~ s/\[.*//;
1047
1048         print ".IP \"".$parameter."\" 12\n";
1049         output_highlight($args{'parameterdescs'}{$parameter_name});
1050     }
1051     foreach $section (@{$args{'sectionlist'}}) {
1052         print ".SH \"$section\"\n";
1053         output_highlight($args{'sections'}{$section});
1054     }
1055 }
1056
1057 ##
1058 # output struct in man
1059 sub output_struct_man(%) {
1060     my %args = %{$_[0]};
1061     my ($parameter, $section);
1062
1063     print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
1064
1065     print ".SH NAME\n";
1066     print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
1067
1068     print ".SH SYNOPSIS\n";
1069     print $args{'type'}." ".$args{'struct'}." {\n.br\n";
1070
1071     foreach my $parameter (@{$args{'parameterlist'}}) {
1072         if ($parameter =~ /^#/) {
1073             print ".BI \"$parameter\"\n.br\n";
1074             next;
1075         }
1076         my $parameter_name = $parameter;
1077         $parameter_name =~ s/\[.*//;
1078
1079         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1080         $type = $args{'parametertypes'}{$parameter};
1081         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1082             # pointer-to-function
1083             print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
1084         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1085             # bitfield
1086             print ".BI \"    ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
1087         } else {
1088             $type =~ s/([^\*])$/$1 /;
1089             print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
1090         }
1091         print "\n.br\n";
1092     }
1093     print "};\n.br\n";
1094
1095     print ".SH Members\n";
1096     foreach $parameter (@{$args{'parameterlist'}}) {
1097         ($parameter =~ /^#/) && next;
1098
1099         my $parameter_name = $parameter;
1100         $parameter_name =~ s/\[.*//;
1101
1102         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1103         print ".IP \"".$parameter."\" 12\n";
1104         output_highlight($args{'parameterdescs'}{$parameter_name});
1105     }
1106     foreach $section (@{$args{'sectionlist'}}) {
1107         print ".SH \"$section\"\n";
1108         output_highlight($args{'sections'}{$section});
1109     }
1110 }
1111
1112 ##
1113 # output typedef in man
1114 sub output_typedef_man(%) {
1115     my %args = %{$_[0]};
1116     my ($parameter, $section);
1117
1118     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1119
1120     print ".SH NAME\n";
1121     print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1122
1123     foreach $section (@{$args{'sectionlist'}}) {
1124         print ".SH \"$section\"\n";
1125         output_highlight($args{'sections'}{$section});
1126     }
1127 }
1128
1129 sub output_intro_man(%) {
1130     my %args = %{$_[0]};
1131     my ($parameter, $section);
1132     my $count;
1133
1134     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1135
1136     foreach $section (@{$args{'sectionlist'}}) {
1137         print ".SH \"$section\"\n";
1138         output_highlight($args{'sections'}{$section});
1139     }
1140 }
1141
1142 ##
1143 # output in text
1144 sub output_function_text(%) {
1145     my %args = %{$_[0]};
1146     my ($parameter, $section);
1147     my $start;
1148
1149     print "Name:\n\n";
1150     print $args{'function'}." - ".$args{'purpose'}."\n";
1151
1152     print "\nSynopsis:\n\n";
1153     if ($args{'functiontype'} ne "") {
1154         $start = $args{'functiontype'}." ".$args{'function'}." (";
1155     } else {
1156         $start = $args{'function'}." (";
1157     }
1158     print $start;
1159
1160     my $count = 0;
1161     foreach my $parameter (@{$args{'parameterlist'}}) {
1162         $type = $args{'parametertypes'}{$parameter};
1163         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1164             # pointer-to-function
1165             print $1.$parameter.") (".$2;
1166         } else {
1167             print $type." ".$parameter;
1168         }
1169         if ($count != $#{$args{'parameterlist'}}) {
1170             $count++;
1171             print ",\n";
1172             print " " x length($start);
1173         } else {
1174             print ");\n\n";
1175         }
1176     }
1177
1178     print "Arguments:\n\n";
1179     foreach $parameter (@{$args{'parameterlist'}}) {
1180         my $parameter_name = $parameter;
1181         $parameter_name =~ s/\[.*//;
1182
1183         print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
1184     }
1185     output_section_text(@_);
1186 }
1187
1188 #output sections in text
1189 sub output_section_text(%) {
1190     my %args = %{$_[0]};
1191     my $section;
1192
1193     print "\n";
1194     foreach $section (@{$args{'sectionlist'}}) {
1195         print "$section:\n\n";
1196         output_highlight($args{'sections'}{$section});
1197     }
1198     print "\n\n";
1199 }
1200
1201 # output enum in text
1202 sub output_enum_text(%) {
1203     my %args = %{$_[0]};
1204     my ($parameter);
1205     my $count;
1206     print "Enum:\n\n";
1207
1208     print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
1209     print "enum ".$args{'enum'}." {\n";
1210     $count = 0;
1211     foreach $parameter (@{$args{'parameterlist'}}) {
1212         print "\t$parameter";
1213         if ($count != $#{$args{'parameterlist'}}) {
1214             $count++;
1215             print ",";
1216         }
1217         print "\n";
1218     }
1219     print "};\n\n";
1220
1221     print "Constants:\n\n";
1222     foreach $parameter (@{$args{'parameterlist'}}) {
1223         print "$parameter\n\t";
1224         print $args{'parameterdescs'}{$parameter}."\n";
1225     }
1226
1227     output_section_text(@_);
1228 }
1229
1230 # output typedef in text
1231 sub output_typedef_text(%) {
1232     my %args = %{$_[0]};
1233     my ($parameter);
1234     my $count;
1235     print "Typedef:\n\n";
1236
1237     print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
1238     output_section_text(@_);
1239 }
1240
1241 # output struct as text
1242 sub output_struct_text(%) {
1243     my %args = %{$_[0]};
1244     my ($parameter);
1245
1246     print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
1247     print $args{'type'}." ".$args{'struct'}." {\n";
1248     foreach $parameter (@{$args{'parameterlist'}}) {
1249         if ($parameter =~ /^#/) {
1250             print "$parameter\n";
1251             next;
1252         }
1253
1254         my $parameter_name = $parameter;
1255         $parameter_name =~ s/\[.*//;
1256
1257         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1258         $type = $args{'parametertypes'}{$parameter};
1259         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1260             # pointer-to-function
1261             print "\t$1 $parameter) ($2);\n";
1262         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1263             print "\t$1 $parameter$2;\n";
1264         } else {
1265             print "\t".$type." ".$parameter.";\n";
1266         }
1267     }
1268     print "};\n\n";
1269
1270     print "Members:\n\n";
1271     foreach $parameter (@{$args{'parameterlist'}}) {
1272         ($parameter =~ /^#/) && next;
1273
1274         my $parameter_name = $parameter;
1275         $parameter_name =~ s/\[.*//;
1276
1277         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1278         print "$parameter\n\t";
1279         print $args{'parameterdescs'}{$parameter_name}."\n";
1280     }
1281     print "\n";
1282     output_section_text(@_);
1283 }
1284
1285 sub output_intro_text(%) {
1286     my %args = %{$_[0]};
1287     my ($parameter, $section);
1288
1289     foreach $section (@{$args{'sectionlist'}}) {
1290         print " $section:\n";
1291         print "    -> ";
1292         output_highlight($args{'sections'}{$section});
1293     }
1294 }
1295
1296 ##
1297 # generic output function for all types (function, struct/union, typedef, enum);
1298 # calls the generated, variable output_ function name based on
1299 # functype and output_mode
1300 sub output_declaration {
1301     no strict 'refs';
1302     my $name = shift;
1303     my $functype = shift;
1304     my $func = "output_${functype}_$output_mode";
1305     if (($function_only==0) ||
1306         ( $function_only == 1 && defined($function_table{$name})) ||
1307         ( $function_only == 2 && !defined($function_table{$name})))
1308     {
1309         &$func(@_);
1310         $section_counter++;
1311     }
1312 }
1313
1314 ##
1315 # generic output function - calls the right one based on current output mode.
1316 sub output_intro {
1317     no strict 'refs';
1318     my $func = "output_intro_".$output_mode;
1319     &$func(@_);
1320     $section_counter++;
1321 }
1322
1323 ##
1324 # takes a declaration (struct, union, enum, typedef) and
1325 # invokes the right handler. NOT called for functions.
1326 sub dump_declaration($$) {
1327     no strict 'refs';
1328     my ($prototype, $file) = @_;
1329     my $func = "dump_".$decl_type;
1330     &$func(@_);
1331 }
1332
1333 sub dump_union($$) {
1334     dump_struct(@_);
1335 }
1336
1337 sub dump_struct($$) {
1338     my $x = shift;
1339     my $file = shift;
1340
1341     if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1342         $declaration_name = $2;
1343         my $members = $3;
1344
1345         # ignore embedded structs or unions
1346         $members =~ s/{.*?}//g;
1347
1348         # ignore members marked private:
1349         $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
1350         $members =~ s/\/\*.*?private:.*//gos;
1351         # strip comments:
1352         $members =~ s/\/\*.*?\*\///gos;
1353
1354         create_parameterlist($members, ';', $file);
1355
1356         output_declaration($declaration_name,
1357                            'struct',
1358                            {'struct' => $declaration_name,
1359                             'module' => $modulename,
1360                             'parameterlist' => \@parameterlist,
1361                             'parameterdescs' => \%parameterdescs,
1362                             'parametertypes' => \%parametertypes,
1363                             'sectionlist' => \@sectionlist,
1364                             'sections' => \%sections,
1365                             'purpose' => $declaration_purpose,
1366                             'type' => $decl_type
1367                            });
1368     }
1369     else {
1370         print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1371         ++$errors;
1372     }
1373 }
1374
1375 sub dump_enum($$) {
1376     my $x = shift;
1377     my $file = shift;
1378
1379     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1380     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1381         $declaration_name = $1;
1382         my $members = $2;
1383
1384         foreach my $arg (split ',', $members) {
1385             $arg =~ s/^\s*(\w+).*/$1/;
1386             push @parameterlist, $arg;
1387             if (!$parameterdescs{$arg}) {
1388                 $parameterdescs{$arg} = $undescribed;
1389                 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1390                     "not described in enum '$declaration_name'\n";
1391             }
1392
1393         }
1394
1395         output_declaration($declaration_name,
1396                            'enum',
1397                            {'enum' => $declaration_name,
1398                             'module' => $modulename,
1399                             'parameterlist' => \@parameterlist,
1400                             'parameterdescs' => \%parameterdescs,
1401                             'sectionlist' => \@sectionlist,
1402                             'sections' => \%sections,
1403                             'purpose' => $declaration_purpose
1404                            });
1405     }
1406     else {
1407         print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1408         ++$errors;
1409     }
1410 }
1411
1412 sub dump_typedef($$) {
1413     my $x = shift;
1414     my $file = shift;
1415
1416     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1417     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1418         $x =~ s/\(*.\)\s*;$/;/;
1419         $x =~ s/\[*.\]\s*;$/;/;
1420     }
1421
1422     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1423         $declaration_name = $1;
1424
1425         output_declaration($declaration_name,
1426                            'typedef',
1427                            {'typedef' => $declaration_name,
1428                             'module' => $modulename,
1429                             'sectionlist' => \@sectionlist,
1430                             'sections' => \%sections,
1431                             'purpose' => $declaration_purpose
1432                            });
1433     }
1434     else {
1435         print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1436         ++$errors;
1437     }
1438 }
1439
1440 sub create_parameterlist($$$) {
1441     my $args = shift;
1442     my $splitter = shift;
1443     my $file = shift;
1444     my $type;
1445     my $param;
1446
1447     # temporarily replace commas inside function pointer definition
1448     while ($args =~ /(\([^\),]+),/) {
1449         $args =~ s/(\([^\),]+),/$1#/g;
1450     }
1451
1452     foreach my $arg (split($splitter, $args)) {
1453         # strip comments
1454         $arg =~ s/\/\*.*\*\///;
1455         # strip leading/trailing spaces
1456         $arg =~ s/^\s*//;
1457         $arg =~ s/\s*$//;
1458         $arg =~ s/\s+/ /;
1459
1460         if ($arg =~ /^#/) {
1461             # Treat preprocessor directive as a typeless variable just to fill
1462             # corresponding data structures "correctly". Catch it later in
1463             # output_* subs.
1464             push_parameter($arg, "", $file);
1465         } elsif ($arg =~ m/\(.*\*/) {
1466             # pointer-to-function
1467             $arg =~ tr/#/,/;
1468             $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
1469             $param = $1;
1470             $type = $arg;
1471             $type =~ s/([^\(]+\(\*)$param/$1/;
1472             push_parameter($param, $type, $file);
1473         } elsif ($arg) {
1474             $arg =~ s/\s*:\s*/:/g;
1475             $arg =~ s/\s*\[/\[/g;
1476
1477             my @args = split('\s*,\s*', $arg);
1478             if ($args[0] =~ m/\*/) {
1479                 $args[0] =~ s/(\*+)\s*/ $1/;
1480             }
1481
1482             my @first_arg;
1483             if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1484                     shift @args;
1485                     push(@first_arg, split('\s+', $1));
1486                     push(@first_arg, $2);
1487             } else {
1488                     @first_arg = split('\s+', shift @args);
1489             }
1490
1491             unshift(@args, pop @first_arg);
1492             $type = join " ", @first_arg;
1493
1494             foreach $param (@args) {
1495                 if ($param =~ m/^(\*+)\s*(.*)/) {
1496                     push_parameter($2, "$type $1", $file);
1497                 }
1498                 elsif ($param =~ m/(.*?):(\d+)/) {
1499                     push_parameter($1, "$type:$2", $file)
1500                 }
1501                 else {
1502                     push_parameter($param, $type, $file);
1503                 }
1504             }
1505         }
1506     }
1507 }
1508
1509 sub push_parameter($$$) {
1510         my $param = shift;
1511         my $type = shift;
1512         my $file = shift;
1513         my $anon = 0;
1514
1515         my $param_name = $param;
1516         $param_name =~ s/\[.*//;
1517
1518         if ($type eq "" && $param =~ /\.\.\.$/)
1519         {
1520             $type="";
1521             $parameterdescs{$param} = "variable arguments";
1522         }
1523         elsif ($type eq "" && ($param eq "" or $param eq "void"))
1524         {
1525             $type="";
1526             $param="void";
1527             $parameterdescs{void} = "no arguments";
1528         }
1529         elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1530         # handle unnamed (anonymous) union or struct:
1531         {
1532                 $type = $param;
1533                 $param = "{unnamed_" . $param. "}";
1534                 $parameterdescs{$param} = "anonymous\n";
1535                 $anon = 1;
1536         }
1537
1538         # warn if parameter has no description
1539         # (but ignore ones starting with # as these are not parameters
1540         # but inline preprocessor statements);
1541         # also ignore unnamed structs/unions;
1542         if (!$anon) {
1543         if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1544
1545             $parameterdescs{$param_name} = $undescribed;
1546
1547             if (($type eq 'function') || ($type eq 'enum')) {
1548                 print STDERR "Warning(${file}:$.): Function parameter ".
1549                     "or member '$param' not " .
1550                     "described in '$declaration_name'\n";
1551             }
1552             print STDERR "Warning(${file}:$.):".
1553                          " No description found for parameter '$param'\n";
1554             ++$warnings;
1555         }
1556         }
1557
1558         push @parameterlist, $param;
1559         $parametertypes{$param} = $type;
1560 }
1561
1562 ##
1563 # takes a function prototype and the name of the current file being
1564 # processed and spits out all the details stored in the global
1565 # arrays/hashes.
1566 sub dump_function($$) {
1567     my $prototype = shift;
1568     my $file = shift;
1569
1570     $prototype =~ s/^static +//;
1571     $prototype =~ s/^extern +//;
1572     $prototype =~ s/^fastcall +//;
1573     $prototype =~ s/^asmlinkage +//;
1574     $prototype =~ s/^inline +//;
1575     $prototype =~ s/^__inline__ +//;
1576     $prototype =~ s/^__inline +//;
1577     $prototype =~ s/^__always_inline +//;
1578     $prototype =~ s/^noinline +//;
1579     $prototype =~ s/__devinit +//;
1580     $prototype =~ s/^#define\s+//; #ak added
1581     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1582
1583     # Yes, this truly is vile.  We are looking for:
1584     # 1. Return type (may be nothing if we're looking at a macro)
1585     # 2. Function name
1586     # 3. Function parameters.
1587     #
1588     # All the while we have to watch out for function pointer parameters
1589     # (which IIRC is what the two sections are for), C types (these
1590     # regexps don't even start to express all the possibilities), and
1591     # so on.
1592     #
1593     # If you mess with these regexps, it's a good idea to check that
1594     # the following functions' documentation still comes out right:
1595     # - parport_register_device (function pointer parameters)
1596     # - atomic_set (macro)
1597     # - pci_match_device, __copy_to_user (long return type)
1598
1599     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1600         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1601         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1602         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1603         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1604         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1605         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1606         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1607         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1608         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1609         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1610         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1611         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1612         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1613         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1614         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1615         $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
1616         $return_type = $1;
1617         $declaration_name = $2;
1618         my $args = $3;
1619
1620         create_parameterlist($args, ',', $file);
1621     } else {
1622         print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1623         ++$errors;
1624         return;
1625     }
1626
1627     output_declaration($declaration_name,
1628                        'function',
1629                        {'function' => $declaration_name,
1630                         'module' => $modulename,
1631                         'functiontype' => $return_type,
1632                         'parameterlist' => \@parameterlist,
1633                         'parameterdescs' => \%parameterdescs,
1634                         'parametertypes' => \%parametertypes,
1635                         'sectionlist' => \@sectionlist,
1636                         'sections' => \%sections,
1637                         'purpose' => $declaration_purpose
1638                        });
1639 }
1640
1641 sub process_file($);
1642
1643 # Read the file that maps relative names to absolute names for
1644 # separate source and object directories and for shadow trees.
1645 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
1646         my ($relname, $absname);
1647         while(<SOURCE_MAP>) {
1648                 chop();
1649                 ($relname, $absname) = (split())[0..1];
1650                 $relname =~ s:^/+::;
1651                 $source_map{$relname} = $absname;
1652         }
1653         close(SOURCE_MAP);
1654 }
1655
1656 if ($filelist) {
1657         open(FLIST,"<$filelist") or die "Can't open file list $filelist";
1658         while(<FLIST>) {
1659                 chop;
1660                 process_file($_);
1661         }
1662 }
1663
1664 foreach (@ARGV) {
1665     chomp;
1666     process_file($_);
1667 }
1668 if ($verbose && $errors) {
1669   print STDERR "$errors errors\n";
1670 }
1671 if ($verbose && $warnings) {
1672   print STDERR "$warnings warnings\n";
1673 }
1674
1675 exit($errors);
1676
1677 sub reset_state {
1678     $function = "";
1679     %constants = ();
1680     %parameterdescs = ();
1681     %parametertypes = ();
1682     @parameterlist = ();
1683     %sections = ();
1684     @sectionlist = ();
1685     $prototype = "";
1686
1687     $state = 0;
1688 }
1689
1690 sub process_state3_function($$) {
1691     my $x = shift;
1692     my $file = shift;
1693
1694     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
1695         # do nothing
1696     }
1697     elsif ($x =~ /([^\{]*)/) {
1698         $prototype .= $1;
1699     }
1700     if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
1701         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1702         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1703         $prototype =~ s@^\s+@@gos; # strip leading spaces
1704         dump_function($prototype,$file);
1705         reset_state();
1706     }
1707 }
1708
1709 sub process_state3_type($$) {
1710     my $x = shift;
1711     my $file = shift;
1712
1713     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1714     $x =~ s@^\s+@@gos; # strip leading spaces
1715     $x =~ s@\s+$@@gos; # strip trailing spaces
1716     if ($x =~ /^#/) {
1717         # To distinguish preprocessor directive from regular declaration later.
1718         $x .= ";";
1719     }
1720
1721     while (1) {
1722         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1723             $prototype .= $1 . $2;
1724             ($2 eq '{') && $brcount++;
1725             ($2 eq '}') && $brcount--;
1726             if (($2 eq ';') && ($brcount == 0)) {
1727                 dump_declaration($prototype,$file);
1728                 reset_state();
1729                 last;
1730             }
1731             $x = $3;
1732         } else {
1733             $prototype .= $x;
1734             last;
1735         }
1736     }
1737 }
1738
1739 # replace <, >, and &
1740 sub xml_escape($) {
1741         my $text = shift;
1742         if (($output_mode eq "text") || ($output_mode eq "man")) {
1743                 return $text;
1744         }
1745         $text =~ s/\&/\\\\\\amp;/g;
1746         $text =~ s/\</\\\\\\lt;/g;
1747         $text =~ s/\>/\\\\\\gt;/g;
1748         return $text;
1749 }
1750
1751 sub process_file($) {
1752     my $file;
1753     my $identifier;
1754     my $func;
1755     my $descr;
1756     my $initial_section_counter = $section_counter;
1757
1758     if (defined($ENV{'SRCTREE'})) {
1759         $file = "$ENV{'SRCTREE'}" . "/" . "@_";
1760     }
1761     else {
1762         $file = "@_";
1763     }
1764     if (defined($source_map{$file})) {
1765         $file = $source_map{$file};
1766     }
1767
1768     if (!open(IN,"<$file")) {
1769         print STDERR "Error: Cannot open file $file\n";
1770         ++$errors;
1771         return;
1772     }
1773
1774     $section_counter = 0;
1775     while (<IN>) {
1776         if ($state == 0) {
1777             if (/$doc_start/o) {
1778                 $state = 1;             # next line is always the function name
1779                 $in_doc_sect = 0;
1780             }
1781         } elsif ($state == 1) { # this line is the function name (always)
1782             if (/$doc_block/o) {
1783                 $state = 4;
1784                 $contents = "";
1785                 if ( $1 eq "" ) {
1786                         $section = $section_intro;
1787                 } else {
1788                         $section = $1;
1789                 }
1790             }
1791             elsif (/$doc_decl/o) {
1792                 $identifier = $1;
1793                 if (/\s*([\w\s]+?)\s*-/) {
1794                     $identifier = $1;
1795                 }
1796
1797                 $state = 2;
1798                 if (/-(.*)/) {
1799                     # strip leading/trailing/multiple spaces #RDD:T:
1800                     $descr= $1;
1801                     $descr =~ s/^\s*//;
1802                     $descr =~ s/\s*$//;
1803                     $descr =~ s/\s+/ /;
1804                     $declaration_purpose = xml_escape($descr);
1805                 } else {
1806                     $declaration_purpose = "";
1807                 }
1808                 if ($identifier =~ m/^struct/) {
1809                     $decl_type = 'struct';
1810                 } elsif ($identifier =~ m/^union/) {
1811                     $decl_type = 'union';
1812                 } elsif ($identifier =~ m/^enum/) {
1813                     $decl_type = 'enum';
1814                 } elsif ($identifier =~ m/^typedef/) {
1815                     $decl_type = 'typedef';
1816                 } else {
1817                     $decl_type = 'function';
1818                 }
1819
1820                 if ($verbose) {
1821                     print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
1822                 }
1823             } else {
1824                 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
1825                 " - I thought it was a doc line\n";
1826                 ++$warnings;
1827                 $state = 0;
1828             }
1829         } elsif ($state == 2) { # look for head: lines, and include content
1830             if (/$doc_sect/o) {
1831                 $newsection = $1;
1832                 $newcontents = $2;
1833
1834                 if ($contents ne "") {
1835                     if (!$in_doc_sect && $verbose) {
1836                         print STDERR "Warning(${file}:$.): contents before sections\n";
1837                         ++$warnings;
1838                     }
1839                     dump_section($section, xml_escape($contents));
1840                     $section = $section_default;
1841                 }
1842
1843                 $in_doc_sect = 1;
1844                 $contents = $newcontents;
1845                 if ($contents ne "") {
1846                     while ((substr($contents, 0, 1) eq " ") ||
1847                         substr($contents, 0, 1) eq "\t") {
1848                             $contents = substr($contents, 1);
1849                     }
1850                     $contents .= "\n";
1851                 }
1852                 $section = $newsection;
1853             } elsif (/$doc_end/) {
1854
1855                 if ($contents ne "") {
1856                     dump_section($section, xml_escape($contents));
1857                     $section = $section_default;
1858                     $contents = "";
1859                 }
1860
1861                 $prototype = "";
1862                 $state = 3;
1863                 $brcount = 0;
1864 #               print STDERR "end of doc comment, looking for prototype\n";
1865             } elsif (/$doc_content/) {
1866                 # miguel-style comment kludge, look for blank lines after
1867                 # @parameter line to signify start of description
1868                 if ($1 eq "" &&
1869                         ($section =~ m/^@/ || $section eq $section_context)) {
1870                     dump_section($section, xml_escape($contents));
1871                     $section = $section_default;
1872                     $contents = "";
1873                 } else {
1874                     $contents .= $1."\n";
1875                 }
1876             } else {
1877                 # i dont know - bad line?  ignore.
1878                 print STDERR "Warning(${file}:$.): bad line: $_";
1879                 ++$warnings;
1880             }
1881         } elsif ($state == 3) { # scanning for function '{' (end of prototype)
1882             if ($decl_type eq 'function') {
1883                 process_state3_function($_, $file);
1884             } else {
1885                 process_state3_type($_, $file);
1886             }
1887         } elsif ($state == 4) {
1888                 # Documentation block
1889                 if (/$doc_block/) {
1890                         dump_section($section, $contents);
1891                         output_intro({'sectionlist' => \@sectionlist,
1892                                       'sections' => \%sections });
1893                         $contents = "";
1894                         $function = "";
1895                         %constants = ();
1896                         %parameterdescs = ();
1897                         %parametertypes = ();
1898                         @parameterlist = ();
1899                         %sections = ();
1900                         @sectionlist = ();
1901                         $prototype = "";
1902                         if ( $1 eq "" ) {
1903                                 $section = $section_intro;
1904                         } else {
1905                                 $section = $1;
1906                         }
1907                 }
1908                 elsif (/$doc_end/)
1909                 {
1910                         dump_section($section, $contents);
1911                         output_intro({'sectionlist' => \@sectionlist,
1912                                       'sections' => \%sections });
1913                         $contents = "";
1914                         $function = "";
1915                         %constants = ();
1916                         %parameterdescs = ();
1917                         %parametertypes = ();
1918                         @parameterlist = ();
1919                         %sections = ();
1920                         @sectionlist = ();
1921                         $prototype = "";
1922                         $state = 0;
1923                 }
1924                 elsif (/$doc_content/)
1925                 {
1926                         if ( $1 eq "" )
1927                         {
1928                                 $contents .= $blankline;
1929                         }
1930                         else
1931                         {
1932                                 $contents .= $1 . "\n";
1933                         }
1934                 }
1935         }
1936     }
1937     if ($initial_section_counter == $section_counter) {
1938         print STDERR "Warning(${file}): no structured comments found\n";
1939         if ($output_mode eq "xml") {
1940             # The template wants at least one RefEntry here; make one.
1941             print "<refentry>\n";
1942             print " <refnamediv>\n";
1943             print "  <refname>\n";
1944             print "   ${file}\n";
1945             print "  </refname>\n";
1946             print "  <refpurpose>\n";
1947             print "   Document generation inconsistency\n";
1948             print "  </refpurpose>\n";
1949             print " </refnamediv>\n";
1950             print " <refsect1>\n";
1951             print "  <title>\n";
1952             print "   Oops\n";
1953             print "  </title>\n";
1954             print "  <warning>\n";
1955             print "   <para>\n";
1956             print "    The template for this document tried to insert\n";
1957             print "    the structured comment from the file\n";
1958             print "    <filename>${file}</filename> at this point,\n";
1959             print "    but none was found.\n";
1960             print "    This dummy section is inserted to allow\n";
1961             print "    generation to continue.\n";
1962             print "   </para>\n";
1963             print "  </warning>\n";
1964             print " </refsect1>\n";
1965             print "</refentry>\n";
1966         }
1967     }
1968 }