#!/usr/bin/perl -w use strict; ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved #### Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> #### Copyright (C) 2001 Simon Huggins #### Copyright (C) 2005-2008 Randy Dunlap #### #### #define enhancements by Armin Kuster <akuster@mvista.com> #### Copyright (c) 2000 MontaVista Software, Inc. #### #### This software falls under the GNU General Public License. #### Please read the COPYING file for more information ## # w.o. 03-11-2000: added the '-filelist' option. # 18/01/2001 - Cleanups# Functions prototyped as foo(void) same as foo()# Stop eval'ing where we don't need to.# -- huggie@earth.li # 27/06/2001 - Allowed whitespace after initial "/**" and# allowed comments before function declarations.# -- Christian Kreibich <ck@whoop.org> # Still to do:# - add perldoc documentation# - Look more closely at some of the scarier bits :) # 26/05/2001 - Support for separate source and object trees.# Return error code.# Keith Owens <kaos@ocs.com.au> # 23/09/2001 - Added support for typedefs, structs, enums and unions# Support for Context section; can be terminated using empty line# Small fixes (like spaces vs. \s in regex)# -- Tim Jansen <tim@tjansen.de> ## This will read a 'c' file and scan for embedded comments in the# style of gnome comments (+minor extensions - see below).# # Note: This only supports 'c'. # usage:# kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ]# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile# or# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile## Set output format using one of -docbook -html -text or -man. Default is man.## -no-doc-sections# Do not output DOC: sections## -function funcname# If set, then only generate documentation for the given function(s) or# DOC: section titles. All other functions and DOC: sections are ignored.## -nofunction funcname# If set, then only generate documentation for the other function(s)/DOC:# sections. Cannot be used together with -function (yes, that's a bug --# perl hackers can fix it 8))## c files - list of 'c' files to process## All output goes to stdout, with errors to stderr. ## format of comments.# In the following table, (...)? signifies optional structure.# (...)* signifies 0 or more structure elements# /**# * function_name(:)? (- short description)?# (* @parameterx: (description of parameter x)?)*# (* a blank line)?# * (Description:)? (Description of function)?# * (section header: (section description)? )*# (*)?*/## So .. the trivial example would be:## /**# * my_function# **/## If the Description: header tag is omitted, then there must be a blank line# after the last parameter specification.# e.g.# /**# * my_function - does my stuff# * @my_arg: its mine damnit# *# * Does my stuff explained.# */## or, could also use:# /**# * my_function - does my stuff# * @my_arg: its mine damnit# * Description: Does my stuff explained.# */# etc.## Beside functions you can also write documentation for structs, unions,# enums and typedefs. Instead of the function name you must write the name# of the declaration; the struct/union/enum/typedef must always precede# the name. Nesting of declarations is not supported.# Use the argument mechanism to document members or constants.# e.g.# /**# * struct my_struct - short description# * @a: first member# * @b: second member# *# * Longer description# */# struct my_struct {# int a;# int b;# /* private: */# int c;# };## All descriptions can be multiline, except the short function description.## You can also add additional sections. When documenting kernel functions you# should document the "Context:" of the function, e.g. whether the functions# can be called form interrupts. Unlike other sections you can end it with an# empty line.# Example-sections should contain the string EXAMPLE so that they are marked# appropriately in DocBook.## Example:# /**# * user_function - function that can only be called in user context# * @a: some argument# * Context: !in_interrupt()# *# * Some description# * Example:# * user_function(22);# */# ...### All descriptive text is further processed, scanning for the following special# patterns, which are highlighted appropriately.## 'funcname()' - function# '$ENVVAR' - environmental variable# '&struct_name' - name of a structure (up to two words including 'struct')# '@parameter' - name of a parameter# '%CONST' - name of a constant. my $errors = 0;my $warnings = 0;my $anon_struct_union = 0; # match expressions used to find embedded type informationmy $type_constant = '\%([-_\w]+)';my $type_func = '(\w+)\(\)';my $type_param = '\@(\w+)';my $type_struct = '\&((struct\s*)*[_\w]+)';my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';my $type_env = '(\$\w+)'; # Output conversion substitutions.# One for each output format # these work fairly wellmy %highlights_html = ( $type_constant, "<i>\$1</i>", $type_func, "<b>\$1</b>", $type_struct_xml, "<i>\$1</i>", $type_env, "<b><i>\$1</i></b>", $type_param, "<tt><b>\$1</b></tt>" );my $local_lt = "\\\\\\\\lt:";my $local_gt = "\\\\\\\\gt:";my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" # XML, docbook formatmy %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>", $type_constant, "<constant>\$1</constant>", $type_func, "<function>\$1</function>", $type_struct_xml, "<structname>\$1</structname>", $type_env, "<envar>\$1</envar>", $type_param, "<parameter>\$1</parameter>" );my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook formatmy %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>", $type_func, "<function>\$1</function>", $type_struct, "<structname>\$1</structname>", $type_env, "<envar>\$1</envar>", $type_param, "<parameter>\$1</parameter>" );my $blankline_gnome = "</para><para>\n"; # these are pretty roughmy %highlights_man = ( $type_constant, "\$1", $type_func, "\\\\fB\$1\\\\fP", $type_struct, "\\\\fI\$1\\\\fP", $type_param, "\\\\fI\$1\\\\fP" );my $blankline_man = ""; # text-modemy %highlights_text = ( $type_constant, "\$1", $type_func, "\$1", $type_struct, "\$1", $type_param, "\$1" );my $blankline_text = ""; sub usage { print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n"; print " [ -function funcname [ -function funcname ...] ]\n"; print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; print " c source file(s) > outputfile\n"; print " -v : verbose output, more warnings & other info listed\n"; exit 1;} # read argumentsif ($#ARGV==-1) { usage();} my $verbose = 0;my $output_mode = "man";my $no_doc_sections = 0;my %highlights = %highlights_man;my $blankline = $blankline_man;my $modulename = "Kernel API";my $function_only = 0;my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')[(localtime)[4]] . " " . ((localtime)[5]+1900); # Essentially these are globals# They probably want to be tidied up made more localised or summat.# CAVEAT EMPTOR! Some of the others I localised may not want to be which# could cause "use of undefined value" or other bugs.my ($function, %function_table,%parametertypes,$declaration_purpose);my ($type,$declaration_name,$return_type);my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map); if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}";} # Generated docbook code is inserted in a template at a point where# docbook v3.1 requires a non-zero sequence of RefEntry's; see:# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html# We keep track of number of generated entries and generate a dummy# if needs be to ensure the expanded template can be postprocessed# into html.my $section_counter = 0; my $lineprefix=""; # states# 0 - normal code# 1 - looking for function name# 2 - scanning field start.# 3 - scanning prototype.# 4 - documentation blockmy $state;my $in_doc_sect; #declaration types: can be# 'function', 'struct', 'union', 'enum', 'typedef'my $decl_type; my $doc_special = "\@\%\$\&"; my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.my $doc_end = '\*/';my $doc_com = '\s*\*\s*';my $doc_decl = $doc_com.'(\w+)';my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';my $doc_content = $doc_com.'(.*)';my $doc_block = $doc_com.'DOC:\s*(.*)?'; my %constants;my %parameterdescs;my @parameterlist;my %sections;my @sectionlist;my $sectcheck;my $struct_actual; my $contents = "";my $section_default = "Description"; # default sectionmy $section_intro = "Introduction";my $section = $section_default;my $section_context = "Context"; my $undescribed = "-- undescribed --"; reset_state(); while ($ARGV[0] =~ m/^-(.*)/) { my $cmd = shift @ARGV; if ($cmd eq "-html") { $output_mode = "html"; %highlights = %highlights_html; $blankline = $blankline_html; } elsif ($cmd eq "-man") { $output_mode = "man"; %highlights = %highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "-text") { $output_mode = "text"; %highlights = %highlights_text; $blankline = $blankline_text; } elsif ($cmd eq "-docbook") { $output_mode = "xml"; %highlights = %highlights_xml; $blankline = $blankline_xml; } elsif ($cmd eq "-gnome") { $output_mode = "gnome"; %highlights = %highlights_gnome; $blankline = $blankline_gnome; } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; } elsif ($cmd eq "-function") { # to only output specific functions $function_only = 1; $function = shift @ARGV; $function_table{$function} = 1; } elsif ($cmd eq "-nofunction") { # to only output specific functions $function_only = 2; $function = shift @ARGV; $function_table{$function} = 1; } elsif ($cmd eq "-v") { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { usage(); } elsif ($cmd eq '-filelist') { $filelist = shift @ARGV; } elsif ($cmd eq '-no-doc-sections') { $no_doc_sections = 1; }} # get kernel version from envsub get_kernel_version() { my $version = 'unknown kernel version'; if (defined($ENV{'KERNELVERSION'})) { $version = $ENV{'KERNELVERSION'}; } return $version;}my $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information# using the s// operator.my $dohighlight = "";foreach my $pattern (keys %highlights) {# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";} ### dumps section contents to arrays/hashes intended for that purpose.#sub dump_section { my $file = shift; my $name = shift; my $contents = join "\n", @_; if ($name =~ m/$type_constant/) { $name = $1;# print STDERR "constant section '$1' = '$contents'\n"; $constants{$name} = $contents; } elsif ($name =~ m/$type_param/) {# print STDERR "parameter def '$1' = '$contents'\n"; $name = $1; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; } elsif ($name eq "@\.\.\.") {# print STDERR "parameter def '...' = '$contents'\n"; $name = "..."; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; } else {# print STDERR "other section '$name' = '$contents'\n"; if (defined($sections{$name}) && ($sections{$name} ne "")) { print STDERR "Error(${file}:$.): duplicate section name '$name'\n"; ++$errors; } $sections{$name} = $contents; push @sectionlist, $name; }} ### dump DOC: section after checking that it should go out#sub dump_doc_section { my $file = shift; my $name = shift; my $contents = join "\n", @_; if ($no_doc_sections) { return; } if (($function_only == 0) || ( $function_only == 1 && defined($function_table{$name})) || ( $function_only == 2 && !defined($function_table{$name}))) { dump_section($file, $name, $contents); output_blockhead({'sectionlist' => \@sectionlist, 'sections' => \%sections, 'module' => $modulename, 'content-only' => ($function_only != 0), }); }} ### output function## parameterdescs, a hash.# function => "function name"# parameterlist => @list of parameters# parameterdescs => %parameter descriptions# sectionlist => @list of sections# sections => %section descriptions# sub output_highlight { my $contents = join "\n",@_; my $line; # DEBUG# if (!defined $contents) {# use Carp;# confess "output_highlight got called with no args?\n";# } if ($output_mode eq "html" || $output_mode eq "xml") { $contents = local_unescape($contents); # convert data read & converted thru xml_escape() into &xyz; format: $contents =~ s/\\\\\\/&/g; }# print STDERR "contents b4:$contents\n"; eval $dohighlight; die $@ if $@;# print STDERR "contents af:$contents\n"; foreach $line (split "\n", $contents) { if ($line eq ""){ print $lineprefix, local_unescape($blankline); } else { $line =~ s/\\\\\\/\&/g; if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { print "\\&$line"; } else { print $lineprefix, $line; } } print "\n"; }} #output sections in htmlsub output_section_html(%) { my %args = %{$_[0]}; my $section; foreach $section (@{$args{'sectionlist'}}) { print "<h3>$section</h3>\n"; print "<blockquote>\n"; output_highlight($args{'sections'}{$section}); print "</blockquote>\n"; }} # output enum in htmlsub output_enum_html(%) { my %args = %{$_[0]}; my ($parameter); my $count; print "<h2>enum ".$args{'enum'}."</h2>\n"; print "<b>enum ".$args{'enum'}."</b> {<br>\n"; $count = 0; foreach $parameter (@{$args{'parameterlist'}}) { print " <b>".$parameter."</b>"; if ($count != $#{$args{'parameterlist'}}) { $count++; print ",\n"; } print "<br>"; } print "};<br>\n";Lines 1–500 of 2176. Load more
#!/usr/bin/perl -w use strict; ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## ## Copyright (C) 2001 Simon Huggins ## ## Copyright (C) 2005-2008 Randy Dunlap ## ## ## ## #define enhancements by Armin Kuster <akuster@mvista.com> ## ## Copyright (c) 2000 MontaVista Software, Inc. ## ## ## ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## # w.o. 03-11-2000: added the '-filelist' option. # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. # -- huggie@earth.li # 27/06/2001 - Allowed whitespace after initial "/**" and # allowed comments before function declarations. # -- Christian Kreibich <ck@whoop.org> # Still to do: # - add perldoc documentation # - Look more closely at some of the scarier bits :) # 26/05/2001 - Support for separate source and object trees. # Return error code. # Keith Owens <kaos@ocs.com.au> # 23/09/2001 - Added support for typedefs, structs, enums and unions # Support for Context section; can be terminated using empty line # Small fixes (like spaces vs. \s in regex) # -- Tim Jansen <tim@tjansen.de> # # This will read a 'c' file and scan for embedded comments in the # style of gnome comments (+minor extensions - see below). # # Note: This only supports 'c'. # usage: # kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ] # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile # or # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile # # Set output format using one of -docbook -html -text or -man. Default is man. # # -no-doc-sections # Do not output DOC: sections # # -function funcname # If set, then only generate documentation for the given function(s) or # DOC: section titles. All other functions and DOC: sections are ignored. # # -nofunction funcname # If set, then only generate documentation for the other function(s)/DOC: # sections. Cannot be used together with -function (yes, that's a bug -- # perl hackers can fix it 8)) # # c files - list of 'c' files to process # # All output goes to stdout, with errors to stderr. # # format of comments. # In the following table, (...)? signifies optional structure. # (...)* signifies 0 or more structure elements # /** # * function_name(:)? (- short description)? # (* @parameterx: (description of parameter x)?)* # (* a blank line)? # * (Description:)? (Description of function)? # * (section header: (section description)? )* # (*)?*/ # # So .. the trivial example would be: # # /** # * my_function # **/ # # If the Description: header tag is omitted, then there must be a blank line # after the last parameter specification. # e.g. # /** # * my_function - does my stuff # * @my_arg: its mine damnit # * # * Does my stuff explained. # */ # # or, could also use: # /** # * my_function - does my stuff # * @my_arg: its mine damnit # * Description: Does my stuff explained. # */ # etc. # # Beside functions you can also write documentation for structs, unions, # enums and typedefs. Instead of the function name you must write the name # of the declaration; the struct/union/enum/typedef must always precede # the name. Nesting of declarations is not supported. # Use the argument mechanism to document members or constants. # e.g. # /** # * struct my_struct - short description # * @a: first member # * @b: second member # * # * Longer description # */ # struct my_struct { # int a; # int b; # /* private: */ # int c; # }; # # All descriptions can be multiline, except the short function description. # # You can also add additional sections. When documenting kernel functions you # should document the "Context:" of the function, e.g. whether the functions # can be called form interrupts. Unlike other sections you can end it with an # empty line. # Example-sections should contain the string EXAMPLE so that they are marked # appropriately in DocBook. # # Example: # /** # * user_function - function that can only be called in user context # * @a: some argument # * Context: !in_interrupt() # * # * Some description # * Example: # * user_function(22); # */ # ... # # # All descriptive text is further processed, scanning for the following special # patterns, which are highlighted appropriately. # # 'funcname()' - function # '$ENVVAR' - environmental variable # '&struct_name' - name of a structure (up to two words including 'struct') # '@parameter' - name of a parameter # '%CONST' - name of a constant. my $errors = 0; my $warnings = 0; my $anon_struct_union = 0; # match expressions used to find embedded type information my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+)'; my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; # Output conversion substitutions. # One for each output format # these work fairly well my %highlights_html = ( $type_constant, "<i>\$1</i>", $type_func, "<b>\$1</b>", $type_struct_xml, "<i>\$1</i>", $type_env, "<b><i>\$1</i></b>", $type_param, "<tt><b>\$1</b></tt>" ); my $local_lt = "\\\\\\\\lt:"; my $local_gt = "\\\\\\\\gt:"; my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" # XML, docbook format my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>", $type_constant, "<constant>\$1</constant>", $type_func, "<function>\$1</function>", $type_struct_xml, "<structname>\$1</structname>", $type_env, "<envar>\$1</envar>", $type_param, "<parameter>\$1</parameter>" ); my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook format my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>", $type_func, "<function>\$1</function>", $type_struct, "<structname>\$1</structname>", $type_env, "<envar>\$1</envar>", $type_param, "<parameter>\$1</parameter>" ); my $blankline_gnome = "</para><para>\n"; # these are pretty rough my %highlights_man = ( $type_constant, "\$1", $type_func, "\\\\fB\$1\\\\fP", $type_struct, "\\\\fI\$1\\\\fP", $type_param, "\\\\fI\$1\\\\fP" ); my $blankline_man = ""; # text-mode my %highlights_text = ( $type_constant, "\$1", $type_func, "\$1", $type_struct, "\$1", $type_param, "\$1" ); my $blankline_text = ""; sub usage { print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n"; print " [ -function funcname [ -function funcname ...] ]\n"; print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; print " c source file(s) > outputfile\n"; print " -v : verbose output, more warnings & other info listed\n"; exit 1; } # read arguments if ($#ARGV==-1) { usage(); } my $verbose = 0; my $output_mode = "man"; my $no_doc_sections = 0; my %highlights = %highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; my $function_only = 0; my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')[(localtime)[4]] . " " . ((localtime)[5]+1900); # Essentially these are globals # They probably want to be tidied up made more localised or summat. # CAVEAT EMPTOR! Some of the others I localised may not want to be which # could cause "use of undefined value" or other bugs. my ($function, %function_table,%parametertypes,$declaration_purpose); my ($type,$declaration_name,$return_type); my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map); if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}"; } # Generated docbook code is inserted in a template at a point where # docbook v3.1 requires a non-zero sequence of RefEntry's; see: # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html # We keep track of number of generated entries and generate a dummy # if needs be to ensure the expanded template can be postprocessed # into html. my $section_counter = 0; my $lineprefix=""; # states # 0 - normal code # 1 - looking for function name # 2 - scanning field start. # 3 - scanning prototype. # 4 - documentation block my $state; my $in_doc_sect; #declaration types: can be # 'function', 'struct', 'union', 'enum', 'typedef' my $decl_type; my $doc_special = "\@\%\$\&"; my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. my $doc_end = '\*/'; my $doc_com = '\s*\*\s*'; my $doc_decl = $doc_com.'(\w+)'; my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)'; my $doc_content = $doc_com.'(.*)'; my $doc_block = $doc_com.'DOC:\s*(.*)?'; my %constants; my %parameterdescs; my @parameterlist; my %sections; my @sectionlist; my $sectcheck; my $struct_actual; my $contents = ""; my $section_default = "Description"; # default section my $section_intro = "Introduction"; my $section = $section_default; my $section_context = "Context"; my $undescribed = "-- undescribed --"; reset_state(); while ($ARGV[0] =~ m/^-(.*)/) { my $cmd = shift @ARGV; if ($cmd eq "-html") { $output_mode = "html"; %highlights = %highlights_html; $blankline = $blankline_html; } elsif ($cmd eq "-man") { $output_mode = "man"; %highlights = %highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "-text") { $output_mode = "text"; %highlights = %highlights_text; $blankline = $blankline_text; } elsif ($cmd eq "-docbook") { $output_mode = "xml"; %highlights = %highlights_xml; $blankline = $blankline_xml; } elsif ($cmd eq "-gnome") { $output_mode = "gnome"; %highlights = %highlights_gnome; $blankline = $blankline_gnome; } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; } elsif ($cmd eq "-function") { # to only output specific functions $function_only = 1; $function = shift @ARGV; $function_table{$function} = 1; } elsif ($cmd eq "-nofunction") { # to only output specific functions $function_only = 2; $function = shift @ARGV; $function_table{$function} = 1; } elsif ($cmd eq "-v") { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { usage(); } elsif ($cmd eq '-filelist') { $filelist = shift @ARGV; } elsif ($cmd eq '-no-doc-sections') { $no_doc_sections = 1; } } # get kernel version from env sub get_kernel_version() { my $version = 'unknown kernel version'; if (defined($ENV{'KERNELVERSION'})) { $version = $ENV{'KERNELVERSION'}; } return $version; } my $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information # using the s// operator. my $dohighlight = ""; foreach my $pattern (keys %highlights) { # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; } ## # dumps section contents to arrays/hashes intended for that purpose. # sub dump_section { my $file = shift; my $name = shift; my $contents = join "\n", @_; if ($name =~ m/$type_constant/) { $name = $1; # print STDERR "constant section '$1' = '$contents'\n"; $constants{$name} = $contents; } elsif ($name =~ m/$type_param/) { # print STDERR "parameter def '$1' = '$contents'\n"; $name = $1; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; } elsif ($name eq "@\.\.\.") { # print STDERR "parameter def '...' = '$contents'\n"; $name = "..."; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; } else { # print STDERR "other section '$name' = '$contents'\n"; if (defined($sections{$name}) && ($sections{$name} ne "")) { print STDERR "Error(${file}:$.): duplicate section name '$name'\n"; ++$errors; } $sections{$name} = $contents; push @sectionlist, $name; } } ## # dump DOC: section after checking that it should go out # sub dump_doc_section { my $file = shift; my $name = shift; my $contents = join "\n", @_; if ($no_doc_sections) { return; } if (($function_only == 0) || ( $function_only == 1 && defined($function_table{$name})) || ( $function_only == 2 && !defined($function_table{$name}))) { dump_section($file, $name, $contents); output_blockhead({'sectionlist' => \@sectionlist, 'sections' => \%sections, 'module' => $modulename, 'content-only' => ($function_only != 0), }); } } ## # output function # # parameterdescs, a hash. # function => "function name" # parameterlist => @list of parameters # parameterdescs => %parameter descriptions # sectionlist => @list of sections # sections => %section descriptions # sub output_highlight { my $contents = join "\n",@_; my $line; # DEBUG # if (!defined $contents) { # use Carp; # confess "output_highlight got called with no args?\n"; # } if ($output_mode eq "html" || $output_mode eq "xml") { $contents = local_unescape($contents); # convert data read & converted thru xml_escape() into &xyz; format: $contents =~ s/\\\\\\/&/g; } # print STDERR "contents b4:$contents\n"; eval $dohighlight; die $@ if $@; # print STDERR "contents af:$contents\n"; foreach $line (split "\n", $contents) { if ($line eq ""){ print $lineprefix, local_unescape($blankline); } else { $line =~ s/\\\\\\/\&/g; if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { print "\\&$line"; } else { print $lineprefix, $line; } } print "\n"; } } #output sections in html sub output_section_html(%) { my %args = %{$_[0]}; my $section; foreach $section (@{$args{'sectionlist'}}) { print "<h3>$section</h3>\n"; print "<blockquote>\n"; output_highlight($args{'sections'}{$section}); print "</blockquote>\n"; } } # output enum in html sub output_enum_html(%) { my %args = %{$_[0]}; my ($parameter); my $count; print "<h2>enum ".$args{'enum'}."</h2>\n"; print "<b>enum ".$args{'enum'}."</b> {<br>\n"; $count = 0; foreach $parameter (@{$args{'parameterlist'}}) { print " <b>".$parameter."</b>"; if ($count != $#{$args{'parameterlist'}}) { $count++; print ",\n"; } print "<br>"; } print "};<br>\n";