kernel-doc (857af3b775940865c215ab168212ebc96ab80f57) kernel-doc (b05142675310d2ac80276569e151742f880e3ec3)
1#!/usr/bin/env perl
2
3use warnings;
4use 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 ##

--- 37 unchanged lines hidden (view full) ---

46
47Read C language source or header FILEs, extract embedded documentation comments,
48and print formatted documentation to standard output.
49
50The documentation comments are identified by "/**" opening comment mark. See
51Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
52
53Output format selection (mutually exclusive):
1#!/usr/bin/env perl
2
3use warnings;
4use 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 ##

--- 37 unchanged lines hidden (view full) ---

46
47Read C language source or header FILEs, extract embedded documentation comments,
48and print formatted documentation to standard output.
49
50The documentation comments are identified by "/**" opening comment mark. See
51Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
52
53Output 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.
54 -man Output troff manual page format. This is the default.
55 -rst Output reStructuredText format.
60 -text Output plain text format.
61 -none Do not output documentation, only warnings.
62
63Output 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()

--- 151 unchanged lines hidden (view full) ---

220my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
221my $type_env = '(\$\w+)';
222my $type_enum = '\&(enum\s*([_\w]+))';
223my $type_struct = '\&(struct\s*([_\w]+))';
224my $type_typedef = '\&(typedef\s*([_\w]+))';
225my $type_union = '\&(union\s*([_\w]+))';
226my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
227my $type_fallback = '\&([_\w]+)';
56 -none Do not output documentation, only warnings.
57
58Output selection (mutually exclusive):
59 -export Only output documentation for symbols that have been
60 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
61 in any input FILE or -export-file FILE.
62 -internal Only output documentation for symbols that have NOT been
63 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()

--- 151 unchanged lines hidden (view full) ---

215my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
216my $type_env = '(\$\w+)';
217my $type_enum = '\&(enum\s*([_\w]+))';
218my $type_struct = '\&(struct\s*([_\w]+))';
219my $type_typedef = '\&(typedef\s*([_\w]+))';
220my $type_union = '\&(union\s*([_\w]+))';
221my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
222my $type_fallback = '\&([_\w]+)';
228my $type_enum_xml = '\&amp;(enum\s*([_\w]+))';
229my $type_struct_xml = '\&amp;(struct\s*([_\w]+))';
230my $type_typedef_xml = '\&amp;(typedef\s*([_\w]+))';
231my $type_union_xml = '\&amp;(union\s*([_\w]+))';
232my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
233my $type_fallback_xml = '\&amp([_\w]+)';
234my $type_member_func = $type_member . '\(\)';
235
236# Output conversion substitutions.
237# One for each output format
238
223my $type_member_func = $type_member . '\(\)';
224
225# Output conversion substitutions.
226# One for each output format
227
239# these work fairly well
240my @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 );
253my $local_lt = "\\\\\\\\lt:";
254my $local_gt = "\\\\\\\\gt:";
255my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
256
257# html version 5
258my @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 );
271my $blankline_html5 = $local_lt . "br /" . $local_gt;
272
273# XML, docbook format
274my @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 );
288my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
289
290# gnome, docbook format
291my @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 );
304my $blankline_gnome = "</para><para>\n";
305
306# these are pretty rough
307my @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 );
319my $blankline_man = "";
320
228# these are pretty rough
229my @highlights_man = (
230 [$type_constant, "\$1"],
231 [$type_constant2, "\$1"],
232 [$type_func, "\\\\fB\$1\\\\fP"],
233 [$type_enum, "\\\\fI\$1\\\\fP"],
234 [$type_struct, "\\\\fI\$1\\\\fP"],
235 [$type_typedef, "\\\\fI\$1\\\\fP"],
236 [$type_union, "\\\\fI\$1\\\\fP"],
237 [$type_param, "\\\\fI\$1\\\\fP"],
238 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
239 [$type_fallback, "\\\\fI\$1\\\\fP"]
240 );
241my $blankline_man = "";
242
321# text-mode
322my @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 );
334my $blankline_text = "";
335
336# rst-mode
337my @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 );
353my $blankline_rst = "\n";
354
243# rst-mode
244my @highlights_rst = (
245 [$type_constant, "``\$1``"],
246 [$type_constant2, "``\$1``"],
247 # Note: need to escape () to avoid func matching later
248 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
249 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
250 [$type_fp_param, "**\$1\\\\(\\\\)**"],
251 [$type_func, "\\:c\\:func\\:`\$1()`"],
252 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
253 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
254 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
255 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
256 # in rst this can refer to any type
257 [$type_fallback, "\\:c\\:type\\:`\$1`"],
258 [$type_param, "**\$1**"]
259 );
260my $blankline_rst = "\n";
261
355# list mode
356my @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 );
368my $blankline_list = "";
369
370# read arguments
371if ($#ARGV == -1) {
372 usage();
373}
374
375my $kernelversion;
376my $dohighlight = "";
377

--- 118 unchanged lines hidden (view full) ---

