Merge tag 'docs-4.15-2' of git://git.lwn.net/linux
[muen/linux.git] / scripts / kernel-doc
1 #!/usr/bin/env perl
2
3 use warnings;
4 use strict;
5
6 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
7 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
8 ## Copyright (C) 2001  Simon Huggins                             ##
9 ## Copyright (C) 2005-2012  Randy Dunlap                         ##
10 ## Copyright (C) 2012  Dan Luedtke                               ##
11 ##                                                               ##
12 ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
13 ## Copyright (c) 2000 MontaVista Software, Inc.                  ##
14 ##                                                               ##
15 ## This software falls under the GNU General Public License.     ##
16 ## Please read the COPYING file for more information             ##
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 # 25/07/2012 - Added support for HTML5
41 # -- Dan Luedtke <mail@danrl.de>
42
43 sub usage {
44     my $message = <<"EOF";
45 Usage: $0 [OPTION ...] FILE ...
46
47 Read C language source or header FILEs, extract embedded documentation comments,
48 and print formatted documentation to standard output.
49
50 The documentation comments are identified by "/**" opening comment mark. See
51 Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
52
53 Output format selection (mutually exclusive):
54   -docbook              Output DocBook format.
55   -html                 Output HTML format.
56   -html5                Output HTML5 format.
57   -list                 Output symbol list format. This is for use by docproc.
58   -man                  Output troff manual page format. This is the default.
59   -rst                  Output reStructuredText format.
60   -text                 Output plain text format.
61   -none                 Do not output documentation, only warnings.
62
63 Output selection (mutually exclusive):
64   -export               Only output documentation for symbols that have been
65                         exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
66                         in any input FILE or -export-file FILE.
67   -internal             Only output documentation for symbols that have NOT been
68                         exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
69                         in any input FILE or -export-file FILE.
70   -function NAME        Only output documentation for the given function(s)
71                         or DOC: section title(s). All other functions and DOC:
72                         sections are ignored. May be specified multiple times.
73   -nofunction NAME      Do NOT output documentation for the given function(s);
74                         only output documentation for the other functions and
75                         DOC: sections. May be specified multiple times.
76
77 Output selection modifiers:
78   -no-doc-sections      Do not output DOC: sections.
79   -enable-lineno        Enable output of #define LINENO lines. Only works with
80                         reStructuredText format.
81   -export-file FILE     Specify an additional FILE in which to look for
82                         EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
83                         -export or -internal. May be specified multiple times.
84
85 Other parameters:
86   -v                    Verbose output, more warnings and other information.
87   -h                    Print this help.
88
89 EOF
90     print $message;
91     exit 1;
92 }
93
94 #
95 # format of comments.
96 # In the following table, (...)? signifies optional structure.
97 #                         (...)* signifies 0 or more structure elements
98 # /**
99 #  * function_name(:)? (- short description)?
100 # (* @parameterx: (description of parameter x)?)*
101 # (* a blank line)?
102 #  * (Description:)? (Description of function)?
103 #  * (section header: (section description)? )*
104 #  (*)?*/
105 #
106 # So .. the trivial example would be:
107 #
108 # /**
109 #  * my_function
110 #  */
111 #
112 # If the Description: header tag is omitted, then there must be a blank line
113 # after the last parameter specification.
114 # e.g.
115 # /**
116 #  * my_function - does my stuff
117 #  * @my_arg: its mine damnit
118 #  *
119 #  * Does my stuff explained.
120 #  */
121 #
122 #  or, could also use:
123 # /**
124 #  * my_function - does my stuff
125 #  * @my_arg: its mine damnit
126 #  * Description: Does my stuff explained.
127 #  */
128 # etc.
129 #
130 # Besides functions you can also write documentation for structs, unions,
131 # enums and typedefs. Instead of the function name you must write the name
132 # of the declaration;  the struct/union/enum/typedef must always precede
133 # the name. Nesting of declarations is not supported.
134 # Use the argument mechanism to document members or constants.
135 # e.g.
136 # /**
137 #  * struct my_struct - short description
138 #  * @a: first member
139 #  * @b: second member
140 #  *
141 #  * Longer description
142 #  */
143 # struct my_struct {
144 #     int a;
145 #     int b;
146 # /* private: */
147 #     int c;
148 # };
149 #
150 # All descriptions can be multiline, except the short function description.
151 #
152 # For really longs structs, you can also describe arguments inside the
153 # body of the struct.
154 # eg.
155 # /**
156 #  * struct my_struct - short description
157 #  * @a: first member
158 #  * @b: second member
159 #  *
160 #  * Longer description
161 #  */
162 # struct my_struct {
163 #     int a;
164 #     int b;
165 #     /**
166 #      * @c: This is longer description of C
167 #      *
168 #      * You can use paragraphs to describe arguments
169 #      * using this method.
170 #      */
171 #     int c;
172 # };
173 #
174 # This should be use only for struct/enum members.
175 #
176 # You can also add additional sections. When documenting kernel functions you
177 # should document the "Context:" of the function, e.g. whether the functions
178 # can be called form interrupts. Unlike other sections you can end it with an
179 # empty line.
180 # A non-void function should have a "Return:" section describing the return
181 # value(s).
182 # Example-sections should contain the string EXAMPLE so that they are marked
183 # appropriately in DocBook.
184 #
185 # Example:
186 # /**
187 #  * user_function - function that can only be called in user context
188 #  * @a: some argument
189 #  * Context: !in_interrupt()
190 #  *
191 #  * Some description
192 #  * Example:
193 #  *    user_function(22);
194 #  */
195 # ...
196 #
197 #
198 # All descriptive text is further processed, scanning for the following special
199 # patterns, which are highlighted appropriately.
200 #
201 # 'funcname()' - function
202 # '$ENVVAR' - environmental variable
203 # '&struct_name' - name of a structure (up to two words including 'struct')
204 # '&struct_name.member' - name of a structure member
205 # '@parameter' - name of a parameter
206 # '%CONST' - name of a constant.
207 # '``LITERAL``' - literal string without any spaces on it.
208
209 ## init lots of data
210
211 my $errors = 0;
212 my $warnings = 0;
213 my $anon_struct_union = 0;
214
215 # match expressions used to find embedded type information
216 my $type_constant = '\b``([^\`]+)``\b';
217 my $type_constant2 = '\%([-_\w]+)';
218 my $type_func = '(\w+)\(\)';
219 my $type_param = '\@(\w+(\.\.\.)?)';
220 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
221 my $type_env = '(\$\w+)';
222 my $type_enum = '\&(enum\s*([_\w]+))';
223 my $type_struct = '\&(struct\s*([_\w]+))';
224 my $type_typedef = '\&(typedef\s*([_\w]+))';
225 my $type_union = '\&(union\s*([_\w]+))';
226 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
227 my $type_fallback = '\&([_\w]+)';
228 my $type_enum_xml = '\&amp;(enum\s*([_\w]+))';
229 my $type_struct_xml = '\&amp;(struct\s*([_\w]+))';
230 my $type_typedef_xml = '\&amp;(typedef\s*([_\w]+))';
231 my $type_union_xml = '\&amp;(union\s*([_\w]+))';
232 my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
233 my $type_fallback_xml = '\&amp([_\w]+)';
234 my $type_member_func = $type_member . '\(\)';
235
236 # Output conversion substitutions.
237 #  One for each output format
238
239 # these work fairly well
240 my @highlights_html = (
241                        [$type_constant, "<i>\$1</i>"],
242                        [$type_constant2, "<i>\$1</i>"],
243                        [$type_func, "<b>\$1</b>"],
244                        [$type_enum_xml, "<i>\$1</i>"],
245                        [$type_struct_xml, "<i>\$1</i>"],
246                        [$type_typedef_xml, "<i>\$1</i>"],
247                        [$type_union_xml, "<i>\$1</i>"],
248                        [$type_env, "<b><i>\$1</i></b>"],
249                        [$type_param, "<tt><b>\$1</b></tt>"],
250                        [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"],
251                        [$type_fallback_xml, "<i>\$1</i>"]
252                       );
253 my $local_lt = "\\\\\\\\lt:";
254 my $local_gt = "\\\\\\\\gt:";
255 my $blankline_html = $local_lt . "p" . $local_gt;       # was "<p>"
256
257 # html version 5
258 my @highlights_html5 = (
259                         [$type_constant, "<span class=\"const\">\$1</span>"],
260                         [$type_constant2, "<span class=\"const\">\$1</span>"],
261                         [$type_func, "<span class=\"func\">\$1</span>"],
262                         [$type_enum_xml, "<span class=\"enum\">\$1</span>"],
263                         [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
264                         [$type_typedef_xml, "<span class=\"typedef\">\$1</span>"],
265                         [$type_union_xml, "<span class=\"union\">\$1</span>"],
266                         [$type_env, "<span class=\"env\">\$1</span>"],
267                         [$type_param, "<span class=\"param\">\$1</span>]"],
268                         [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"],
269                         [$type_fallback_xml, "<span class=\"struct\">\$1</span>"]
270                        );
271 my $blankline_html5 = $local_lt . "br /" . $local_gt;
272
273 # XML, docbook format
274 my @highlights_xml = (
275                       ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
276                       [$type_constant, "<constant>\$1</constant>"],
277                       [$type_constant2, "<constant>\$1</constant>"],
278                       [$type_enum_xml, "<type>\$1</type>"],
279                       [$type_struct_xml, "<structname>\$1</structname>"],
280                       [$type_typedef_xml, "<type>\$1</type>"],
281                       [$type_union_xml, "<structname>\$1</structname>"],
282                       [$type_param, "<parameter>\$1</parameter>"],
283                       [$type_func, "<function>\$1</function>"],
284                       [$type_env, "<envar>\$1</envar>"],
285                       [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
286                       [$type_fallback_xml, "<structname>\$1</structname>"]
287                      );
288 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
289
290 # gnome, docbook format
291 my @highlights_gnome = (
292                         [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
293                         [$type_constant2, "<replaceable class=\"option\">\$1</replaceable>"],
294                         [$type_func, "<function>\$1</function>"],
295                         [$type_enum, "<type>\$1</type>"],
296                         [$type_struct, "<structname>\$1</structname>"],
297                         [$type_typedef, "<type>\$1</type>"],
298                         [$type_union, "<structname>\$1</structname>"],
299                         [$type_env, "<envar>\$1</envar>"],
300                         [$type_param, "<parameter>\$1</parameter>" ],
301                         [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
302                         [$type_fallback, "<structname>\$1</structname>"]
303                        );
304 my $blankline_gnome = "</para><para>\n";
305
306 # these are pretty rough
307 my @highlights_man = (
308                       [$type_constant, "\$1"],
309                       [$type_constant2, "\$1"],
310                       [$type_func, "\\\\fB\$1\\\\fP"],
311                       [$type_enum, "\\\\fI\$1\\\\fP"],
312                       [$type_struct, "\\\\fI\$1\\\\fP"],
313                       [$type_typedef, "\\\\fI\$1\\\\fP"],
314                       [$type_union, "\\\\fI\$1\\\\fP"],
315                       [$type_param, "\\\\fI\$1\\\\fP"],
316                       [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
317                       [$type_fallback, "\\\\fI\$1\\\\fP"]
318                      );
319 my $blankline_man = "";
320
321 # text-mode
322 my @highlights_text = (
323                        [$type_constant, "\$1"],
324                        [$type_constant2, "\$1"],
325                        [$type_func, "\$1"],
326                        [$type_enum, "\$1"],
327                        [$type_struct, "\$1"],
328                        [$type_typedef, "\$1"],
329                        [$type_union, "\$1"],
330                        [$type_param, "\$1"],
331                        [$type_member, "\$1\$2\$3"],
332                        [$type_fallback, "\$1"]
333                       );
334 my $blankline_text = "";
335
336 # rst-mode
337 my @highlights_rst = (
338                        [$type_constant, "``\$1``"],
339                        [$type_constant2, "``\$1``"],
340                        # Note: need to escape () to avoid func matching later
341                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
342                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
343                        [$type_fp_param, "**\$1\\\\(\\\\)**"],
344                        [$type_func, "\\:c\\:func\\:`\$1()`"],
345                        [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
346                        [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
347                        [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
348                        [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
349                        # in rst this can refer to any type
350                        [$type_fallback, "\\:c\\:type\\:`\$1`"],
351                        [$type_param, "**\$1**"]
352                       );
353 my $blankline_rst = "\n";
354
355 # list mode
356 my @highlights_list = (
357                        [$type_constant, "\$1"],
358                        [$type_constant2, "\$1"],
359                        [$type_func, "\$1"],
360                        [$type_enum, "\$1"],
361                        [$type_struct, "\$1"],
362                        [$type_typedef, "\$1"],
363                        [$type_union, "\$1"],
364                        [$type_param, "\$1"],
365                        [$type_member, "\$1"],
366                        [$type_fallback, "\$1"]
367                       );
368 my $blankline_list = "";
369
370 # read arguments
371 if ($#ARGV == -1) {
372     usage();
373 }
374
375 my $kernelversion;
376 my $dohighlight = "";
377
378 my $verbose = 0;
379 my $output_mode = "man";
380 my $output_preformatted = 0;
381 my $no_doc_sections = 0;
382 my $enable_lineno = 0;
383 my @highlights = @highlights_man;
384 my $blankline = $blankline_man;
385 my $modulename = "Kernel API";
386
387 use constant {
388     OUTPUT_ALL          => 0, # output all symbols and doc sections
389     OUTPUT_INCLUDE      => 1, # output only specified symbols
390     OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
391     OUTPUT_EXPORTED     => 3, # output exported symbols
392     OUTPUT_INTERNAL     => 4, # output non-exported symbols
393 };
394 my $output_selection = OUTPUT_ALL;
395 my $show_not_found = 0;
396
397 my @export_file_list;
398
399 my @build_time;
400 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
401     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
402     @build_time = gmtime($seconds);
403 } else {
404     @build_time = localtime;
405 }
406
407 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
408                 'July', 'August', 'September', 'October',
409                 'November', 'December')[$build_time[4]] .
410   " " . ($build_time[5]+1900);
411
412 # Essentially these are globals.
413 # They probably want to be tidied up, made more localised or something.
414 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
415 # could cause "use of undefined value" or other bugs.
416 my ($function, %function_table, %parametertypes, $declaration_purpose);
417 my $declaration_start_line;
418 my ($type, $declaration_name, $return_type);
419 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
420
421 if (defined($ENV{'KBUILD_VERBOSE'})) {
422         $verbose = "$ENV{'KBUILD_VERBOSE'}";
423 }
424
425 # Generated docbook code is inserted in a template at a point where
426 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
427 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
428 # We keep track of number of generated entries and generate a dummy
429 # if needs be to ensure the expanded template can be postprocessed
430 # into html.
431 my $section_counter = 0;
432
433 my $lineprefix="";
434
435 # Parser states
436 use constant {
437     STATE_NORMAL        => 0, # normal code
438     STATE_NAME          => 1, # looking for function name
439     STATE_FIELD         => 2, # scanning field start
440     STATE_PROTO         => 3, # scanning prototype
441     STATE_DOCBLOCK      => 4, # documentation block
442     STATE_INLINE        => 5, # gathering documentation outside main block
443 };
444 my $state;
445 my $in_doc_sect;
446
447 # Inline documentation state
448 use constant {
449     STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
450     STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
451     STATE_INLINE_TEXT   => 2, # looking for member documentation
452     STATE_INLINE_END    => 3, # done
453     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
454                               # Spit a warning as it's not
455                               # proper kernel-doc and ignore the rest.
456 };
457 my $inline_doc_state;
458
459 #declaration types: can be
460 # 'function', 'struct', 'union', 'enum', 'typedef'
461 my $decl_type;
462
463 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
464 my $doc_end = '\*/';
465 my $doc_com = '\s*\*\s*';
466 my $doc_com_body = '\s*\* ?';
467 my $doc_decl = $doc_com . '(\w+)';
468 # @params and a strictly limited set of supported section names
469 my $doc_sect = $doc_com . 
470     '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
471 my $doc_content = $doc_com_body . '(.*)';
472 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
473 my $doc_inline_start = '^\s*/\*\*\s*$';
474 my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
475 my $doc_inline_end = '^\s*\*/\s*$';
476 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
477 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
478
479 my %parameterdescs;
480 my %parameterdesc_start_lines;
481 my @parameterlist;
482 my %sections;
483 my @sectionlist;
484 my %section_start_lines;
485 my $sectcheck;
486 my $struct_actual;
487
488 my $contents = "";
489 my $new_start_line = 0;
490
491 # the canonical section names. see also $doc_sect above.
492 my $section_default = "Description";    # default section
493 my $section_intro = "Introduction";
494 my $section = $section_default;
495 my $section_context = "Context";
496 my $section_return = "Return";
497
498 my $undescribed = "-- undescribed --";
499
500 reset_state();
501
502 while ($ARGV[0] =~ m/^-(.*)/) {
503     my $cmd = shift @ARGV;
504     if ($cmd eq "-html") {
505         $output_mode = "html";
506         @highlights = @highlights_html;
507         $blankline = $blankline_html;
508     } elsif ($cmd eq "-html5") {
509         $output_mode = "html5";
510         @highlights = @highlights_html5;
511         $blankline = $blankline_html5;
512     } elsif ($cmd eq "-man") {
513         $output_mode = "man";
514         @highlights = @highlights_man;
515         $blankline = $blankline_man;
516     } elsif ($cmd eq "-text") {
517         $output_mode = "text";
518         @highlights = @highlights_text;
519         $blankline = $blankline_text;
520     } elsif ($cmd eq "-rst") {
521         $output_mode = "rst";
522         @highlights = @highlights_rst;
523         $blankline = $blankline_rst;
524     } elsif ($cmd eq "-docbook") {
525         $output_mode = "xml";
526         @highlights = @highlights_xml;
527         $blankline = $blankline_xml;
528     } elsif ($cmd eq "-list") {
529         $output_mode = "list";
530         @highlights = @highlights_list;
531         $blankline = $blankline_list;
532     } elsif ($cmd eq "-gnome") {
533         $output_mode = "gnome";
534         @highlights = @highlights_gnome;
535         $blankline = $blankline_gnome;
536     } elsif ($cmd eq "-none") {
537         $output_mode = "none";
538     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
539         $modulename = shift @ARGV;
540     } elsif ($cmd eq "-function") { # to only output specific functions
541         $output_selection = OUTPUT_INCLUDE;
542         $function = shift @ARGV;
543         $function_table{$function} = 1;
544     } elsif ($cmd eq "-nofunction") { # output all except specific functions
545         $output_selection = OUTPUT_EXCLUDE;
546         $function = shift @ARGV;
547         $function_table{$function} = 1;
548     } elsif ($cmd eq "-export") { # only exported symbols
549         $output_selection = OUTPUT_EXPORTED;
550         %function_table = ();
551     } elsif ($cmd eq "-internal") { # only non-exported symbols
552         $output_selection = OUTPUT_INTERNAL;
553         %function_table = ();
554     } elsif ($cmd eq "-export-file") {
555         my $file = shift @ARGV;
556         push(@export_file_list, $file);
557     } elsif ($cmd eq "-v") {
558         $verbose = 1;
559     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
560         usage();
561     } elsif ($cmd eq '-no-doc-sections') {
562             $no_doc_sections = 1;
563     } elsif ($cmd eq '-enable-lineno') {
564             $enable_lineno = 1;
565     } elsif ($cmd eq '-show-not-found') {
566         $show_not_found = 1;
567     }
568 }
569
570 # continue execution near EOF;
571
572 # get kernel version from env
573 sub get_kernel_version() {
574     my $version = 'unknown kernel version';
575
576     if (defined($ENV{'KERNELVERSION'})) {
577         $version = $ENV{'KERNELVERSION'};
578     }
579     return $version;
580 }
581
582 #
583 sub print_lineno {
584     my $lineno = shift;
585     if ($enable_lineno && defined($lineno)) {
586         print "#define LINENO " . $lineno . "\n";
587     }
588 }
589 ##
590 # dumps section contents to arrays/hashes intended for that purpose.
591 #
592 sub dump_section {
593     my $file = shift;
594     my $name = shift;
595     my $contents = join "\n", @_;
596
597     if ($name =~ m/$type_param/) {
598         $name = $1;
599         $parameterdescs{$name} = $contents;
600         $sectcheck = $sectcheck . $name . " ";
601         $parameterdesc_start_lines{$name} = $new_start_line;
602         $new_start_line = 0;
603     } elsif ($name eq "@\.\.\.") {
604         $name = "...";
605         $parameterdescs{$name} = $contents;
606         $sectcheck = $sectcheck . $name . " ";
607         $parameterdesc_start_lines{$name} = $new_start_line;
608         $new_start_line = 0;
609     } else {
610         if (defined($sections{$name}) && ($sections{$name} ne "")) {
611             # Only warn on user specified duplicate section names.
612             if ($name ne $section_default) {
613                 print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
614                 ++$warnings;
615             }
616             $sections{$name} .= $contents;
617         } else {
618             $sections{$name} = $contents;
619             push @sectionlist, $name;
620             $section_start_lines{$name} = $new_start_line;
621             $new_start_line = 0;
622         }
623     }
624 }
625
626 ##
627 # dump DOC: section after checking that it should go out
628 #
629 sub dump_doc_section {
630     my $file = shift;
631     my $name = shift;
632     my $contents = join "\n", @_;
633
634     if ($no_doc_sections) {
635         return;
636     }
637
638     if (($output_selection == OUTPUT_ALL) ||
639         ($output_selection == OUTPUT_INCLUDE &&
640          defined($function_table{$name})) ||
641         ($output_selection == OUTPUT_EXCLUDE &&
642          !defined($function_table{$name})))
643     {
644         dump_section($file, $name, $contents);
645         output_blockhead({'sectionlist' => \@sectionlist,
646                           'sections' => \%sections,
647                           'module' => $modulename,
648                           'content-only' => ($output_selection != OUTPUT_ALL), });
649     }
650 }
651
652 ##
653 # output function
654 #
655 # parameterdescs, a hash.
656 #  function => "function name"
657 #  parameterlist => @list of parameters
658 #  parameterdescs => %parameter descriptions
659 #  sectionlist => @list of sections
660 #  sections => %section descriptions
661 #
662
663 sub output_highlight {
664     my $contents = join "\n",@_;
665     my $line;
666
667 #   DEBUG
668 #   if (!defined $contents) {
669 #       use Carp;
670 #       confess "output_highlight got called with no args?\n";
671 #   }
672
673     if ($output_mode eq "html" || $output_mode eq "html5" ||
674         $output_mode eq "xml") {
675         $contents = local_unescape($contents);
676         # convert data read & converted thru xml_escape() into &xyz; format:
677         $contents =~ s/\\\\\\/\&/g;
678     }
679 #   print STDERR "contents b4:$contents\n";
680     eval $dohighlight;
681     die $@ if $@;
682 #   print STDERR "contents af:$contents\n";
683
684 #   strip whitespaces when generating html5
685     if ($output_mode eq "html5") {
686         $contents =~ s/^\s+//;
687         $contents =~ s/\s+$//;
688     }
689     foreach $line (split "\n", $contents) {
690         if (! $output_preformatted) {
691             $line =~ s/^\s*//;
692         }
693         if ($line eq ""){
694             if (! $output_preformatted) {
695                 print $lineprefix, local_unescape($blankline);
696             }
697         } else {
698             $line =~ s/\\\\\\/\&/g;
699             if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
700                 print "\\&$line";
701             } else {
702                 print $lineprefix, $line;
703             }
704         }
705         print "\n";
706     }
707 }
708
709 # output sections in html
710 sub output_section_html(%) {
711     my %args = %{$_[0]};
712     my $section;
713
714     foreach $section (@{$args{'sectionlist'}}) {
715         print "<h3>$section</h3>\n";
716         print "<blockquote>\n";
717         output_highlight($args{'sections'}{$section});
718         print "</blockquote>\n";
719     }
720 }
721
722 # output enum in html
723 sub output_enum_html(%) {
724     my %args = %{$_[0]};
725     my ($parameter);
726     my $count;
727     print "<h2>enum " . $args{'enum'} . "</h2>\n";
728
729     print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
730     $count = 0;
731     foreach $parameter (@{$args{'parameterlist'}}) {
732         print " <b>" . $parameter . "</b>";
733         if ($count != $#{$args{'parameterlist'}}) {
734             $count++;
735             print ",\n";
736         }
737         print "<br>";
738     }
739     print "};<br>\n";
740
741     print "<h3>Constants</h3>\n";
742     print "<dl>\n";
743     foreach $parameter (@{$args{'parameterlist'}}) {
744         print "<dt><b>" . $parameter . "</b>\n";
745         print "<dd>";
746         output_highlight($args{'parameterdescs'}{$parameter});
747     }
748     print "</dl>\n";
749     output_section_html(@_);
750     print "<hr>\n";
751 }
752
753 # output typedef in html
754 sub output_typedef_html(%) {
755     my %args = %{$_[0]};
756     my ($parameter);
757     my $count;
758     print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
759
760     print "<b>typedef " . $args{'typedef'} . "</b>\n";
761     output_section_html(@_);
762     print "<hr>\n";
763 }
764
765 # output struct in html
766 sub output_struct_html(%) {
767     my %args = %{$_[0]};
768     my ($parameter);
769
770     print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
771     print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
772     foreach $parameter (@{$args{'parameterlist'}}) {
773         if ($parameter =~ /^#/) {
774                 print "$parameter<br>\n";
775                 next;
776         }
777         my $parameter_name = $parameter;
778         $parameter_name =~ s/\[.*//;
779
780         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
781         $type = $args{'parametertypes'}{$parameter};
782         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
783             # pointer-to-function
784             print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
785         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
786             # bitfield
787             print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
788         } else {
789             print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
790         }
791     }
792     print "};<br>\n";
793
794     print "<h3>Members</h3>\n";
795     print "<dl>\n";
796     foreach $parameter (@{$args{'parameterlist'}}) {
797         ($parameter =~ /^#/) && next;
798
799         my $parameter_name = $parameter;
800         $parameter_name =~ s/\[.*//;
801
802         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
803         print "<dt><b>" . $parameter . "</b>\n";
804         print "<dd>";
805         output_highlight($args{'parameterdescs'}{$parameter_name});
806     }
807     print "</dl>\n";
808     output_section_html(@_);
809     print "<hr>\n";
810 }
811
812 # output function in html
813 sub output_function_html(%) {
814     my %args = %{$_[0]};
815     my ($parameter, $section);
816     my $count;
817
818     print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
819     print "<i>" . $args{'functiontype'} . "</i>\n";
820     print "<b>" . $args{'function'} . "</b>\n";
821     print "(";
822     $count = 0;
823     foreach $parameter (@{$args{'parameterlist'}}) {
824         $type = $args{'parametertypes'}{$parameter};
825         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
826             # pointer-to-function
827             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
828         } else {
829             print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
830         }
831         if ($count != $#{$args{'parameterlist'}}) {
832             $count++;
833             print ",\n";
834         }
835     }
836     print ")\n";
837
838     print "<h3>Arguments</h3>\n";
839     print "<dl>\n";
840     foreach $parameter (@{$args{'parameterlist'}}) {
841         my $parameter_name = $parameter;
842         $parameter_name =~ s/\[.*//;
843
844         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
845         print "<dt><b>" . $parameter . "</b>\n";
846         print "<dd>";
847         output_highlight($args{'parameterdescs'}{$parameter_name});
848     }
849     print "</dl>\n";
850     output_section_html(@_);
851     print "<hr>\n";
852 }
853
854 # output DOC: block header in html
855 sub output_blockhead_html(%) {
856     my %args = %{$_[0]};
857     my ($parameter, $section);
858     my $count;
859
860     foreach $section (@{$args{'sectionlist'}}) {
861         print "<h3>$section</h3>\n";
862         print "<ul>\n";
863         output_highlight($args{'sections'}{$section});
864         print "</ul>\n";
865     }
866     print "<hr>\n";
867 }
868
869 # output sections in html5
870 sub output_section_html5(%) {
871     my %args = %{$_[0]};
872     my $section;
873
874     foreach $section (@{$args{'sectionlist'}}) {
875         print "<section>\n";
876         print "<h1>$section</h1>\n";
877         print "<p>\n";
878         output_highlight($args{'sections'}{$section});
879         print "</p>\n";
880         print "</section>\n";
881     }
882 }
883
884 # output enum in html5
885 sub output_enum_html5(%) {
886     my %args = %{$_[0]};
887     my ($parameter);
888     my $count;
889     my $html5id;
890
891     $html5id = $args{'enum'};
892     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
893     print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
894     print "<h1>enum " . $args{'enum'} . "</h1>\n";
895     print "<ol class=\"code\">\n";
896     print "<li>";
897     print "<span class=\"keyword\">enum</span> ";
898     print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
899     print "</li>\n";
900     $count = 0;
901     foreach $parameter (@{$args{'parameterlist'}}) {
902         print "<li class=\"indent\">";
903         print "<span class=\"param\">" . $parameter . "</span>";
904         if ($count != $#{$args{'parameterlist'}}) {
905             $count++;
906             print ",";
907         }
908         print "</li>\n";
909     }
910     print "<li>};</li>\n";
911     print "</ol>\n";
912
913     print "<section>\n";
914     print "<h1>Constants</h1>\n";
915     print "<dl>\n";
916     foreach $parameter (@{$args{'parameterlist'}}) {
917         print "<dt>" . $parameter . "</dt>\n";
918         print "<dd>";
919         output_highlight($args{'parameterdescs'}{$parameter});
920         print "</dd>\n";
921     }
922     print "</dl>\n";
923     print "</section>\n";
924     output_section_html5(@_);
925     print "</article>\n";
926 }
927
928 # output typedef in html5
929 sub output_typedef_html5(%) {
930     my %args = %{$_[0]};
931     my ($parameter);
932     my $count;
933     my $html5id;
934
935     $html5id = $args{'typedef'};
936     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
937     print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
938     print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
939
940     print "<ol class=\"code\">\n";
941     print "<li>";
942     print "<span class=\"keyword\">typedef</span> ";
943     print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
944     print "</li>\n";
945     print "</ol>\n";
946     output_section_html5(@_);
947     print "</article>\n";
948 }
949
950 # output struct in html5
951 sub output_struct_html5(%) {
952     my %args = %{$_[0]};
953     my ($parameter);
954     my $html5id;
955
956     $html5id = $args{'struct'};
957     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
958     print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
959     print "<hgroup>\n";
960     print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
961     print "<h2>". $args{'purpose'} . "</h2>\n";
962     print "</hgroup>\n";
963     print "<ol class=\"code\">\n";
964     print "<li>";
965     print "<span class=\"type\">" . $args{'type'} . "</span> ";
966     print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
967     print "</li>\n";
968     foreach $parameter (@{$args{'parameterlist'}}) {
969         print "<li class=\"indent\">";
970         if ($parameter =~ /^#/) {
971                 print "<span class=\"param\">" . $parameter ."</span>\n";
972                 print "</li>\n";
973                 next;
974         }
975         my $parameter_name = $parameter;
976         $parameter_name =~ s/\[.*//;
977
978         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
979         $type = $args{'parametertypes'}{$parameter};
980         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
981             # pointer-to-function
982             print "<span class=\"type\">$1</span> ";
983             print "<span class=\"param\">$parameter</span>";
984             print "<span class=\"type\">)</span> ";
985             print "(<span class=\"args\">$2</span>);";
986         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
987             # bitfield
988             print "<span class=\"type\">$1</span> ";
989             print "<span class=\"param\">$parameter</span>";
990             print "<span class=\"bits\">$2</span>;";
991         } else {
992             print "<span class=\"type\">$type</span> ";
993             print "<span class=\"param\">$parameter</span>;";
994         }
995         print "</li>\n";
996     }
997     print "<li>};</li>\n";
998     print "</ol>\n";
999
1000     print "<section>\n";
1001     print "<h1>Members</h1>\n";
1002     print "<dl>\n";
1003     foreach $parameter (@{$args{'parameterlist'}}) {
1004         ($parameter =~ /^#/) && next;
1005
1006         my $parameter_name = $parameter;
1007         $parameter_name =~ s/\[.*//;
1008
1009         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1010         print "<dt>" . $parameter . "</dt>\n";
1011         print "<dd>";
1012         output_highlight($args{'parameterdescs'}{$parameter_name});
1013         print "</dd>\n";
1014     }
1015     print "</dl>\n";
1016     print "</section>\n";
1017     output_section_html5(@_);
1018     print "</article>\n";
1019 }
1020
1021 # output function in html5
1022 sub output_function_html5(%) {
1023     my %args = %{$_[0]};
1024     my ($parameter, $section);
1025     my $count;
1026     my $html5id;
1027
1028     $html5id = $args{'function'};
1029     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1030     print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
1031     print "<hgroup>\n";
1032     print "<h1>" . $args{'function'} . "</h1>";
1033     print "<h2>" . $args{'purpose'} . "</h2>\n";
1034     print "</hgroup>\n";
1035     print "<ol class=\"code\">\n";
1036     print "<li>";
1037     print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
1038     print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
1039     print "</li>";
1040     $count = 0;
1041     foreach $parameter (@{$args{'parameterlist'}}) {
1042         print "<li class=\"indent\">";
1043         $type = $args{'parametertypes'}{$parameter};
1044         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1045             # pointer-to-function
1046             print "<span class=\"type\">$1</span> ";
1047             print "<span class=\"param\">$parameter</span>";
1048             print "<span class=\"type\">)</span> ";
1049             print "(<span class=\"args\">$2</span>)";
1050         } else {
1051             print "<span class=\"type\">$type</span> ";
1052             print "<span class=\"param\">$parameter</span>";
1053         }
1054         if ($count != $#{$args{'parameterlist'}}) {
1055             $count++;
1056             print ",";
1057         }
1058         print "</li>\n";
1059     }
1060     print "<li>)</li>\n";
1061     print "</ol>\n";
1062
1063     print "<section>\n";
1064     print "<h1>Arguments</h1>\n";
1065     print "<p>\n";
1066     print "<dl>\n";
1067     foreach $parameter (@{$args{'parameterlist'}}) {
1068         my $parameter_name = $parameter;
1069         $parameter_name =~ s/\[.*//;
1070
1071         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1072         print "<dt>" . $parameter . "</dt>\n";
1073         print "<dd>";
1074         output_highlight($args{'parameterdescs'}{$parameter_name});
1075         print "</dd>\n";
1076     }
1077     print "</dl>\n";
1078     print "</section>\n";
1079     output_section_html5(@_);
1080     print "</article>\n";
1081 }
1082
1083 # output DOC: block header in html5
1084 sub output_blockhead_html5(%) {
1085     my %args = %{$_[0]};
1086     my ($parameter, $section);
1087     my $count;
1088     my $html5id;
1089
1090     foreach $section (@{$args{'sectionlist'}}) {
1091         $html5id = $section;
1092         $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1093         print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
1094         print "<h1>$section</h1>\n";
1095         print "<p>\n";
1096         output_highlight($args{'sections'}{$section});
1097         print "</p>\n";
1098     }
1099     print "</article>\n";
1100 }
1101
1102 sub output_section_xml(%) {
1103     my %args = %{$_[0]};
1104     my $section;
1105     # print out each section
1106     $lineprefix="   ";
1107     foreach $section (@{$args{'sectionlist'}}) {
1108         print "<refsect1>\n";
1109         print "<title>$section</title>\n";
1110         if ($section =~ m/EXAMPLE/i) {
1111             print "<informalexample><programlisting>\n";
1112             $output_preformatted = 1;
1113         } else {
1114             print "<para>\n";
1115         }
1116         output_highlight($args{'sections'}{$section});
1117         $output_preformatted = 0;
1118         if ($section =~ m/EXAMPLE/i) {
1119             print "</programlisting></informalexample>\n";
1120         } else {
1121             print "</para>\n";
1122         }
1123         print "</refsect1>\n";
1124     }
1125 }
1126
1127 # output function in XML DocBook
1128 sub output_function_xml(%) {
1129     my %args = %{$_[0]};
1130     my ($parameter, $section);
1131     my $count;
1132     my $id;
1133
1134     $id = "API-" . $args{'function'};
1135     $id =~ s/[^A-Za-z0-9]/-/g;
1136
1137     print "<refentry id=\"$id\">\n";
1138     print "<refentryinfo>\n";
1139     print " <title>LINUX</title>\n";
1140     print " <productname>Kernel Hackers Manual</productname>\n";
1141     print " <date>$man_date</date>\n";
1142     print "</refentryinfo>\n";
1143     print "<refmeta>\n";
1144     print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
1145     print " <manvolnum>9</manvolnum>\n";
1146     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1147     print "</refmeta>\n";
1148     print "<refnamediv>\n";
1149     print " <refname>" . $args{'function'} . "</refname>\n";
1150     print " <refpurpose>\n";
1151     print "  ";
1152     output_highlight ($args{'purpose'});
1153     print " </refpurpose>\n";
1154     print "</refnamediv>\n";
1155
1156     print "<refsynopsisdiv>\n";
1157     print " <title>Synopsis</title>\n";
1158     print "  <funcsynopsis><funcprototype>\n";
1159     print "   <funcdef>" . $args{'functiontype'} . " ";
1160     print "<function>" . $args{'function'} . " </function></funcdef>\n";
1161
1162     $count = 0;
1163     if ($#{$args{'parameterlist'}} >= 0) {
1164         foreach $parameter (@{$args{'parameterlist'}}) {
1165             $type = $args{'parametertypes'}{$parameter};
1166             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1167                 # pointer-to-function
1168                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
1169                 print "     <funcparams>$2</funcparams></paramdef>\n";
1170             } else {
1171                 print "   <paramdef>" . $type;
1172                 print " <parameter>$parameter</parameter></paramdef>\n";
1173             }
1174         }
1175     } else {
1176         print "  <void/>\n";
1177     }
1178     print "  </funcprototype></funcsynopsis>\n";
1179     print "</refsynopsisdiv>\n";
1180
1181     # print parameters
1182     print "<refsect1>\n <title>Arguments</title>\n";
1183     if ($#{$args{'parameterlist'}} >= 0) {
1184         print " <variablelist>\n";
1185         foreach $parameter (@{$args{'parameterlist'}}) {
1186             my $parameter_name = $parameter;
1187             $parameter_name =~ s/\[.*//;
1188             $type = $args{'parametertypes'}{$parameter};
1189
1190             print "  <varlistentry>\n   <term><parameter>$type $parameter</parameter></term>\n";
1191             print "   <listitem>\n    <para>\n";
1192             $lineprefix="     ";
1193             output_highlight($args{'parameterdescs'}{$parameter_name});
1194             print "    </para>\n   </listitem>\n  </varlistentry>\n";
1195         }
1196         print " </variablelist>\n";
1197     } else {
1198         print " <para>\n  None\n </para>\n";
1199     }
1200     print "</refsect1>\n";
1201
1202     output_section_xml(@_);
1203     print "</refentry>\n\n";
1204 }
1205
1206 # output struct in XML DocBook
1207 sub output_struct_xml(%) {
1208     my %args = %{$_[0]};
1209     my ($parameter, $section);
1210     my $id;
1211
1212     $id = "API-struct-" . $args{'struct'};
1213     $id =~ s/[^A-Za-z0-9]/-/g;
1214
1215     print "<refentry id=\"$id\">\n";
1216     print "<refentryinfo>\n";
1217     print " <title>LINUX</title>\n";
1218     print " <productname>Kernel Hackers Manual</productname>\n";
1219     print " <date>$man_date</date>\n";
1220     print "</refentryinfo>\n";
1221     print "<refmeta>\n";
1222     print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1223     print " <manvolnum>9</manvolnum>\n";
1224     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1225     print "</refmeta>\n";
1226     print "<refnamediv>\n";
1227     print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1228     print " <refpurpose>\n";
1229     print "  ";
1230     output_highlight ($args{'purpose'});
1231     print " </refpurpose>\n";
1232     print "</refnamediv>\n";
1233
1234     print "<refsynopsisdiv>\n";
1235     print " <title>Synopsis</title>\n";
1236     print "  <programlisting>\n";
1237     print $args{'type'} . " " . $args{'struct'} . " {\n";
1238     foreach $parameter (@{$args{'parameterlist'}}) {
1239         if ($parameter =~ /^#/) {
1240             my $prm = $parameter;
1241             # convert data read & converted thru xml_escape() into &xyz; format:
1242             # This allows us to have #define macros interspersed in a struct.
1243             $prm =~ s/\\\\\\/\&/g;
1244             print "$prm\n";
1245             next;
1246         }
1247
1248         my $parameter_name = $parameter;
1249         $parameter_name =~ s/\[.*//;
1250
1251         defined($args{'parameterdescs'}{$parameter_name}) || next;
1252         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1253         $type = $args{'parametertypes'}{$parameter};
1254         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1255             # pointer-to-function
1256             print "  $1 $parameter) ($2);\n";
1257         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1258             # bitfield
1259             print "  $1 $parameter$2;\n";
1260         } else {
1261             print "  " . $type . " " . $parameter . ";\n";
1262         }
1263     }
1264     print "};";
1265     print "  </programlisting>\n";
1266     print "</refsynopsisdiv>\n";
1267
1268     print " <refsect1>\n";
1269     print "  <title>Members</title>\n";
1270
1271     if ($#{$args{'parameterlist'}} >= 0) {
1272     print "  <variablelist>\n";
1273     foreach $parameter (@{$args{'parameterlist'}}) {
1274       ($parameter =~ /^#/) && next;
1275
1276       my $parameter_name = $parameter;
1277       $parameter_name =~ s/\[.*//;
1278
1279       defined($args{'parameterdescs'}{$parameter_name}) || next;
1280       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1281       $type = $args{'parametertypes'}{$parameter};
1282       print "    <varlistentry>";
1283       print "      <term><literal>$type $parameter</literal></term>\n";
1284       print "      <listitem><para>\n";
1285       output_highlight($args{'parameterdescs'}{$parameter_name});
1286       print "      </para></listitem>\n";
1287       print "    </varlistentry>\n";
1288     }
1289     print "  </variablelist>\n";
1290     } else {
1291         print " <para>\n  None\n </para>\n";
1292     }
1293     print " </refsect1>\n";
1294
1295     output_section_xml(@_);
1296
1297     print "</refentry>\n\n";
1298 }
1299
1300 # output enum in XML DocBook
1301 sub output_enum_xml(%) {
1302     my %args = %{$_[0]};
1303     my ($parameter, $section);
1304     my $count;
1305     my $id;
1306
1307     $id = "API-enum-" . $args{'enum'};
1308     $id =~ s/[^A-Za-z0-9]/-/g;
1309
1310     print "<refentry id=\"$id\">\n";
1311     print "<refentryinfo>\n";
1312     print " <title>LINUX</title>\n";
1313     print " <productname>Kernel Hackers Manual</productname>\n";
1314     print " <date>$man_date</date>\n";
1315     print "</refentryinfo>\n";
1316     print "<refmeta>\n";
1317     print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1318     print " <manvolnum>9</manvolnum>\n";
1319     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1320     print "</refmeta>\n";
1321     print "<refnamediv>\n";
1322     print " <refname>enum " . $args{'enum'} . "</refname>\n";
1323     print " <refpurpose>\n";
1324     print "  ";
1325     output_highlight ($args{'purpose'});
1326     print " </refpurpose>\n";
1327     print "</refnamediv>\n";
1328
1329     print "<refsynopsisdiv>\n";
1330     print " <title>Synopsis</title>\n";
1331     print "  <programlisting>\n";
1332     print "enum " . $args{'enum'} . " {\n";
1333     $count = 0;
1334     foreach $parameter (@{$args{'parameterlist'}}) {
1335         print "  $parameter";
1336         if ($count != $#{$args{'parameterlist'}}) {
1337             $count++;
1338             print ",";
1339         }
1340         print "\n";
1341     }
1342     print "};";
1343     print "  </programlisting>\n";
1344     print "</refsynopsisdiv>\n";
1345
1346     print "<refsect1>\n";
1347     print " <title>Constants</title>\n";
1348     print "  <variablelist>\n";
1349     foreach $parameter (@{$args{'parameterlist'}}) {
1350       my $parameter_name = $parameter;
1351       $parameter_name =~ s/\[.*//;
1352
1353       print "    <varlistentry>";
1354       print "      <term>$parameter</term>\n";
1355       print "      <listitem><para>\n";
1356       output_highlight($args{'parameterdescs'}{$parameter_name});
1357       print "      </para></listitem>\n";
1358       print "    </varlistentry>\n";
1359     }
1360     print "  </variablelist>\n";
1361     print "</refsect1>\n";
1362
1363     output_section_xml(@_);
1364
1365     print "</refentry>\n\n";
1366 }
1367
1368 # output typedef in XML DocBook
1369 sub output_typedef_xml(%) {
1370     my %args = %{$_[0]};
1371     my ($parameter, $section);
1372     my $id;
1373
1374     $id = "API-typedef-" . $args{'typedef'};
1375     $id =~ s/[^A-Za-z0-9]/-/g;
1376
1377     print "<refentry id=\"$id\">\n";
1378     print "<refentryinfo>\n";
1379     print " <title>LINUX</title>\n";
1380     print " <productname>Kernel Hackers Manual</productname>\n";
1381     print " <date>$man_date</date>\n";
1382     print "</refentryinfo>\n";
1383     print "<refmeta>\n";
1384     print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1385     print " <manvolnum>9</manvolnum>\n";
1386     print "</refmeta>\n";
1387     print "<refnamediv>\n";
1388     print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1389     print " <refpurpose>\n";
1390     print "  ";
1391     output_highlight ($args{'purpose'});
1392     print " </refpurpose>\n";
1393     print "</refnamediv>\n";
1394
1395     print "<refsynopsisdiv>\n";
1396     print " <title>Synopsis</title>\n";
1397     print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1398     print "</refsynopsisdiv>\n";
1399
1400     output_section_xml(@_);
1401
1402     print "</refentry>\n\n";
1403 }
1404
1405 # output in XML DocBook
1406 sub output_blockhead_xml(%) {
1407     my %args = %{$_[0]};
1408     my ($parameter, $section);
1409     my $count;
1410
1411     my $id = $args{'module'};
1412     $id =~ s/[^A-Za-z0-9]/-/g;
1413
1414     # print out each section
1415     $lineprefix="   ";
1416     foreach $section (@{$args{'sectionlist'}}) {
1417         if (!$args{'content-only'}) {
1418                 print "<refsect1>\n <title>$section</title>\n";
1419         }
1420         if ($section =~ m/EXAMPLE/i) {
1421             print "<example><para>\n";
1422             $output_preformatted = 1;
1423         } else {
1424             print "<para>\n";
1425         }
1426         output_highlight($args{'sections'}{$section});
1427         $output_preformatted = 0;
1428         if ($section =~ m/EXAMPLE/i) {
1429             print "</para></example>\n";
1430         } else {
1431             print "</para>";
1432         }
1433         if (!$args{'content-only'}) {
1434                 print "\n</refsect1>\n";
1435         }
1436     }
1437
1438     print "\n\n";
1439 }
1440
1441 # output in XML DocBook
1442 sub output_function_gnome {
1443     my %args = %{$_[0]};
1444     my ($parameter, $section);
1445     my $count;
1446     my $id;
1447
1448     $id = $args{'module'} . "-" . $args{'function'};
1449     $id =~ s/[^A-Za-z0-9]/-/g;
1450
1451     print "<sect2>\n";
1452     print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1453
1454     print "  <funcsynopsis>\n";
1455     print "   <funcdef>" . $args{'functiontype'} . " ";
1456     print "<function>" . $args{'function'} . " ";
1457     print "</function></funcdef>\n";
1458
1459     $count = 0;
1460     if ($#{$args{'parameterlist'}} >= 0) {
1461         foreach $parameter (@{$args{'parameterlist'}}) {
1462             $type = $args{'parametertypes'}{$parameter};
1463             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1464                 # pointer-to-function
1465                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
1466                 print "     <funcparams>$2</funcparams></paramdef>\n";
1467             } else {
1468                 print "   <paramdef>" . $type;
1469                 print " <parameter>$parameter</parameter></paramdef>\n";
1470             }
1471         }
1472     } else {
1473         print "  <void>\n";
1474     }
1475     print "  </funcsynopsis>\n";
1476     if ($#{$args{'parameterlist'}} >= 0) {
1477         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1478         print "<tgroup cols=\"2\">\n";
1479         print "<colspec colwidth=\"2*\">\n";
1480         print "<colspec colwidth=\"8*\">\n";
1481         print "<tbody>\n";
1482         foreach $parameter (@{$args{'parameterlist'}}) {
1483             my $parameter_name = $parameter;
1484             $parameter_name =~ s/\[.*//;
1485
1486             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1487             print "   <entry>\n";
1488             $lineprefix="     ";
1489             output_highlight($args{'parameterdescs'}{$parameter_name});
1490             print "    </entry></row>\n";
1491         }
1492         print " </tbody></tgroup></informaltable>\n";
1493     } else {
1494         print " <para>\n  None\n </para>\n";
1495     }
1496
1497     # print out each section
1498     $lineprefix="   ";
1499     foreach $section (@{$args{'sectionlist'}}) {
1500         print "<simplesect>\n <title>$section</title>\n";
1501         if ($section =~ m/EXAMPLE/i) {
1502             print "<example><programlisting>\n";
1503             $output_preformatted = 1;
1504         } else {
1505         }
1506         print "<para>\n";
1507         output_highlight($args{'sections'}{$section});
1508         $output_preformatted = 0;
1509         print "</para>\n";
1510         if ($section =~ m/EXAMPLE/i) {
1511             print "</programlisting></example>\n";
1512         } else {
1513         }
1514         print " </simplesect>\n";
1515     }
1516
1517     print "</sect2>\n\n";
1518 }
1519
1520 ##
1521 # output function in man
1522 sub output_function_man(%) {
1523     my %args = %{$_[0]};
1524     my ($parameter, $section);
1525     my $count;
1526
1527     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1528
1529     print ".SH NAME\n";
1530     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1531
1532     print ".SH SYNOPSIS\n";
1533     if ($args{'functiontype'} ne "") {
1534         print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1535     } else {
1536         print ".B \"" . $args{'function'} . "\n";
1537     }
1538     $count = 0;
1539     my $parenth = "(";
1540     my $post = ",";
1541     foreach my $parameter (@{$args{'parameterlist'}}) {
1542         if ($count == $#{$args{'parameterlist'}}) {
1543             $post = ");";
1544         }
1545         $type = $args{'parametertypes'}{$parameter};
1546         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1547             # pointer-to-function
1548             print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1549         } else {
1550             $type =~ s/([^\*])$/$1 /;
1551             print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1552         }
1553         $count++;
1554         $parenth = "";
1555     }
1556
1557     print ".SH ARGUMENTS\n";
1558     foreach $parameter (@{$args{'parameterlist'}}) {
1559         my $parameter_name = $parameter;
1560         $parameter_name =~ s/\[.*//;
1561
1562         print ".IP \"" . $parameter . "\" 12\n";
1563         output_highlight($args{'parameterdescs'}{$parameter_name});
1564     }
1565     foreach $section (@{$args{'sectionlist'}}) {
1566         print ".SH \"", uc $section, "\"\n";
1567         output_highlight($args{'sections'}{$section});
1568     }
1569 }
1570
1571 ##
1572 # output enum in man
1573 sub output_enum_man(%) {
1574     my %args = %{$_[0]};
1575     my ($parameter, $section);
1576     my $count;
1577
1578     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1579
1580     print ".SH NAME\n";
1581     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1582
1583     print ".SH SYNOPSIS\n";
1584     print "enum " . $args{'enum'} . " {\n";
1585     $count = 0;
1586     foreach my $parameter (@{$args{'parameterlist'}}) {
1587         print ".br\n.BI \"    $parameter\"\n";
1588         if ($count == $#{$args{'parameterlist'}}) {
1589             print "\n};\n";
1590             last;
1591         }
1592         else {
1593             print ", \n.br\n";
1594         }
1595         $count++;
1596     }
1597
1598     print ".SH Constants\n";
1599     foreach $parameter (@{$args{'parameterlist'}}) {
1600         my $parameter_name = $parameter;
1601         $parameter_name =~ s/\[.*//;
1602
1603         print ".IP \"" . $parameter . "\" 12\n";
1604         output_highlight($args{'parameterdescs'}{$parameter_name});
1605     }
1606     foreach $section (@{$args{'sectionlist'}}) {
1607         print ".SH \"$section\"\n";
1608         output_highlight($args{'sections'}{$section});
1609     }
1610 }
1611
1612 ##
1613 # output struct in man
1614 sub output_struct_man(%) {
1615     my %args = %{$_[0]};
1616     my ($parameter, $section);
1617
1618     print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1619
1620     print ".SH NAME\n";
1621     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1622
1623     print ".SH SYNOPSIS\n";
1624     print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1625
1626     foreach my $parameter (@{$args{'parameterlist'}}) {
1627         if ($parameter =~ /^#/) {
1628             print ".BI \"$parameter\"\n.br\n";
1629             next;
1630         }
1631         my $parameter_name = $parameter;
1632         $parameter_name =~ s/\[.*//;
1633
1634         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1635         $type = $args{'parametertypes'}{$parameter};
1636         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1637             # pointer-to-function
1638             print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1639         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1640             # bitfield
1641             print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1642         } else {
1643             $type =~ s/([^\*])$/$1 /;
1644             print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1645         }
1646         print "\n.br\n";
1647     }
1648     print "};\n.br\n";
1649
1650     print ".SH Members\n";
1651     foreach $parameter (@{$args{'parameterlist'}}) {
1652         ($parameter =~ /^#/) && next;
1653
1654         my $parameter_name = $parameter;
1655         $parameter_name =~ s/\[.*//;
1656
1657         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1658         print ".IP \"" . $parameter . "\" 12\n";
1659         output_highlight($args{'parameterdescs'}{$parameter_name});
1660     }
1661     foreach $section (@{$args{'sectionlist'}}) {
1662         print ".SH \"$section\"\n";
1663         output_highlight($args{'sections'}{$section});
1664     }
1665 }
1666
1667 ##
1668 # output typedef in man
1669 sub output_typedef_man(%) {
1670     my %args = %{$_[0]};
1671     my ($parameter, $section);
1672
1673     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1674
1675     print ".SH NAME\n";
1676     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1677
1678     foreach $section (@{$args{'sectionlist'}}) {
1679         print ".SH \"$section\"\n";
1680         output_highlight($args{'sections'}{$section});
1681     }
1682 }
1683
1684 sub output_blockhead_man(%) {
1685     my %args = %{$_[0]};
1686     my ($parameter, $section);
1687     my $count;
1688
1689     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1690
1691     foreach $section (@{$args{'sectionlist'}}) {
1692         print ".SH \"$section\"\n";
1693         output_highlight($args{'sections'}{$section});
1694     }
1695 }
1696
1697 ##
1698 # output in text
1699 sub output_function_text(%) {
1700     my %args = %{$_[0]};
1701     my ($parameter, $section);
1702     my $start;
1703
1704     print "Name:\n\n";
1705     print $args{'function'} . " - " . $args{'purpose'} . "\n";
1706
1707     print "\nSynopsis:\n\n";
1708     if ($args{'functiontype'} ne "") {
1709         $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1710     } else {
1711         $start = $args{'function'} . " (";
1712     }
1713     print $start;
1714
1715     my $count = 0;
1716     foreach my $parameter (@{$args{'parameterlist'}}) {
1717         $type = $args{'parametertypes'}{$parameter};
1718         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1719             # pointer-to-function
1720             print $1 . $parameter . ") (" . $2;
1721         } else {
1722             print $type . " " . $parameter;
1723         }
1724         if ($count != $#{$args{'parameterlist'}}) {
1725             $count++;
1726             print ",\n";
1727             print " " x length($start);
1728         } else {
1729             print ");\n\n";
1730         }
1731     }
1732
1733     print "Arguments:\n\n";
1734     foreach $parameter (@{$args{'parameterlist'}}) {
1735         my $parameter_name = $parameter;
1736         $parameter_name =~ s/\[.*//;
1737
1738         print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1739     }
1740     output_section_text(@_);
1741 }
1742
1743 #output sections in text
1744 sub output_section_text(%) {
1745     my %args = %{$_[0]};
1746     my $section;
1747
1748     print "\n";
1749     foreach $section (@{$args{'sectionlist'}}) {
1750         print "$section:\n\n";
1751         output_highlight($args{'sections'}{$section});
1752     }
1753     print "\n\n";
1754 }
1755
1756 # output enum in text
1757 sub output_enum_text(%) {
1758     my %args = %{$_[0]};
1759     my ($parameter);
1760     my $count;
1761     print "Enum:\n\n";
1762
1763     print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1764     print "enum " . $args{'enum'} . " {\n";
1765     $count = 0;
1766     foreach $parameter (@{$args{'parameterlist'}}) {
1767         print "\t$parameter";
1768         if ($count != $#{$args{'parameterlist'}}) {
1769             $count++;
1770             print ",";
1771         }
1772         print "\n";
1773     }
1774     print "};\n\n";
1775
1776     print "Constants:\n\n";
1777     foreach $parameter (@{$args{'parameterlist'}}) {
1778         print "$parameter\n\t";
1779         print $args{'parameterdescs'}{$parameter} . "\n";
1780     }
1781
1782     output_section_text(@_);
1783 }
1784
1785 # output typedef in text
1786 sub output_typedef_text(%) {
1787     my %args = %{$_[0]};
1788     my ($parameter);
1789     my $count;
1790     print "Typedef:\n\n";
1791
1792     print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1793     output_section_text(@_);
1794 }
1795
1796 # output struct as text
1797 sub output_struct_text(%) {
1798     my %args = %{$_[0]};
1799     my ($parameter);
1800
1801     print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1802     print $args{'type'} . " " . $args{'struct'} . " {\n";
1803     foreach $parameter (@{$args{'parameterlist'}}) {
1804         if ($parameter =~ /^#/) {
1805             print "$parameter\n";
1806             next;
1807         }
1808
1809         my $parameter_name = $parameter;
1810         $parameter_name =~ s/\[.*//;
1811
1812         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1813         $type = $args{'parametertypes'}{$parameter};
1814         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1815             # pointer-to-function
1816             print "\t$1 $parameter) ($2);\n";
1817         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1818             # bitfield
1819             print "\t$1 $parameter$2;\n";
1820         } else {
1821             print "\t" . $type . " " . $parameter . ";\n";
1822         }
1823     }
1824     print "};\n\n";
1825
1826     print "Members:\n\n";
1827     foreach $parameter (@{$args{'parameterlist'}}) {
1828         ($parameter =~ /^#/) && next;
1829
1830         my $parameter_name = $parameter;
1831         $parameter_name =~ s/\[.*//;
1832
1833         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1834         print "$parameter\n\t";
1835         print $args{'parameterdescs'}{$parameter_name} . "\n";
1836     }
1837     print "\n";
1838     output_section_text(@_);
1839 }
1840
1841 sub output_blockhead_text(%) {
1842     my %args = %{$_[0]};
1843     my ($parameter, $section);
1844
1845     foreach $section (@{$args{'sectionlist'}}) {
1846         print " $section:\n";
1847         print "    -> ";
1848         output_highlight($args{'sections'}{$section});
1849     }
1850 }
1851
1852 ##
1853 # output in restructured text
1854 #
1855
1856 #
1857 # This could use some work; it's used to output the DOC: sections, and
1858 # starts by putting out the name of the doc section itself, but that tends
1859 # to duplicate a header already in the template file.
1860 #
1861 sub output_blockhead_rst(%) {
1862     my %args = %{$_[0]};
1863     my ($parameter, $section);
1864
1865     foreach $section (@{$args{'sectionlist'}}) {
1866         if ($output_selection != OUTPUT_INCLUDE) {
1867             print "**$section**\n\n";
1868         }
1869         print_lineno($section_start_lines{$section});
1870         output_highlight_rst($args{'sections'}{$section});
1871         print "\n";
1872     }
1873 }
1874
1875 sub output_highlight_rst {
1876     my $contents = join "\n",@_;
1877     my $line;
1878
1879     # undo the evil effects of xml_escape() earlier
1880     $contents = xml_unescape($contents);
1881
1882     eval $dohighlight;
1883     die $@ if $@;
1884
1885     foreach $line (split "\n", $contents) {
1886         print $lineprefix . $line . "\n";
1887     }
1888 }
1889
1890 sub output_function_rst(%) {
1891     my %args = %{$_[0]};
1892     my ($parameter, $section);
1893     my $oldprefix = $lineprefix;
1894     my $start = "";
1895
1896     if ($args{'typedef'}) {
1897         print ".. c:type:: ". $args{'function'} . "\n\n";
1898         print_lineno($declaration_start_line);
1899         print "   **Typedef**: ";
1900         $lineprefix = "";
1901         output_highlight_rst($args{'purpose'});
1902         $start = "\n\n**Syntax**\n\n  ``";
1903     } else {
1904         print ".. c:function:: ";
1905     }
1906     if ($args{'functiontype'} ne "") {
1907         $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
1908     } else {
1909         $start .= $args{'function'} . " (";
1910     }
1911     print $start;
1912
1913     my $count = 0;
1914     foreach my $parameter (@{$args{'parameterlist'}}) {
1915         if ($count ne 0) {
1916             print ", ";
1917         }
1918         $count++;
1919         $type = $args{'parametertypes'}{$parameter};
1920
1921         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1922             # pointer-to-function
1923             print $1 . $parameter . ") (" . $2;
1924         } else {
1925             print $type . " " . $parameter;
1926         }
1927     }
1928     if ($args{'typedef'}) {
1929         print ");``\n\n";
1930     } else {
1931         print ")\n\n";
1932         print_lineno($declaration_start_line);
1933         $lineprefix = "   ";
1934         output_highlight_rst($args{'purpose'});
1935         print "\n";
1936     }
1937
1938     print "**Parameters**\n\n";
1939     $lineprefix = "  ";
1940     foreach $parameter (@{$args{'parameterlist'}}) {
1941         my $parameter_name = $parameter;
1942         $parameter_name =~ s/\[.*//;
1943         $type = $args{'parametertypes'}{$parameter};
1944
1945         if ($type ne "") {
1946             print "``$type $parameter``\n";
1947         } else {
1948             print "``$parameter``\n";
1949         }
1950
1951         print_lineno($parameterdesc_start_lines{$parameter_name});
1952
1953         if (defined($args{'parameterdescs'}{$parameter_name}) &&
1954             $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1955             output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1956         } else {
1957             print "  *undescribed*\n";
1958         }
1959         print "\n";
1960     }
1961
1962     $lineprefix = $oldprefix;
1963     output_section_rst(@_);
1964 }
1965
1966 sub output_section_rst(%) {
1967     my %args = %{$_[0]};
1968     my $section;
1969     my $oldprefix = $lineprefix;
1970     $lineprefix = "";
1971
1972     foreach $section (@{$args{'sectionlist'}}) {
1973         print "**$section**\n\n";
1974         print_lineno($section_start_lines{$section});
1975         output_highlight_rst($args{'sections'}{$section});
1976         print "\n";
1977     }
1978     print "\n";
1979     $lineprefix = $oldprefix;
1980 }
1981
1982 sub output_enum_rst(%) {
1983     my %args = %{$_[0]};
1984     my ($parameter);
1985     my $oldprefix = $lineprefix;
1986     my $count;
1987     my $name = "enum " . $args{'enum'};
1988
1989     print "\n\n.. c:type:: " . $name . "\n\n";
1990     print_lineno($declaration_start_line);
1991     $lineprefix = "   ";
1992     output_highlight_rst($args{'purpose'});
1993     print "\n";
1994
1995     print "**Constants**\n\n";
1996     $lineprefix = "  ";
1997     foreach $parameter (@{$args{'parameterlist'}}) {
1998         print "``$parameter``\n";
1999         if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
2000             output_highlight_rst($args{'parameterdescs'}{$parameter});
2001         } else {
2002             print "  *undescribed*\n";
2003         }
2004         print "\n";
2005     }
2006
2007     $lineprefix = $oldprefix;
2008     output_section_rst(@_);
2009 }
2010
2011 sub output_typedef_rst(%) {
2012     my %args = %{$_[0]};
2013     my ($parameter);
2014     my $oldprefix = $lineprefix;
2015     my $name = "typedef " . $args{'typedef'};
2016
2017     print "\n\n.. c:type:: " . $name . "\n\n";
2018     print_lineno($declaration_start_line);
2019     $lineprefix = "   ";
2020     output_highlight_rst($args{'purpose'});
2021     print "\n";
2022
2023     $lineprefix = $oldprefix;
2024     output_section_rst(@_);
2025 }
2026
2027 sub output_struct_rst(%) {
2028     my %args = %{$_[0]};
2029     my ($parameter);
2030     my $oldprefix = $lineprefix;
2031     my $name = $args{'type'} . " " . $args{'struct'};
2032
2033     print "\n\n.. c:type:: " . $name . "\n\n";
2034     print_lineno($declaration_start_line);
2035     $lineprefix = "   ";
2036     output_highlight_rst($args{'purpose'});
2037     print "\n";
2038
2039     print "**Definition**\n\n";
2040     print "::\n\n";
2041     print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
2042     foreach $parameter (@{$args{'parameterlist'}}) {
2043         if ($parameter =~ /^#/) {
2044             print "  " . "$parameter\n";
2045             next;
2046         }
2047
2048         my $parameter_name = $parameter;
2049         $parameter_name =~ s/\[.*//;
2050
2051         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
2052         $type = $args{'parametertypes'}{$parameter};
2053         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
2054             # pointer-to-function
2055             print "    $1 $parameter) ($2);\n";
2056         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
2057             # bitfield
2058             print "    $1 $parameter$2;\n";
2059         } else {
2060             print "    " . $type . " " . $parameter . ";\n";
2061         }
2062     }
2063     print "  };\n\n";
2064
2065     print "**Members**\n\n";
2066     $lineprefix = "  ";
2067     foreach $parameter (@{$args{'parameterlist'}}) {
2068         ($parameter =~ /^#/) && next;
2069
2070         my $parameter_name = $parameter;
2071         $parameter_name =~ s/\[.*//;
2072
2073         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
2074         $type = $args{'parametertypes'}{$parameter};
2075         print_lineno($parameterdesc_start_lines{$parameter_name});
2076         print "``" . $parameter . "``\n";
2077         output_highlight_rst($args{'parameterdescs'}{$parameter_name});
2078         print "\n";
2079     }
2080     print "\n";
2081
2082     $lineprefix = $oldprefix;
2083     output_section_rst(@_);
2084 }
2085
2086
2087 ## list mode output functions
2088
2089 sub output_function_list(%) {
2090     my %args = %{$_[0]};
2091
2092     print $args{'function'} . "\n";
2093 }
2094
2095 # output enum in list
2096 sub output_enum_list(%) {
2097     my %args = %{$_[0]};
2098     print $args{'enum'} . "\n";
2099 }
2100
2101 # output typedef in list
2102 sub output_typedef_list(%) {
2103     my %args = %{$_[0]};
2104     print $args{'typedef'} . "\n";
2105 }
2106
2107 # output struct as list
2108 sub output_struct_list(%) {
2109     my %args = %{$_[0]};
2110
2111     print $args{'struct'} . "\n";
2112 }
2113
2114 sub output_blockhead_list(%) {
2115     my %args = %{$_[0]};
2116     my ($parameter, $section);
2117
2118     foreach $section (@{$args{'sectionlist'}}) {
2119         print "DOC: $section\n";
2120     }
2121 }
2122
2123
2124 ## none mode output functions
2125
2126 sub output_function_none(%) {
2127 }
2128
2129 sub output_enum_none(%) {
2130 }
2131
2132 sub output_typedef_none(%) {
2133 }
2134
2135 sub output_struct_none(%) {
2136 }
2137
2138 sub output_blockhead_none(%) {
2139 }
2140
2141 ##
2142 # generic output function for all types (function, struct/union, typedef, enum);
2143 # calls the generated, variable output_ function name based on
2144 # functype and output_mode
2145 sub output_declaration {
2146     no strict 'refs';
2147     my $name = shift;
2148     my $functype = shift;
2149     my $func = "output_${functype}_$output_mode";
2150     if (($output_selection == OUTPUT_ALL) ||
2151         (($output_selection == OUTPUT_INCLUDE ||
2152           $output_selection == OUTPUT_EXPORTED) &&
2153          defined($function_table{$name})) ||
2154         (($output_selection == OUTPUT_EXCLUDE ||
2155           $output_selection == OUTPUT_INTERNAL) &&
2156          !($functype eq "function" && defined($function_table{$name}))))
2157     {
2158         &$func(@_);
2159         $section_counter++;
2160     }
2161 }
2162
2163 ##
2164 # generic output function - calls the right one based on current output mode.
2165 sub output_blockhead {
2166     no strict 'refs';
2167     my $func = "output_blockhead_" . $output_mode;
2168     &$func(@_);
2169     $section_counter++;
2170 }
2171
2172 ##
2173 # takes a declaration (struct, union, enum, typedef) and
2174 # invokes the right handler. NOT called for functions.
2175 sub dump_declaration($$) {
2176     no strict 'refs';
2177     my ($prototype, $file) = @_;
2178     my $func = "dump_" . $decl_type;
2179     &$func(@_);
2180 }
2181
2182 sub dump_union($$) {
2183     dump_struct(@_);
2184 }
2185
2186 sub dump_struct($$) {
2187     my $x = shift;
2188     my $file = shift;
2189     my $nested;
2190
2191     if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2192         my $decl_type = $1;
2193         $declaration_name = $2;
2194         my $members = $3;
2195
2196         # ignore embedded structs or unions
2197         $members =~ s/({.*})//g;
2198         $nested = $1;
2199
2200         # ignore members marked private:
2201         $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2202         $members =~ s/\/\*\s*private:.*//gosi;
2203         # strip comments:
2204         $members =~ s/\/\*.*?\*\///gos;
2205         $nested =~ s/\/\*.*?\*\///gos;
2206         # strip attributes
2207         $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2208         $members =~ s/__aligned\s*\([^;]*\)//gos;
2209         $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2210         # replace DECLARE_BITMAP
2211         $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2212         # replace DECLARE_HASHTABLE
2213         $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
2214
2215         create_parameterlist($members, ';', $file);
2216         check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested);
2217
2218         output_declaration($declaration_name,
2219                            'struct',
2220                            {'struct' => $declaration_name,
2221                             'module' => $modulename,
2222                             'parameterlist' => \@parameterlist,
2223                             'parameterdescs' => \%parameterdescs,
2224                             'parametertypes' => \%parametertypes,
2225                             'sectionlist' => \@sectionlist,
2226                             'sections' => \%sections,
2227                             'purpose' => $declaration_purpose,
2228                             'type' => $decl_type
2229                            });
2230     }
2231     else {
2232         print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2233         ++$errors;
2234     }
2235 }
2236
2237 sub dump_enum($$) {
2238     my $x = shift;
2239     my $file = shift;
2240
2241     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
2242     # strip #define macros inside enums
2243     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2244
2245     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2246         $declaration_name = $1;
2247         my $members = $2;
2248         my %_members;
2249
2250         $members =~ s/\s+$//;
2251
2252         foreach my $arg (split ',', $members) {
2253             $arg =~ s/^\s*(\w+).*/$1/;
2254             push @parameterlist, $arg;
2255             if (!$parameterdescs{$arg}) {
2256                 $parameterdescs{$arg} = $undescribed;
2257                 print STDERR "${file}:$.: warning: Enum value '$arg' ".
2258                     "not described in enum '$declaration_name'\n";
2259             }
2260             $_members{$arg} = 1;
2261         }
2262
2263         while (my ($k, $v) = each %parameterdescs) {
2264             if (!exists($_members{$k})) {
2265              print STDERR "${file}:$.: warning: Excess enum value " .
2266                           "'$k' description in '$declaration_name'\n";
2267             }
2268         }
2269
2270         output_declaration($declaration_name,
2271                            'enum',
2272                            {'enum' => $declaration_name,
2273                             'module' => $modulename,
2274                             'parameterlist' => \@parameterlist,
2275                             'parameterdescs' => \%parameterdescs,
2276                             'sectionlist' => \@sectionlist,
2277                             'sections' => \%sections,
2278                             'purpose' => $declaration_purpose
2279                            });
2280     }
2281     else {
2282         print STDERR "${file}:$.: error: Cannot parse enum!\n";
2283         ++$errors;
2284     }
2285 }
2286
2287 sub dump_typedef($$) {
2288     my $x = shift;
2289     my $file = shift;
2290
2291     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
2292
2293     # Parse function prototypes
2294     if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
2295         $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
2296
2297         # Function typedefs
2298         $return_type = $1;
2299         $declaration_name = $2;
2300         my $args = $3;
2301
2302         create_parameterlist($args, ',', $file);
2303
2304         output_declaration($declaration_name,
2305                            'function',
2306                            {'function' => $declaration_name,
2307                             'typedef' => 1,
2308                             'module' => $modulename,
2309                             'functiontype' => $return_type,
2310                             'parameterlist' => \@parameterlist,
2311                             'parameterdescs' => \%parameterdescs,
2312                             'parametertypes' => \%parametertypes,
2313                             'sectionlist' => \@sectionlist,
2314                             'sections' => \%sections,
2315                             'purpose' => $declaration_purpose
2316                            });
2317         return;
2318     }
2319
2320     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2321         $x =~ s/\(*.\)\s*;$/;/;
2322         $x =~ s/\[*.\]\s*;$/;/;
2323     }
2324
2325     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2326         $declaration_name = $1;
2327
2328         output_declaration($declaration_name,
2329                            'typedef',
2330                            {'typedef' => $declaration_name,
2331                             'module' => $modulename,
2332                             'sectionlist' => \@sectionlist,
2333                             'sections' => \%sections,
2334                             'purpose' => $declaration_purpose
2335                            });
2336     }
2337     else {
2338         print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2339         ++$errors;
2340     }
2341 }
2342
2343 sub save_struct_actual($) {
2344     my $actual = shift;
2345
2346     # strip all spaces from the actual param so that it looks like one string item
2347     $actual =~ s/\s*//g;
2348     $struct_actual = $struct_actual . $actual . " ";
2349 }
2350
2351 sub create_parameterlist($$$) {
2352     my $args = shift;
2353     my $splitter = shift;
2354     my $file = shift;
2355     my $type;
2356     my $param;
2357
2358     # temporarily replace commas inside function pointer definition
2359     while ($args =~ /(\([^\),]+),/) {
2360         $args =~ s/(\([^\),]+),/$1#/g;
2361     }
2362
2363     foreach my $arg (split($splitter, $args)) {
2364         # strip comments
2365         $arg =~ s/\/\*.*\*\///;
2366         # strip leading/trailing spaces
2367         $arg =~ s/^\s*//;
2368         $arg =~ s/\s*$//;
2369         $arg =~ s/\s+/ /;
2370
2371         if ($arg =~ /^#/) {
2372             # Treat preprocessor directive as a typeless variable just to fill
2373             # corresponding data structures "correctly". Catch it later in
2374             # output_* subs.
2375             push_parameter($arg, "", $file);
2376         } elsif ($arg =~ m/\(.+\)\s*\(/) {
2377             # pointer-to-function
2378             $arg =~ tr/#/,/;
2379             $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2380             $param = $1;
2381             $type = $arg;
2382             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2383             save_struct_actual($param);
2384             push_parameter($param, $type, $file);
2385         } elsif ($arg) {
2386             $arg =~ s/\s*:\s*/:/g;
2387             $arg =~ s/\s*\[/\[/g;
2388
2389             my @args = split('\s*,\s*', $arg);
2390             if ($args[0] =~ m/\*/) {
2391                 $args[0] =~ s/(\*+)\s*/ $1/;
2392             }
2393
2394             my @first_arg;
2395             if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2396                     shift @args;
2397                     push(@first_arg, split('\s+', $1));
2398                     push(@first_arg, $2);
2399             } else {
2400                     @first_arg = split('\s+', shift @args);
2401             }
2402
2403             unshift(@args, pop @first_arg);
2404             $type = join " ", @first_arg;
2405
2406             foreach $param (@args) {
2407                 if ($param =~ m/^(\*+)\s*(.*)/) {
2408                     save_struct_actual($2);
2409                     push_parameter($2, "$type $1", $file);
2410                 }
2411                 elsif ($param =~ m/(.*?):(\d+)/) {
2412                     if ($type ne "") { # skip unnamed bit-fields
2413                         save_struct_actual($1);
2414                         push_parameter($1, "$type:$2", $file)
2415                     }
2416                 }
2417                 else {
2418                     save_struct_actual($param);
2419                     push_parameter($param, $type, $file);
2420                 }
2421             }
2422         }
2423     }
2424 }
2425
2426 sub push_parameter($$$) {
2427         my $param = shift;
2428         my $type = shift;
2429         my $file = shift;
2430
2431         if (($anon_struct_union == 1) && ($type eq "") &&
2432             ($param eq "}")) {
2433                 return;         # ignore the ending }; from anon. struct/union
2434         }
2435
2436         $anon_struct_union = 0;
2437         $param =~ s/[\[\)].*//;
2438
2439         if ($type eq "" && $param =~ /\.\.\.$/)
2440         {
2441             if (!$param =~ /\w\.\.\.$/) {
2442               # handles unnamed variable parameters
2443               $param = "...";
2444             }
2445             if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2446                 $parameterdescs{$param} = "variable arguments";
2447             }
2448         }
2449         elsif ($type eq "" && ($param eq "" or $param eq "void"))
2450         {
2451             $param="void";
2452             $parameterdescs{void} = "no arguments";
2453         }
2454         elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2455         # handle unnamed (anonymous) union or struct:
2456         {
2457                 $type = $param;
2458                 $param = "{unnamed_" . $param . "}";
2459                 $parameterdescs{$param} = "anonymous\n";
2460                 $anon_struct_union = 1;
2461         }
2462
2463         # warn if parameter has no description
2464         # (but ignore ones starting with # as these are not parameters
2465         # but inline preprocessor statements);
2466         # also ignore unnamed structs/unions;
2467         if (!$anon_struct_union) {
2468         if (!defined $parameterdescs{$param} && $param !~ /^#/) {
2469
2470             $parameterdescs{$param} = $undescribed;
2471
2472             if (($type eq 'function') || ($type eq 'enum')) {
2473                 print STDERR "${file}:$.: warning: Function parameter ".
2474                     "or member '$param' not " .
2475                     "described in '$declaration_name'\n";
2476             }
2477             print STDERR "${file}:$.: warning:" .
2478                          " No description found for parameter '$param'\n";
2479             ++$warnings;
2480         }
2481         }
2482
2483         $param = xml_escape($param);
2484
2485         # strip spaces from $param so that it is one continuous string
2486         # on @parameterlist;
2487         # this fixes a problem where check_sections() cannot find
2488         # a parameter like "addr[6 + 2]" because it actually appears
2489         # as "addr[6", "+", "2]" on the parameter list;
2490         # but it's better to maintain the param string unchanged for output,
2491         # so just weaken the string compare in check_sections() to ignore
2492         # "[blah" in a parameter string;
2493         ###$param =~ s/\s*//g;
2494         push @parameterlist, $param;
2495         $type =~ s/\s\s+/ /g;
2496         $parametertypes{$param} = $type;
2497 }
2498
2499 sub check_sections($$$$$$) {
2500         my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2501         my @sects = split ' ', $sectcheck;
2502         my @prms = split ' ', $prmscheck;
2503         my $err;
2504         my ($px, $sx);
2505         my $prm_clean;          # strip trailing "[array size]" and/or beginning "*"
2506
2507         foreach $sx (0 .. $#sects) {
2508                 $err = 1;
2509                 foreach $px (0 .. $#prms) {
2510                         $prm_clean = $prms[$px];
2511                         $prm_clean =~ s/\[.*\]//;
2512                         $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2513                         # ignore array size in a parameter string;
2514                         # however, the original param string may contain
2515                         # spaces, e.g.:  addr[6 + 2]
2516                         # and this appears in @prms as "addr[6" since the
2517                         # parameter list is split at spaces;
2518                         # hence just ignore "[..." for the sections check;
2519                         $prm_clean =~ s/\[.*//;
2520
2521                         ##$prm_clean =~ s/^\**//;
2522                         if ($prm_clean eq $sects[$sx]) {
2523                                 $err = 0;
2524                                 last;
2525                         }
2526                 }
2527                 if ($err) {
2528                         if ($decl_type eq "function") {
2529                                 print STDERR "${file}:$.: warning: " .
2530                                         "Excess function parameter " .
2531                                         "'$sects[$sx]' " .
2532                                         "description in '$decl_name'\n";
2533                                 ++$warnings;
2534                         } else {
2535                                 if ($nested !~ m/\Q$sects[$sx]\E/) {
2536                                     print STDERR "${file}:$.: warning: " .
2537                                         "Excess $decl_type member " .
2538                                         "'$sects[$sx]' " .
2539                                         "description in '$decl_name'\n";
2540                                     ++$warnings;
2541                                 }
2542                         }
2543                 }
2544         }
2545 }
2546
2547 ##
2548 # Checks the section describing the return value of a function.
2549 sub check_return_section {
2550         my $file = shift;
2551         my $declaration_name = shift;
2552         my $return_type = shift;
2553
2554         # Ignore an empty return type (It's a macro)
2555         # Ignore functions with a "void" return type. (But don't ignore "void *")
2556         if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2557                 return;
2558         }
2559
2560         if (!defined($sections{$section_return}) ||
2561             $sections{$section_return} eq "") {
2562                 print STDERR "${file}:$.: warning: " .
2563                         "No description found for return value of " .
2564                         "'$declaration_name'\n";
2565                 ++$warnings;
2566         }
2567 }
2568
2569 ##
2570 # takes a function prototype and the name of the current file being
2571 # processed and spits out all the details stored in the global
2572 # arrays/hashes.
2573 sub dump_function($$) {
2574     my $prototype = shift;
2575     my $file = shift;
2576     my $noret = 0;
2577
2578     $prototype =~ s/^static +//;
2579     $prototype =~ s/^extern +//;
2580     $prototype =~ s/^asmlinkage +//;
2581     $prototype =~ s/^inline +//;
2582     $prototype =~ s/^__inline__ +//;
2583     $prototype =~ s/^__inline +//;
2584     $prototype =~ s/^__always_inline +//;
2585     $prototype =~ s/^noinline +//;
2586     $prototype =~ s/__init +//;
2587     $prototype =~ s/__init_or_module +//;
2588     $prototype =~ s/__meminit +//;
2589     $prototype =~ s/__must_check +//;
2590     $prototype =~ s/__weak +//;
2591     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2592     $prototype =~ s/__attribute__\s*\(\(
2593             (?:
2594                  [\w\s]++          # attribute name
2595                  (?:\([^)]*+\))?   # attribute arguments
2596                  \s*+,?            # optional comma at the end
2597             )+
2598           \)\)\s+//x;
2599
2600     # Yes, this truly is vile.  We are looking for:
2601     # 1. Return type (may be nothing if we're looking at a macro)
2602     # 2. Function name
2603     # 3. Function parameters.
2604     #
2605     # All the while we have to watch out for function pointer parameters
2606     # (which IIRC is what the two sections are for), C types (these
2607     # regexps don't even start to express all the possibilities), and
2608     # so on.
2609     #
2610     # If you mess with these regexps, it's a good idea to check that
2611     # the following functions' documentation still comes out right:
2612     # - parport_register_device (function pointer parameters)
2613     # - atomic_set (macro)
2614     # - pci_match_device, __copy_to_user (long return type)
2615
2616     if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2617         # This is an object-like macro, it has no return type and no parameter
2618         # list.
2619         # Function-like macros are not allowed to have spaces between
2620         # declaration_name and opening parenthesis (notice the \s+).
2621         $return_type = $1;
2622         $declaration_name = $2;
2623         $noret = 1;
2624     } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2625         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2626         $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2627         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2628         $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2629         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2630         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2631         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2632         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2633         $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2634         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2635         $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2636         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2637         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2638         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2639         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2640         $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
2641         $return_type = $1;
2642         $declaration_name = $2;
2643         my $args = $3;
2644
2645         create_parameterlist($args, ',', $file);
2646     } else {
2647         print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2648         return;
2649     }
2650
2651         my $prms = join " ", @parameterlist;
2652         check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2653
2654         # This check emits a lot of warnings at the moment, because many
2655         # functions don't have a 'Return' doc section. So until the number
2656         # of warnings goes sufficiently down, the check is only performed in
2657         # verbose mode.
2658         # TODO: always perform the check.
2659         if ($verbose && !$noret) {
2660                 check_return_section($file, $declaration_name, $return_type);
2661         }
2662
2663     output_declaration($declaration_name,
2664                        'function',
2665                        {'function' => $declaration_name,
2666                         'module' => $modulename,
2667                         'functiontype' => $return_type,
2668                         'parameterlist' => \@parameterlist,
2669                         'parameterdescs' => \%parameterdescs,
2670                         'parametertypes' => \%parametertypes,
2671                         'sectionlist' => \@sectionlist,
2672                         'sections' => \%sections,
2673                         'purpose' => $declaration_purpose
2674                        });
2675 }
2676
2677 sub reset_state {
2678     $function = "";
2679     %parameterdescs = ();
2680     %parametertypes = ();
2681     @parameterlist = ();
2682     %sections = ();
2683     @sectionlist = ();
2684     $sectcheck = "";
2685     $struct_actual = "";
2686     $prototype = "";
2687
2688     $state = STATE_NORMAL;
2689     $inline_doc_state = STATE_INLINE_NA;
2690 }
2691
2692 sub tracepoint_munge($) {
2693         my $file = shift;
2694         my $tracepointname = 0;
2695         my $tracepointargs = 0;
2696
2697         if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2698                 $tracepointname = $1;
2699         }
2700         if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2701                 $tracepointname = $1;
2702         }
2703         if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2704                 $tracepointname = $2;
2705         }
2706         $tracepointname =~ s/^\s+//; #strip leading whitespace
2707         if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2708                 $tracepointargs = $1;
2709         }
2710         if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2711                 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2712                              "$prototype\n";
2713         } else {
2714                 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2715         }
2716 }
2717
2718 sub syscall_munge() {
2719         my $void = 0;
2720
2721         $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2722 ##      if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2723         if ($prototype =~ m/SYSCALL_DEFINE0/) {
2724                 $void = 1;
2725 ##              $prototype = "long sys_$1(void)";
2726         }
2727
2728         $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2729         if ($prototype =~ m/long (sys_.*?),/) {
2730                 $prototype =~ s/,/\(/;
2731         } elsif ($void) {
2732                 $prototype =~ s/\)/\(void\)/;
2733         }
2734
2735         # now delete all of the odd-number commas in $prototype
2736         # so that arg types & arg names don't have a comma between them
2737         my $count = 0;
2738         my $len = length($prototype);
2739         if ($void) {
2740                 $len = 0;       # skip the for-loop
2741         }
2742         for (my $ix = 0; $ix < $len; $ix++) {
2743                 if (substr($prototype, $ix, 1) eq ',') {
2744                         $count++;
2745                         if ($count % 2 == 1) {
2746                                 substr($prototype, $ix, 1) = ' ';
2747                         }
2748                 }
2749         }
2750 }
2751
2752 sub process_proto_function($$) {
2753     my $x = shift;
2754     my $file = shift;
2755
2756     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2757
2758     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2759         # do nothing
2760     }
2761     elsif ($x =~ /([^\{]*)/) {
2762         $prototype .= $1;
2763     }
2764
2765     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2766         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2767         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2768         $prototype =~ s@^\s+@@gos; # strip leading spaces
2769         if ($prototype =~ /SYSCALL_DEFINE/) {
2770                 syscall_munge();
2771         }
2772         if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2773             $prototype =~ /DEFINE_SINGLE_EVENT/)
2774         {
2775                 tracepoint_munge($file);
2776         }
2777         dump_function($prototype, $file);
2778         reset_state();
2779     }
2780 }
2781
2782 sub process_proto_type($$) {
2783     my $x = shift;
2784     my $file = shift;
2785
2786     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2787     $x =~ s@^\s+@@gos; # strip leading spaces
2788     $x =~ s@\s+$@@gos; # strip trailing spaces
2789     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2790
2791     if ($x =~ /^#/) {
2792         # To distinguish preprocessor directive from regular declaration later.
2793         $x .= ";";
2794     }
2795
2796     while (1) {
2797         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2798             if( length $prototype ) {
2799                 $prototype .= " "
2800             }
2801             $prototype .= $1 . $2;
2802             ($2 eq '{') && $brcount++;
2803             ($2 eq '}') && $brcount--;
2804             if (($2 eq ';') && ($brcount == 0)) {
2805                 dump_declaration($prototype, $file);
2806                 reset_state();
2807                 last;
2808             }
2809             $x = $3;
2810         } else {
2811             $prototype .= $x;
2812             last;
2813         }
2814     }
2815 }
2816
2817 # xml_escape: replace <, >, and & in the text stream;
2818 #
2819 # however, formatting controls that are generated internally/locally in the
2820 # kernel-doc script are not escaped here; instead, they begin life like
2821 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2822 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2823 # just before actual output; (this is done by local_unescape())
2824 sub xml_escape($) {
2825         my $text = shift;
2826         if (($output_mode eq "text") || ($output_mode eq "man")) {
2827                 return $text;
2828         }
2829         $text =~ s/\&/\\\\\\amp;/g;
2830         $text =~ s/\</\\\\\\lt;/g;
2831         $text =~ s/\>/\\\\\\gt;/g;
2832         return $text;
2833 }
2834
2835 # xml_unescape: reverse the effects of xml_escape
2836 sub xml_unescape($) {
2837         my $text = shift;
2838         if (($output_mode eq "text") || ($output_mode eq "man")) {
2839                 return $text;
2840         }
2841         $text =~ s/\\\\\\amp;/\&/g;
2842         $text =~ s/\\\\\\lt;/</g;
2843         $text =~ s/\\\\\\gt;/>/g;
2844         return $text;
2845 }
2846
2847 # convert local escape strings to html
2848 # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
2849 sub local_unescape($) {
2850         my $text = shift;
2851         if (($output_mode eq "text") || ($output_mode eq "man")) {
2852                 return $text;
2853         }
2854         $text =~ s/\\\\\\\\lt:/</g;
2855         $text =~ s/\\\\\\\\gt:/>/g;
2856         return $text;
2857 }
2858
2859 sub map_filename($) {
2860     my $file;
2861     my ($orig_file) = @_;
2862
2863     if (defined($ENV{'SRCTREE'})) {
2864         $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2865     } else {
2866         $file = $orig_file;
2867     }
2868
2869     if (defined($source_map{$file})) {
2870         $file = $source_map{$file};
2871     }
2872
2873     return $file;
2874 }
2875
2876 sub process_export_file($) {
2877     my ($orig_file) = @_;
2878     my $file = map_filename($orig_file);
2879
2880     if (!open(IN,"<$file")) {
2881         print STDERR "Error: Cannot open file $file\n";
2882         ++$errors;
2883         return;
2884     }
2885
2886     while (<IN>) {
2887         if (/$export_symbol/) {
2888             $function_table{$2} = 1;
2889         }
2890     }
2891
2892     close(IN);
2893 }
2894
2895 sub process_file($) {
2896     my $file;
2897     my $identifier;
2898     my $func;
2899     my $descr;
2900     my $in_purpose = 0;
2901     my $initial_section_counter = $section_counter;
2902     my ($orig_file) = @_;
2903     my $leading_space;
2904
2905     $file = map_filename($orig_file);
2906
2907     if (!open(IN,"<$file")) {
2908         print STDERR "Error: Cannot open file $file\n";
2909         ++$errors;
2910         return;
2911     }
2912
2913     $. = 1;
2914
2915     $section_counter = 0;
2916     while (<IN>) {
2917         while (s/\\\s*$//) {
2918             $_ .= <IN>;
2919         }
2920         if ($state == STATE_NORMAL) {
2921             if (/$doc_start/o) {
2922                 $state = STATE_NAME;    # next line is always the function name
2923                 $in_doc_sect = 0;
2924                 $declaration_start_line = $. + 1;
2925             }
2926         } elsif ($state == STATE_NAME) {# this line is the function name (always)
2927             if (/$doc_block/o) {
2928                 $state = STATE_DOCBLOCK;
2929                 $contents = "";
2930                 $new_start_line = $. + 1;
2931
2932                 if ( $1 eq "" ) {
2933                         $section = $section_intro;
2934                 } else {
2935                         $section = $1;
2936                 }
2937             }
2938             elsif (/$doc_decl/o) {
2939                 $identifier = $1;
2940                 if (/\s*([\w\s]+?)\s*-/) {
2941                     $identifier = $1;
2942                 }
2943
2944                 $state = STATE_FIELD;
2945                 # if there's no @param blocks need to set up default section
2946                 # here
2947                 $contents = "";
2948                 $section = $section_default;
2949                 $new_start_line = $. + 1;
2950                 if (/-(.*)/) {
2951                     # strip leading/trailing/multiple spaces
2952                     $descr= $1;
2953                     $descr =~ s/^\s*//;
2954                     $descr =~ s/\s*$//;
2955                     $descr =~ s/\s+/ /g;
2956                     $declaration_purpose = xml_escape($descr);
2957                     $in_purpose = 1;
2958                 } else {
2959                     $declaration_purpose = "";
2960                 }
2961
2962                 if (($declaration_purpose eq "") && $verbose) {
2963                         print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2964                         print STDERR $_;
2965                         ++$warnings;
2966                 }
2967
2968                 if ($identifier =~ m/^struct/) {
2969                     $decl_type = 'struct';
2970                 } elsif ($identifier =~ m/^union/) {
2971                     $decl_type = 'union';
2972                 } elsif ($identifier =~ m/^enum/) {
2973                     $decl_type = 'enum';
2974                 } elsif ($identifier =~ m/^typedef/) {
2975                     $decl_type = 'typedef';
2976                 } else {
2977                     $decl_type = 'function';
2978                 }
2979
2980                 if ($verbose) {
2981                     print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2982                 }
2983             } else {
2984                 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2985                 " - I thought it was a doc line\n";
2986                 ++$warnings;
2987                 $state = STATE_NORMAL;
2988             }
2989         } elsif ($state == STATE_FIELD) {       # look for head: lines, and include content
2990             if (/$doc_sect/i) { # case insensitive for supported section names
2991                 $newsection = $1;
2992                 $newcontents = $2;
2993
2994                 # map the supported section names to the canonical names
2995                 if ($newsection =~ m/^description$/i) {
2996                     $newsection = $section_default;
2997                 } elsif ($newsection =~ m/^context$/i) {
2998                     $newsection = $section_context;
2999                 } elsif ($newsection =~ m/^returns?$/i) {
3000                     $newsection = $section_return;
3001                 } elsif ($newsection =~ m/^\@return$/) {
3002                     # special: @return is a section, not a param description
3003                     $newsection = $section_return;
3004                 }
3005
3006                 if (($contents ne "") && ($contents ne "\n")) {
3007                     if (!$in_doc_sect && $verbose) {
3008                         print STDERR "${file}:$.: warning: contents before sections\n";
3009                         ++$warnings;
3010                     }
3011                     dump_section($file, $section, xml_escape($contents));
3012                     $section = $section_default;
3013                 }
3014
3015                 $in_doc_sect = 1;
3016                 $in_purpose = 0;
3017                 $contents = $newcontents;
3018                 $new_start_line = $.;
3019                 while ((substr($contents, 0, 1) eq " ") ||
3020                        substr($contents, 0, 1) eq "\t") {
3021                     $contents = substr($contents, 1);
3022                 }
3023                 if ($contents ne "") {
3024                     $contents .= "\n";
3025                 }
3026                 $section = $newsection;
3027                 $leading_space = undef;
3028             } elsif (/$doc_end/) {
3029                 if (($contents ne "") && ($contents ne "\n")) {
3030                     dump_section($file, $section, xml_escape($contents));
3031                     $section = $section_default;
3032                     $contents = "";
3033                 }
3034                 # look for doc_com + <text> + doc_end:
3035                 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
3036                     print STDERR "${file}:$.: warning: suspicious ending line: $_";
3037                     ++$warnings;
3038                 }
3039
3040                 $prototype = "";
3041                 $state = STATE_PROTO;
3042                 $brcount = 0;
3043 #               print STDERR "end of doc comment, looking for prototype\n";
3044             } elsif (/$doc_content/) {
3045                 # miguel-style comment kludge, look for blank lines after
3046                 # @parameter line to signify start of description
3047                 if ($1 eq "") {
3048                     if ($section =~ m/^@/ || $section eq $section_context) {
3049                         dump_section($file, $section, xml_escape($contents));
3050                         $section = $section_default;
3051                         $contents = "";
3052                         $new_start_line = $.;
3053                     } else {
3054                         $contents .= "\n";
3055                     }
3056                     $in_purpose = 0;
3057                 } elsif ($in_purpose == 1) {
3058                     # Continued declaration purpose
3059                     chomp($declaration_purpose);
3060                     $declaration_purpose .= " " . xml_escape($1);
3061                     $declaration_purpose =~ s/\s+/ /g;
3062                 } else {
3063                     my $cont = $1;
3064                     if ($section =~ m/^@/ || $section eq $section_context) {
3065                         if (!defined $leading_space) {
3066                             if ($cont =~ m/^(\s+)/) {
3067                                 $leading_space = $1;
3068                             } else {
3069                                 $leading_space = "";
3070                             }
3071                         }
3072
3073                         $cont =~ s/^$leading_space//;
3074                     }
3075                     $contents .= $cont . "\n";
3076                 }
3077             } else {
3078                 # i dont know - bad line?  ignore.
3079                 print STDERR "${file}:$.: warning: bad line: $_";
3080                 ++$warnings;
3081             }
3082         } elsif ($state == STATE_INLINE) { # scanning for inline parameters
3083             # First line (state 1) needs to be a @parameter
3084             if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
3085                 $section = $1;
3086                 $contents = $2;
3087                 $new_start_line = $.;
3088                 if ($contents ne "") {
3089                     while ((substr($contents, 0, 1) eq " ") ||
3090                            substr($contents, 0, 1) eq "\t") {
3091                         $contents = substr($contents, 1);
3092                     }
3093                     $contents .= "\n";
3094                 }
3095                 $inline_doc_state = STATE_INLINE_TEXT;
3096             # Documentation block end */
3097             } elsif (/$doc_inline_end/) {
3098                 if (($contents ne "") && ($contents ne "\n")) {
3099                     dump_section($file, $section, xml_escape($contents));
3100                     $section = $section_default;
3101                     $contents = "";
3102                 }
3103                 $state = STATE_PROTO;
3104                 $inline_doc_state = STATE_INLINE_NA;
3105             # Regular text
3106             } elsif (/$doc_content/) {
3107                 if ($inline_doc_state == STATE_INLINE_TEXT) {
3108                     $contents .= $1 . "\n";
3109                     # nuke leading blank lines
3110                     if ($contents =~ /^\s*$/) {
3111                         $contents = "";
3112                     }
3113                 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
3114                     $inline_doc_state = STATE_INLINE_ERROR;
3115                     print STDERR "${file}:$.: warning: ";
3116                     print STDERR "Incorrect use of kernel-doc format: $_";
3117                     ++$warnings;
3118                 }
3119             }
3120         } elsif ($state == STATE_PROTO) {       # scanning for function '{' (end of prototype)
3121             if (/$doc_inline_oneline/) {
3122                 $section = $1;
3123                 $contents = $2;
3124                 if ($contents ne "") {
3125                     $contents .= "\n";
3126                     dump_section($file, $section, xml_escape($contents));
3127                     $section = $section_default;
3128                     $contents = "";
3129                 }
3130             } elsif (/$doc_inline_start/) {
3131                 $state = STATE_INLINE;
3132                 $inline_doc_state = STATE_INLINE_NAME;
3133             } elsif ($decl_type eq 'function') {
3134                 process_proto_function($_, $file);
3135             } else {
3136                 process_proto_type($_, $file);
3137             }
3138         } elsif ($state == STATE_DOCBLOCK) {
3139                 if (/$doc_end/)
3140                 {
3141                         dump_doc_section($file, $section, xml_escape($contents));
3142                         $section = $section_default;
3143                         $contents = "";
3144                         $function = "";
3145                         %parameterdescs = ();
3146                         %parametertypes = ();
3147                         @parameterlist = ();
3148                         %sections = ();
3149                         @sectionlist = ();
3150                         $prototype = "";
3151                         $state = STATE_NORMAL;
3152                 }
3153                 elsif (/$doc_content/)
3154                 {
3155                         if ( $1 eq "" )
3156                         {
3157                                 $contents .= $blankline;
3158                         }
3159                         else
3160                         {
3161                                 $contents .= $1 . "\n";
3162                         }
3163                 }
3164         }
3165     }
3166     if ($initial_section_counter == $section_counter) {
3167         if ($output_mode ne "none") {
3168             print STDERR "${file}:1: warning: no structured comments found\n";
3169         }
3170         if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
3171             print STDERR "    Was looking for '$_'.\n" for keys %function_table;
3172         }
3173         if ($output_mode eq "xml") {
3174             # The template wants at least one RefEntry here; make one.
3175             print "<refentry>\n";
3176             print " <refnamediv>\n";
3177             print "  <refname>\n";
3178             print "   ${orig_file}\n";
3179             print "  </refname>\n";
3180             print "  <refpurpose>\n";
3181             print "   Document generation inconsistency\n";
3182             print "  </refpurpose>\n";
3183             print " </refnamediv>\n";
3184             print " <refsect1>\n";
3185             print "  <title>\n";
3186             print "   Oops\n";
3187             print "  </title>\n";
3188             print "  <warning>\n";
3189             print "   <para>\n";
3190             print "    The template for this document tried to insert\n";
3191             print "    the structured comment from the file\n";
3192             print "    <filename>${orig_file}</filename> at this point,\n";
3193             print "    but none was found.\n";
3194             print "    This dummy section is inserted to allow\n";
3195             print "    generation to continue.\n";
3196             print "   </para>\n";
3197             print "  </warning>\n";
3198             print " </refsect1>\n";
3199             print "</refentry>\n";
3200         }
3201     }
3202 }
3203
3204
3205 $kernelversion = get_kernel_version();
3206
3207 # generate a sequence of code that will splice in highlighting information
3208 # using the s// operator.
3209 for (my $k = 0; $k < @highlights; $k++) {
3210     my $pattern = $highlights[$k][0];
3211     my $result = $highlights[$k][1];
3212 #   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
3213     $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
3214 }
3215
3216 # Read the file that maps relative names to absolute names for
3217 # separate source and object directories and for shadow trees.
3218 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
3219         my ($relname, $absname);
3220         while(<SOURCE_MAP>) {
3221                 chop();
3222                 ($relname, $absname) = (split())[0..1];
3223                 $relname =~ s:^/+::;
3224                 $source_map{$relname} = $absname;
3225         }
3226         close(SOURCE_MAP);
3227 }
3228
3229 if ($output_selection == OUTPUT_EXPORTED ||
3230     $output_selection == OUTPUT_INTERNAL) {
3231
3232     push(@export_file_list, @ARGV);
3233
3234     foreach (@export_file_list) {
3235         chomp;
3236         process_export_file($_);
3237     }
3238 }
3239
3240 foreach (@ARGV) {
3241     chomp;
3242     process_file($_);
3243 }
3244 if ($verbose && $errors) {
3245   print STDERR "$errors errors\n";
3246 }
3247 if ($verbose && $warnings) {
3248   print STDERR "$warnings warnings\n";
3249 }
3250
3251 exit($errors);