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