496my $section_return = "Return";
497
498my $undescribed = "-- undescribed --";
499
500reset_state();
501
502while ($ARGV[0] =~ m/^-(.*)/) {
503 my $cmd = shift @ARGV;
262# read arguments
263if ($#ARGV == -1) {
264 usage();
265}
266
267my $kernelversion;
268my $dohighlight = "";
269

--- 118 unchanged lines hidden (view full) ---

388my $section_return = "Return";
389
390my $undescribed = "-- undescribed --";
391
392reset_state();
393
394while ($ARGV[0] =~ m/^-(.*)/) {
395 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") {
396 if ($cmd eq "-man") {
513 $output_mode = "man";
514 @highlights = @highlights_man;
515 $blankline = $blankline_man;
397 $output_mode = "man";
398 @highlights = @highlights_man;
399 $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;
400 } elsif ($cmd eq "-rst") {
401 $output_mode = "rst";
402 @highlights = @highlights_rst;
403 $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;

--- 121 unchanged lines hidden (view full) ---

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
404 } elsif ($cmd eq "-none") {
405 $output_mode = "none";
406 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
407 $modulename = shift @ARGV;
408 } elsif ($cmd eq "-function") { # to only output specific functions
409 $output_selection = OUTPUT_INCLUDE;
410 $function = shift @ARGV;
411 $function_table{$function} = 1;

--- 121 unchanged lines hidden (view full) ---

533 my $line;
534
535# DEBUG
536# if (!defined $contents) {
537# use Carp;
538# confess "output_highlight got called with no args?\n";
539# }
540
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
541# print STDERR "contents b4:$contents\n";
542 eval $dohighlight;
543 die $@ if $@;
544# print STDERR "contents af:$contents\n";
545
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 }

--- 4 unchanged lines hidden (view full) ---

701 } else {
702 print $lineprefix, $line;
703 }
704 }
705 print "\n";
706 }
707}
708
546 foreach $line (split "\n", $contents) {
547 if (! $output_preformatted) {
548 $line =~ s/^\s*//;
549 }
550 if ($line eq ""){
551 if (! $output_preformatted) {
552 print $lineprefix, local_unescape($blankline);
553 }

--- 4 unchanged lines hidden (view full) ---

558 } else {
559 print $lineprefix, $line;
560 }
561 }
562 print "\n";
563 }
564}
565
709# output sections in html
710sub 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
723sub 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
754sub 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
766sub 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
813sub 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
855sub 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
870sub 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
885sub 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
929sub 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
951sub 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
1022sub 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
1084sub 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
1102sub 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
1128sub 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
1207sub 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
1301sub 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
1369sub 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
1406sub 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
1442sub 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
1522sub 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";

--- 162 unchanged lines hidden (view full) ---

1690
1691 foreach $section (@{$args{'sectionlist'}}) {
1692 print ".SH \"$section\"\n";
1693 output_highlight($args{'sections'}{$section});
1694 }
1695}
1696
1697##
566##
567# output function in man
568sub output_function_man(%) {
569 my %args = %{$_[0]};
570 my ($parameter, $section);
571 my $count;
572
573 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";

--- 162 unchanged lines hidden (view full) ---

736
737 foreach $section (@{$args{'sectionlist'}}) {
738 print ".SH \"$section\"\n";
739 output_highlight($args{'sections'}{$section});
740 }
741}
742
743##
1698# output in text
1699sub 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
1744sub 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
1757sub 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
1786sub 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
1797sub 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
1841sub 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#

--- 217 unchanged lines hidden (view full) ---

2078 print "\n";
2079 }
2080 print "\n";
2081
2082 $lineprefix = $oldprefix;
2083 output_section_rst(@_);
2084}
2085
744# output in restructured text
745#
746
747#
748# This could use some work; it's used to output the DOC: sections, and
749# starts by putting out the name of the doc section itself, but that tends
750# to duplicate a header already in the template file.
751#

--- 217 unchanged lines hidden (view full) ---

969 print "\n";
970 }
971 print "\n";
972
973 $lineprefix = $oldprefix;
974 output_section_rst(@_);
975}
976
2086
2087## list mode output functions
2088
2089sub output_function_list(%) {
2090 my %args = %{$_[0]};
2091
2092 print $args{'function'} . "\n";
2093}
2094
2095# output enum in list
2096sub output_enum_list(%) {
2097 my %args = %{$_[0]};
2098 print $args{'enum'} . "\n";
2099}
2100
2101# output typedef in list
2102sub output_typedef_list(%) {
2103 my %args = %{$_[0]};
2104 print $args{'typedef'} . "\n";
2105}
2106
2107# output struct as list
2108sub output_struct_list(%) {
2109 my %args = %{$_[0]};
2110
2111 print $args{'struct'} . "\n";
2112}
2113
2114sub 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
2126sub output_function_none(%) {
2127}
2128
2129sub output_enum_none(%) {
2130}
2131

--- 690 unchanged lines hidden (view full) ---

2822#
2823# however, formatting controls that are generated internally/locally in the
2824# kernel-doc script are not escaped here; instead, they begin life like
2825# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2826# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2827# just before actual output; (this is done by local_unescape())
2828sub xml_escape($) {
2829 my $text = shift;
977## none mode output functions
978
979sub output_function_none(%) {
980}
981
982sub output_enum_none(%) {
983}
984

--- 690 unchanged lines hidden (view full) ---

1675#
1676# however, formatting controls that are generated internally/locally in the
1677# kernel-doc script are not escaped here; instead, they begin life like
1678# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
1679# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
1680# just before actual output; (this is done by local_unescape())
1681sub xml_escape($) {
1682 my $text = shift;
2830 if (($output_mode eq "text") || ($output_mode eq "man")) {
1683 if ($output_mode eq "man") {
2831 return $text;
2832 }
2833 $text =~ s/\&/\\\\\\amp;/g;
2834 $text =~ s/\</\\\\\\lt;/g;
2835 $text =~ s/\>/\\\\\\gt;/g;
2836 return $text;
2837}
2838
2839# xml_unescape: reverse the effects of xml_escape
2840sub xml_unescape($) {
2841 my $text = shift;
1684 return $text;
1685 }
1686 $text =~ s/\&/\\\\\\amp;/g;
1687 $text =~ s/\</\\\\\\lt;/g;
1688 $text =~ s/\>/\\\\\\gt;/g;
1689 return $text;
1690}
1691
1692# xml_unescape: reverse the effects of xml_escape
1693sub xml_unescape($) {
1694 my $text = shift;
2842 if (($output_mode eq "text") || ($output_mode eq "man")) {
1695 if ($output_mode eq "man") {
2843 return $text;
2844 }
2845 $text =~ s/\\\\\\amp;/\&/g;
2846 $text =~ s/\\\\\\lt;/</g;
2847 $text =~ s/\\\\\\gt;/>/g;
2848 return $text;
2849}
2850
2851# convert local escape strings to html
2852# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2853sub local_unescape($) {
2854 my $text = shift;
1696 return $text;
1697 }
1698 $text =~ s/\\\\\\amp;/\&/g;
1699 $text =~ s/\\\\\\lt;/</g;
1700 $text =~ s/\\\\\\gt;/>/g;
1701 return $text;
1702}
1703
1704# convert local escape strings to html
1705# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
1706sub local_unescape($) {
1707 my $text = shift;
2855 if (($output_mode eq "text") || ($output_mode eq "man")) {
1708 if ($output_mode eq "man") {
2856 return $text;
2857 }
2858 $text =~ s/\\\\\\\\lt:/</g;
2859 $text =~ s/\\\\\\\\gt:/>/g;
2860 return $text;
2861}
2862
2863sub map_filename($) {

--- 305 unchanged lines hidden (view full) ---

3169 }
3170 if ($initial_section_counter == $section_counter) {
3171 if ($output_mode ne "none") {
3172 print STDERR "${file}:1: warning: no structured comments found\n";
3173 }
3174 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
3175 print STDERR " Was looking for '$_'.\n" for keys %function_table;
3176 }
1709 return $text;
1710 }
1711 $text =~ s/\\\\\\\\lt:/</g;
1712 $text =~ s/\\\\\\\\gt:/>/g;
1713 return $text;
1714}
1715
1716sub map_filename($) {

--- 305 unchanged lines hidden (view full) ---

2022 }
2023 if ($initial_section_counter == $section_counter) {
2024 if ($output_mode ne "none") {
2025 print STDERR "${file}:1: warning: no structured comments found\n";
2026 }
2027 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2028 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2029 }
3177 if ($output_mode eq "xml") {
3178 # The template wants at least one RefEntry here; make one.
3179 print "<refentry>\n";
3180 print " <refnamediv>\n";
3181 print " <refname>\n";
3182 print " ${orig_file}\n";
3183 print " </refname>\n";
3184 print " <refpurpose>\n";
3185 print " Document generation inconsistency\n";
3186 print " </refpurpose>\n";
3187 print " </refnamediv>\n";
3188 print " <refsect1>\n";
3189 print " <title>\n";
3190 print " Oops\n";
3191 print " </title>\n";
3192 print " <warning>\n";
3193 print " <para>\n";
3194 print " The template for this document tried to insert\n";
3195 print " the structured comment from the file\n";
3196 print " <filename>${orig_file}</filename> at this point,\n";
3197 print " but none was found.\n";
3198 print " This dummy section is inserted to allow\n";
3199 print " generation to continue.\n";
3200 print " </para>\n";
3201 print " </warning>\n";
3202 print " </refsect1>\n";
3203 print "</refentry>\n";
3204 }
3205 }
3206}
3207
3208
3209$kernelversion = get_kernel_version();
3210
3211# generate a sequence of code that will splice in highlighting information
3212# using the s// operator.

--- 43 unchanged lines hidden --- 		2030 }
2031}
2032
2033
2034$kernelversion = get_kernel_version();
2035
2036# generate a sequence of code that will splice in highlighting information
2037# using the s// operator.

--- 43 unchanged lines hidden ---