From: Pavel Pisa Date: Sun, 8 Nov 2009 16:36:10 +0000 (+0100) Subject: uLUt documentation converted to XML DocBook variant. X-Git-Tag: ul_drv-0.8.0-release~3 X-Git-Url: https://rtime.felk.cvut.cz/gitweb/ulut.git/commitdiff_plain/894626e4c13e49d3d20d3a1f8b61116451a2b5f8 uLUt documentation converted to XML DocBook variant. Signed-off-by: Pavel Pisa --- diff --git a/doc/srcdoc/Makefile b/doc/srcdoc/Makefile index cd9d8a6..6a4d099 100644 --- a/doc/srcdoc/Makefile +++ b/doc/srcdoc/Makefile @@ -20,18 +20,18 @@ export TMPL2SGML KERNELDOC=$(SCRIPTDIR)/kernel-doc export KERNELDOC -.PHONY: all default fig-prepare sgmldocs htmldocs pdfdocs clean +.PHONY: all default fig-prepare xmldocs htmldocs pdfdocs clean -$(DOCOUTDIR)/%.sgml: %.tmpl +$(DOCOUTDIR)/%.xml: %.tmpl $(TMPL2SGML) $< >$@ -$(DOCOUTDIR)/%.pdf : $(DOCOUTDIR)/%.sgml +$(DOCOUTDIR)/%.pdf : $(DOCOUTDIR)/%.xml @(which db2pdf > /dev/null 2>&1) || \ (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) cd $(dir $@) && db2pdf $< -$(DOCOUTDIR)/%.html: $(DOCOUTDIR)/%.sgml +$(DOCOUTDIR)/%.html: $(DOCOUTDIR)/%.xml @(which db2html > /dev/null 2>&1) || \ (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) @@ -53,11 +53,15 @@ $(DOCOUTDIR)/fig/%: fig/% $(DOCOUTDIR)/fig/%.pdf: $(DOCOUTDIR)/fig/%.fig fig2dev -L pdf $< $@ +$(DOCOUTDIR)/fig/%.gif: $(DOCOUTDIR)/fig/%.fig + fig2dev -L gif $< $@ + all: default -default: $(DOCOUTDIR)/depend fig-prepare sgmldocs htmldocs pdfdocs +default: $(DOCOUTDIR)/depend fig-prepare xmldocs htmldocs pdfdocs -fig-prepare: $(FIGFILES:fig/%=$(DOCOUTDIR)/fig/%) $(patsubst %.fig,$(DOCOUTDIR)/%.pdf,$(filter %.fig,$(FIGFILES))) +fig-prepare: $(FIGFILES:fig/%=$(DOCOUTDIR)/fig/%) $(patsubst %.fig,$(DOCOUTDIR)/%.pdf,$(filter %.fig,$(FIGFILES))) \ + $(patsubst %.fig,$(DOCOUTDIR)/%.gif,$(filter %.fig,$(FIGFILES))) # [ -d fig ] || exit 0 ; \ # mkdir -p $(DOCOUTDIR)/fig @@ -70,7 +74,7 @@ fig-prepare: $(FIGFILES:fig/%=$(DOCOUTDIR)/fig/%) $(patsubst %.fig,$(DOCOUTDIR)/ # echo Done # exit 1 -sgmldocs: $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.sgml) +xmldocs: $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.xml) htmldocs: $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.html) @@ -79,15 +83,16 @@ pdfdocs: $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.pdf) clean: rm -f $(DOCOUTDIR)/depend \ $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.pdf) $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.out) \ - $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.sgml) $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.html) \ - $(FIGFILES:fig/%=$(DOCOUTDIR)/fig/%) $(patsubst %.fig,$(DOCOUTDIR)/%.pdf,$(filter %.fig,$(FIGFILES))) + $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.xml) $(TMPLFILES:%.tmpl=$(DOCOUTDIR)/%.html) \ + $(FIGFILES:fig/%=$(DOCOUTDIR)/fig/%) $(patsubst %.fig,$(DOCOUTDIR)/%.pdf,$(filter %.fig,$(FIGFILES))) \ + $(patsubst %.fig,$(DOCOUTDIR)/%.gif,$(filter %.fig,$(FIGFILES))) rm -rf *.junk $(DOCOUTDIR)/depend: $(TMPLFILES) mkdir -p $(DOCOUTDIR) rm -f $(DOCOUTDIR)/depend $(foreach f,$(TMPLFILES), \ - echo '$(f:%.tmpl=$(DOCOUTDIR)/%.sgml) : \' >>$(DOCOUTDIR)/depend ; \ + echo '$(f:%.tmpl=$(DOCOUTDIR)/%.xml) : \' >>$(DOCOUTDIR)/depend ; \ ( cat $(f) | sed -n -e 's/^![FIE]\(.*\)$$/\t\1 \\/p' >>$(DOCOUTDIR)/depend ) ; \ echo >>$(DOCOUTDIR)/depend ; \ ) diff --git a/doc/srcdoc/gavl.tmpl b/doc/srcdoc/gavl.tmpl index 17eceb8..8774fff 100644 --- a/doc/srcdoc/gavl.tmpl +++ b/doc/srcdoc/gavl.tmpl @@ -1,4 +1,16 @@ - + + + + + + +%mathml; +]> @@ -644,7 +656,7 @@ typedef struct cust2_item { } cust2_item_t; typedef struct cust2_root { - gavl_node_t *my_root; + gavl_cust_root_field_t my_root; /* more user root/tree data ... */ } cust2_root_t; @@ -653,7 +665,7 @@ int cust_cmp_fnc(cust_key_t *a, cust_key_t *b); As can be seen from above code fragment, the key field with user declared type (cust_key_t) and internal node structure are required - for items. The only one field with type gavl_node_t* is required + for items. The only one field with type gavl_cust_root_field_t is required for the custom tree root structure. @@ -757,7 +769,7 @@ cust2_root_t cust2_tree; - + . The height of subtree starting at @@ -766,7 +778,7 @@ cust2_root_t cust2_tree; - + is labeled as @@ -775,7 +787,7 @@ cust2_root_t cust2_tree; - + . Height difference (balance factor) for node @@ -784,7 +796,7 @@ cust2_root_t cust2_tree; - + is labeled as @@ -793,7 +805,7 @@ cust2_root_t cust2_tree; - + . @@ -805,19 +817,19 @@ cust2_root_t cust2_tree; Tree balancing case 1 - + - + Before operation - + - + After operation @@ -833,7 +845,7 @@ cust2_root_t cust2_tree; - + The height of subtree @@ -842,7 +854,7 @@ cust2_root_t cust2_tree; - + is defined by highest branch, which is branch grovinggrowing from node @@ -851,7 +863,7 @@ cust2_root_t cust2_tree; - + . This leads to next equations. @@ -866,7 +878,7 @@ b & = & a+1-\Delta s - + The height of branches @@ -875,7 +887,7 @@ b & = & a+1-\Delta s - + and @@ -884,7 +896,7 @@ b & = & a+1-\Delta s - + is marked as @@ -893,7 +905,7 @@ b & = & a+1-\Delta s - + and @@ -902,7 +914,7 @@ b & = & a+1-\Delta s - + after balancing. @@ -915,7 +927,7 @@ b & = & a+1-\Delta s - + @@ -930,7 +942,7 @@ s1 & = & a+1-\min (\Delta n,\Delta s-1) - + @@ -949,7 +961,7 @@ s1 & = & a+1-\min (\Delta n,\Delta s-1) - + Because balancing in case 1 does not guarantee that new tree has lower height than original tree, it is necessary to compute tree height change (tree height lowering). @@ -969,7 +981,7 @@ s-n1 & = & \left\langle \begin{array}{cc} - + @@ -979,19 +991,19 @@ s-n1 & = & \left\langle \begin{array}{cc} Tree balancing case 2 - + - + Before operation - + - + After operation @@ -1003,7 +1015,7 @@ s-n1 & = & \left\langle \begin{array}{cc} - + @@ -1012,7 +1024,7 @@ s-n1 & = & \left\langle \begin{array}{cc} - + or @@ -1021,7 +1033,7 @@ s-n1 & = & \left\langle \begin{array}{cc} - + @@ -1030,7 +1042,7 @@ s-n1 & = & \left\langle \begin{array}{cc} - + . @@ -1043,7 +1055,7 @@ s-n1 & = & \left\langle \begin{array}{cc} - + @@ -1058,7 +1070,7 @@ a & = & p+\Delta n - + @@ -1071,7 +1083,7 @@ a & = & p+\Delta n - + When @@ -1080,7 +1092,7 @@ a & = & p+\Delta n - + then the height differences @@ -1089,7 +1101,7 @@ a & = & p+\Delta n - + , @@ -1098,7 +1110,7 @@ a & = & p+\Delta n - + and @@ -1107,7 +1119,7 @@ a & = & p+\Delta n - + for nodes @@ -1116,7 +1128,7 @@ a & = & p+\Delta n - + , @@ -1125,7 +1137,7 @@ a & = & p+\Delta n - + and @@ -1134,7 +1146,7 @@ a & = & p+\Delta n - + of the balanced tree can be computed from next equations. @@ -1155,7 +1167,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + When @@ -1164,7 +1176,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + then the height differences @@ -1173,7 +1185,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + , @@ -1182,7 +1194,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + and @@ -1191,7 +1203,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + for nodes @@ -1200,7 +1212,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + , @@ -1209,7 +1221,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + and @@ -1218,7 +1230,7 @@ s1 & = & \max (c,d)+1=\max (b-\Delta p,b+2-\Delta s)+1\\ - + of the balanced tree can be computed from next equations. @@ -1239,7 +1251,7 @@ n1 & = & \max (a,b)+1=\max (c+1+\Delta n,c+\Delta p)+1\\ - + @@ -1250,7 +1262,7 @@ n1 & = & \max (a,b)+1=\max (c+1+\Delta n,c+\Delta p)+1\\ - + can be computed recursively. @@ -1261,7 +1273,7 @@ T(h)=T(h-1)+T(h-2)+1,\, T(0)=0,\, T(1)=1\] - + 1, 2, 4, 7, 12, 20, 33, 54, 88, 143, 232, 376, 609, 986 @@ -1272,7 +1284,7 @@ T(h)=\frac{1}{\sqrt{5}}\left(\frac{1+\sqrt{5}}{2}\right)^{(h+2)}-1\] - + @@ -1283,7 +1295,7 @@ T(h)=\frac{1}{\sqrt{5}}\, 2^{(h+2)\, log_{2}\left(\frac{1+\sqrt{5}}{2}\right)}-1 - + @@ -1294,7 +1306,7 @@ h=\left(log_{2}(T+1)-log_{2}\left(\frac{1}{\sqrt{5}}\right)\right)log_{2}^{-1}\l - + @@ -1305,7 +1317,7 @@ log_{2}^{-1}\left(\frac{1+\sqrt{5}}{2}\right)=1.44042\] - + An AVL tree with n nodes has height between log2 (n + 1) and 1.44 * log2 (n + 2) - 0.328. An AVL tree with height h has between pow (2, (h + .328) / 1.44) - 1 and pow (2, h) - 1 nodes.A red-black tree with n nodes has height at least log2 (n + 1) but no more than 2 * log2 (n + 1). A red-black tree with height h has at least pow (2, h / 2) - 1 nodes but no more than pow (2, h) - 1. diff --git a/doc/srcdoc/ulut.tmpl b/doc/srcdoc/ulut.tmpl index 2407719..247dd25 100644 --- a/doc/srcdoc/ulut.tmpl +++ b/doc/srcdoc/ulut.tmpl @@ -1,4 +1,7 @@ - + + diff --git a/scripts/kernel-doc b/scripts/kernel-doc new file mode 100755 index 0000000..ab919c7 --- /dev/null +++ b/scripts/kernel-doc @@ -0,0 +1,1874 @@ +#!/usr/bin/perl -w + +use strict; + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## Copyright (C) 2000, 1 Tim Waugh ## +## Copyright (C) 2001 Simon Huggins ## +## ## +## #define enhancements by Armin Kuster ## +## 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 + +# 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 + +# 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 + + +# +# 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: +# kerneldoc [ -docbook | -html | -text | -man ] +# [ -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. +# +# -function funcname +# If set, then only generate documentation for the given function(s). All +# other functions are ignored. +# +# -nofunction funcname +# If set, then only generate documentation for the other function(s). All +# other functions are ignored. Cannot be used with -function together +# (yes thats 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 ommitted, 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; +# }; +# +# 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; + +# 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_env = '(\$\w+)'; + +# Output conversion substitutions. +# One for each output format + +# these work fairly well +my %highlights_html = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +my $blankline_html = "

"; + +# sgml, docbook format +my %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", + $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_sgml = "\n"; + +# gnome, docbook format +my %highlights_gnome = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_gnome = "\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 ]\n"; + print " [ -sgmlreferencetitle title ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; + print " [ -no-dummy-per-file ]\n"; + print " c source file(s) > outputfile\n"; + exit 1; +} + +# read arguments +if ($#ARGV==-1) { + usage(); +} + +my $verbose = 0; +my $add_dummy_entry_per_file = 1; +my $sgml_reference_title = ""; +my $output_mode = "man"; +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); + +# 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; + +#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 ]+):(.*)'; +my $doc_content = $doc_com.'(.*)'; +my $doc_block = $doc_com.'DOC:\s*(.*)?'; + +my %constants; +my %parameterdescs; +my @parameterlist; +my %sections; +my @sectionlist; + +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 = "sgml"; + %highlights = %highlights_sgml; + $blankline = $blankline_sgml; + } elsif ($cmd eq "-gnome") { + $output_mode = "gnome"; + %highlights = %highlights_gnome; + $blankline = $blankline_gnome; + } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document + $modulename = shift @ARGV; + } elsif ($cmd eq "-sgmlreferencetitle") { # valid XML document + $sgml_reference_title = shift @ARGV; + } elsif ($cmd eq "-no-dummy-per-file") { + $add_dummy_entry_per_file = 0; + } 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; + } +} + + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +my $dohighlight = ""; +foreach my $pattern (keys %highlights) { +# print "scanning pattern $pattern ($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 $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; + } else { +# print STDERR "other section '$name' = '$contents'\n"; + $sections{$name} = $contents; + push @sectionlist, $name; + } +} + +## +# output function +# +# parameterdescs, a hash. +# function => "function name" +# parameterlist => @list of parameters +# parameterdescs => %parameter descriptions +# sectionlist => @list of sections +# sections => %descriont 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"; +# } + + eval $dohighlight; + die $@ if $@; + foreach $line (split "\n", $contents) { + if ($line eq ""){ + print $lineprefix, $blankline; + } else { + $line =~ s/\\\\\\/\&/g; + print $lineprefix, $line; + } + print "\n"; + } +} + +#output sections in html +sub output_section_html(%) { + my %args = %{$_[0]}; + my $section; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
\n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } +} + +# output enum in html +sub output_enum_html(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "

enum ".$args{'enum'}."

\n"; + + print "enum ".$args{'enum'}." {
\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print " ".$parameter.""; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + print "
"; + } + print "};
\n"; + + print "

Constants

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output tyepdef in html +sub output_typedef_html(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "

typedef ".$args{'typedef'}."

\n"; + + print "typedef ".$args{'typedef'}."\n"; + output_section_html(@_); + print "
\n"; +} + +# output struct in html +sub output_struct_html(%) { + my %args = %{$_[0]}; + my ($parameter); + + print "

".$args{'type'}." ".$args{'struct'}."

\n"; + print "".$args{'type'}." ".$args{'struct'}." {
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print "$parameter
\n"; + next; + } + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter) ($2);
\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print " $1 $parameter$2;
\n"; + } else { + print " $type $parameter;
\n"; + } + } + print "};
\n"; + + print "

Members

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output function in html +sub output_function_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + print "

Function

\n"; + + print "".$args{'functiontype'}."\n"; + print "".$args{'function'}."\n"; + print "("; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "$1$parameter) ($2)"; + } else { + print "".$type." ".$parameter.""; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + } + print ")\n"; + + print "

Arguments

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output intro in html +sub output_intro_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
    \n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + +sub output_section_sgml(%) { + my %args = %{$_[0]}; + my $section; + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } +} + +# output function in sgml DocBook +sub output_function_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + if ($verbose) { + print STDERR "generating doc for function ".$args{'function'}."\n"; + } + print "\n"; + print "\n"; + print "".$args{'function'}."\n"; + print "\n"; + print "\n"; + print " ".$args{'function'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." \n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + print "\n"; + + # print parameters + print "\n Arguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + output_section_sgml(@_); + print "\n\n"; +} + +# output struct in sgml DocBook +sub output_struct_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $id; + + $id = "API-struct-".$args{'struct'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + if ($verbose) { + print STDERR "generating doc for struct ".$args{'struct'}."\n"; + } + print "\n"; + print "\n"; + print "".$args{'type'}." ".$args{'struct'}."\n"; + print "\n"; + print "\n"; + print " ".$args{'type'}." ".$args{'struct'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print "$parameter\n"; + next; + } + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + defined($args{'parameterdescs'}{$parameter_name}) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter) ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print " $1 $parameter$2;\n"; + } else { + print " ".$type." ".$parameter.";\n"; + } + } + print "};"; + print " \n"; + print "\n"; + + print " \n"; + print " Members\n"; + + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + defined($args{'parameterdescs'}{$parameter_name}) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print " "; + print " $parameter\n"; + print " \n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n"; + print " \n"; + } + print " \n"; + print " \n"; + + output_section_sgml(@_); + + print "\n\n"; +} + +# output enum in sgml DocBook +sub output_enum_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-enum-".$args{'enum'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + if ($verbose) { + print STDERR "generating doc for enum ".$args{'enum'}."\n"; + } + print "\n"; + print "\n"; + print "enum ".$args{'enum'}."\n"; + print "\n"; + print "\n"; + print " enum ".$args{'enum'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print " $parameter"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ","; + } + print "\n"; + } + print "};"; + print " \n"; + print "\n"; + + print "\n"; + print " Constants\n"; + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " "; + print " $parameter\n"; + print " \n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n"; + print " \n"; + } + print " \n"; + print "\n"; + + output_section_sgml(@_); + + print "\n\n"; +} + +# output typedef in sgml DocBook +sub output_typedef_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $id; + + $id = "API-typedef-".$args{'typedef'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + if ($verbose) { + print STDERR "generating doc for typedef ".$args{'typedef'}."\n"; + } + print "\n"; + print "\n"; + print "typedef ".$args{'typedef'}."\n"; + print "\n"; + print "\n"; + print " typedef ".$args{'typedef'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " typedef ".$args{'typedef'}.";\n"; + print "\n"; + + output_section_sgml(@_); + + print "\n\n"; +} + +# output in sgml DocBook +sub output_intro_sgml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + my $id = $args{'module'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } + + print "\n\n"; +} + +# output in sgml DocBook +sub output_function_gnome { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}."-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print " ".$args{'function'}."\n"; + + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + print "\n"; + print "\n"; + print "\n"; + print "\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " $parameter\n"; + print " \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print "\n"; + output_highlight($args{'sections'}{$section}); + print "\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print " \n"; + } + + print "\n\n"; +} + +## +# output function in man +sub output_function_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'function'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + $count = 0; + my $parenth = "("; + my $post = ","; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count == $#{$args{'parameterlist'}}) { + $post = ");"; + } + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n"; + } + $count++; + $parenth = ""; + } + + print ".SH ARGUMENTS\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"", uc $section, "\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output enum in man +sub output_enum_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + print ".br\n.BI \" $parameter\"\n"; + if ($count == $#{$args{'parameterlist'}}) { + print "\n};\n"; + last; + } + else { + print ", \n.br\n"; + } + $count++; + } + + print ".SH Constants\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output struct in man +sub output_struct_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print $args{'type'}." ".$args{'struct'}." {\n.br\n"; + + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print ".BI \"$parameter\"\n.br\n"; + next; + } + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print ".BI \" ".$1."\" ".$parameter.$2." \""."\"\n;\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n"; + } + print "\n.br\n"; + } + print "};\n.br\n"; + + print ".SH Arguments\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output typedef in man +sub output_typedef_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +sub output_intro_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output in text +sub output_function_text(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print "Function:\n\n"; + my $start=$args{'functiontype'}." ".$args{'function'}." ("; + print $start; + my $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1.$parameter.") (".$2; + } else { + print $type." ".$parameter; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + print " " x length($start); + } else { + print ");\n\n"; + } + } + + print "Arguments:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n"; + } + output_section_text(@_); +} + +#output sections in text +sub output_section_text(%) { + my %args = %{$_[0]}; + my $section; + + print "\n"; + foreach $section (@{$args{'sectionlist'}}) { + print "$section:\n\n"; + output_highlight($args{'sections'}{$section}); + } + print "\n\n"; +} + +# output enum in text +sub output_enum_text(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "Enum:\n\n"; + + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print "\t$parameter"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ","; + } + print "\n"; + } + print "};\n\n"; + + print "Constants:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "$parameter\n\t"; + print $args{'parameterdescs'}{$parameter}."\n"; + } + + output_section_text(@_); +} + +# output typedef in text +sub output_typedef_text(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "Typedef:\n\n"; + + print "typedef ".$args{'typedef'}."\n"; + output_section_text(@_); +} + +# output struct as text +sub output_struct_text(%) { + my %args = %{$_[0]}; + my ($parameter); + + print $args{'type'}." ".$args{'struct'}.":\n\n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print "$parameter\n"; + next; + } + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "\t$1 $parameter) ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + print "\t$1 $parameter$2;\n"; + } else { + print "\t".$type." ".$parameter.";\n"; + } + } + print "};\n\n"; + + print "Members:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print "$parameter\n\t"; + print $args{'parameterdescs'}{$parameter_name}."\n"; + } + print "\n"; + output_section_text(@_); +} + +sub output_intro_text(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + print " $section:\n"; + print " -> "; + output_highlight($args{'sections'}{$section}); + } +} + +## +# generic output function for typedefs +sub output_declaration { + no strict 'refs'; + my $name = shift; + my $functype = shift; + my $func = "output_${functype}_$output_mode"; + #if ($verbose) { + # print STDERR "Info(): function_only: $function_only output_declaration for $name\n"; + # if(defined($function_table{$name})) { + # print STDERR "Info(): function $name defined in function_table\n"; + # } + #} + if (($function_only==0) || + ( $function_only == 1 && defined($function_table{$name})) || + ( $function_only == 2 && !defined($function_table{$name}))) + { + &$func(@_); + #if ($verbose) { + # print STDERR "Info(): incrementing section_counter: $section_counter\n"; + #} + $section_counter++; + } +} + +## +# generic output function - calls the right one based +# on current output mode. +sub output_intro { + no strict 'refs'; + my $func = "output_intro_".$output_mode; + &$func(@_); + $section_counter++; +} + +## +# takes a declaration (struct, union, enum, typedef) and +# invokes the right handler. NOT called for functions. +sub dump_declaration($$) { + no strict 'refs'; + my ($prototype, $file) = @_; + my $func = "dump_".$decl_type; + &$func(@_); +} + +sub dump_union($$) { + dump_struct(@_); +} + +sub dump_struct($$) { + my $x = shift; + my $file = shift; + + if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) { + $declaration_name = $2; + my $members = $3; + + # ignore embedded structs or unions + $members =~ s/{.*?}//g; + + create_parameterlist($members, ';', $file); + + output_declaration($declaration_name, + 'struct', + {'struct' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose, + 'type' => $decl_type + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse struct or union!\n"; + ++$errors; + } +} + +sub dump_enum($$) { + my $x = shift; + my $file = shift; + + if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { + $declaration_name = $1; + my $members = $2; + + foreach my $arg (split ',', $members) { + $arg =~ s/^\s*(\w+).*/$1/; + push @parameterlist, $arg; + if (!$parameterdescs{$arg}) { + $parameterdescs{$arg} = $undescribed; + print STDERR "Warning(${file}:$.): Enum value '$arg' ". + "not described in enum '$declaration_name'\n"; + } + + } + + output_declaration($declaration_name, + 'enum', + {'enum' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse enum!\n"; + ++$errors; + } +} + +sub dump_typedef($$) { + my $x = shift; + my $file = shift; + + while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { + $x =~ s/\(*.\)\s*;$/;/; + $x =~ s/\[*.\]\s*;$/;/; + } + + if ($x =~ /typedef.*\s+(\w+)\s*;/) { + $declaration_name = $1; + + output_declaration($declaration_name, + 'typedef', + {'typedef' => $declaration_name, + 'module' => $modulename, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; + ++$errors; + } +} + +sub create_parameterlist($$$) { + my $args = shift; + my $splitter = shift; + my $file = shift; + my $type; + my $param; + + while ($args =~ /(\([^\),]+),/) { + $args =~ s/(\([^\),]+),/$1#/g; + } + + foreach my $arg (split($splitter, $args)) { + # strip comments + $arg =~ s/\/\*.*\*\///; + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; + $arg =~ s/\s+/ /; + + if ($arg =~ /^#/) { + # Treat preprocessor directive as a typeless variable just to fill + # corresponding data structures "correctly". Catch it later in + # output_* subs. + push_parameter($arg, "", $file); + } elsif ($arg =~ m/\(/) { + # pointer-to-function + $arg =~ tr/#/,/; + $arg =~ m/[^\(]+\(\*([^\)]+)\)/; + $param = $1; + $type = $arg; + $type =~ s/([^\(]+\(\*)$param/$1/; + push_parameter($param, $type, $file); + } else { + $arg =~ s/\s*:\s*/:/g; + $arg =~ s/\s*\[/\[/g; + + my @args = split('\s*,\s*', $arg); + if ($args[0] =~ m/\*/) { + $args[0] =~ s/(\*+)\s*/ $1/; + } + my @first_arg = split('\s+', shift @args); + unshift(@args, pop @first_arg); + $type = join " ", @first_arg; + + foreach $param (@args) { + if ($param =~ m/^(\*+)\s*(.*)/) { + push_parameter($2, "$type $1", $file); + } + elsif ($param =~ m/(.*?):(\d+)/) { + push_parameter($1, "$type:$2", $file) + } + else { + push_parameter($param, $type, $file); + } + } + } + } +} + +sub push_parameter($$$) { + my $param = shift; + my $type = shift; + my $file = shift; + + my $param_name = $param; + $param_name =~ s/\[.*//; + + if ($type eq "" && $param eq "...") + { + $type=""; + $param="..."; + $parameterdescs{"..."} = "variable arguments"; + } + elsif ($type eq "" && ($param eq "" or $param eq "void")) + { + $type=""; + $param="void"; + $parameterdescs{void} = "no arguments"; + } + if (defined $type && $type && !defined $parameterdescs{$param_name}) { + $parameterdescs{$param_name} = $undescribed; + + if (($type eq 'function') || ($type eq 'enum')) { + print STDERR "Warning(${file}:$.): Function parameter ". + "or member '$param' not " . + "described in '$declaration_name'\n"; + } + print STDERR "Warning(${file}:$.):". + " No description found for parameter '$param'\n"; + ++$warnings; + } + + push @parameterlist, $param; + $parametertypes{$param} = $type; +} + +## +# takes a function prototype and the name of the current file being +# processed and spits out all the details stored in the global +# arrays/hashes. +sub dump_function($$) { + my $prototype = shift; + my $file = shift; + + $prototype =~ s/^static +//; + $prototype =~ s/^extern +//; + $prototype =~ s/^fastcall +//; + $prototype =~ s/^asmlinkage +//; + $prototype =~ s/^inline +//; + $prototype =~ s/^__inline__ +//; + $prototype =~ s/^#define +//; #ak added + $prototype =~ s/__attribute__ \(\([a-z,]*\)\)//; + + # Yes, this truly is vile. We are looking for: + # 1. Return type (may be nothing if we're looking at a macro) + # 2. Function name + # 3. Function parameters. + # + # All the while we have to watch out for function pointer parameters + # (which IIRC is what the two sections are for), C types (these + # regexps don't even start to express all the possibilities), and + # so on. + # + # If you mess with these regexps, it's a good idea to check that + # the following functions' documentation still comes out right: + # - parport_register_device (function pointer parameters) + # - atomic_set (macro) + # - pci_match_device (long return type) + + if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $return_type = $1; + $declaration_name = $2; + my $args = $3; + + create_parameterlist($args, ',', $file); + } else { + print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; + ++$errors; + return; + } + + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); +} + +sub process_file($); + +# Read the file that maps relative names to absolute names for +# separate source and object directories and for shadow trees. +if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { + my ($relname, $absname); + while() { + chop(); + ($relname, $absname) = (split())[0..1]; + $relname =~ s:^/+::; + $source_map{$relname} = $absname; + } + close(SOURCE_MAP); +} + +if (! ($sgml_reference_title eq "")) { + print "\n"; + print "
$sgml_reference_title\n"; +} + +if ($filelist) { + open(FLIST,"<$filelist") or die "Can't open file list $filelist"; + while() { + chop; + process_file($_); + } +} + +foreach (@ARGV) { + chomp; + process_file($_); +} + +if (! ($sgml_reference_title eq "")) { + print "
\n"; +} +if ($verbose && $errors) { + print STDERR "$errors errors\n"; +} +if ($verbose && $warnings) { + print STDERR "$warnings warnings\n"; +} + +exit($errors); + +sub reset_state { + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + + $state = 0; +} + +sub process_state3_function($$) { + my $x = shift; + my $file = shift; + + if ($x =~ m#\s*/\*\s+MACDOC\s*#io) { + # do nothing + } + elsif ($x =~ /([^\{]*)/) { + $prototype .= $1; + } + if (($x =~ /\{/) || ($x =~ /\#/) || ($x =~ /;/)) { + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^\s+@@gos; # strip leading spaces + dump_function($prototype,$file); + reset_state(); + } +} + +sub process_state3_type($$) { + my $x = shift; + my $file = shift; + + $x =~ s@/\*.*?\*/@@gos; # strip comments. + $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $x =~ s@^\s+@@gos; # strip leading spaces + $x =~ s@\s+$@@gos; # strip trailing spaces + if ($x =~ /^#/) { + # To distinguish preprocessor directive from regular declaration later. + $x .= ";"; + } + + while (1) { + if ( $x =~ /([^{};]*)([{};])(.*)/ ) { + $prototype .= $1 . $2; + ($2 eq '{') && $brcount++; + ($2 eq '}') && $brcount--; + if (($2 eq ';') && ($brcount == 0)) { + dump_declaration($prototype,$file); + reset_state(); + last; + } + $x = $3; + } else { + $prototype .= $x; + last; + } + } +} + +sub process_file($) { + #my ($file) = "$ENV{'SRCTREE'}@_"; + my ($file) = @_; + my $identifier; + my $func; + my $initial_section_counter = $section_counter; + + if (defined($source_map{$file})) { + $file = $source_map{$file}; + } + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + print STDERR "Parsing file $file\n"; + #$section_counter = 0; + while () { + if ($state == 0) { + if (/$doc_start/o) { + $state = 1; # next line is always the function name + #print STDERR "found doc start\n"; + } + } elsif ($state == 1) { # this line is the function name (always) + if (/$doc_block/o) { + $state = 4; + $contents = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_decl/o) { + $identifier = $1; + if (/\s*([\w\s]+?)\s*-/) { + $identifier = $1; + } + + $state = 2; + if (/-(.*)/) { + $declaration_purpose = $1; + } else { + $declaration_purpose = ""; + } + if ($identifier =~ m/^struct/) { + $decl_type = 'struct'; + } elsif ($identifier =~ m/^union/) { + $decl_type = 'union'; + } elsif ($identifier =~ m/^enum/) { + $decl_type = 'enum'; + } elsif ($identifier =~ m/^typedef/) { + $decl_type = 'typedef'; + } else { + $decl_type = 'function'; + } + + if ($verbose) { + print STDERR "Info(${file}:$.): Scanning doc for $identifier\n"; + } + } else { + print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.", + " - I thought it was a doc line\n"; + ++$warnings; + $state = 0; + } + } elsif ($state == 2) { # look for head: lines, and include content + if (/$doc_sect/o) { + $newsection = $1; + $newcontents = $2; + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + } + + $contents = $newcontents; + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + } elsif (/$doc_end/) { + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } + + $prototype = ""; + $state = 3; + $brcount = 0; +# print STDERR "end of doc comment, looking for prototype\n"; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "" && + ($section =~ m/^@/ || $section eq $section_context)) { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } else { + $contents .= $1."\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "Warning(${file}:$.): bad line: $_"; + ++$warnings; + } + } elsif ($state == 3) { # scanning for function { (end of prototype) + if ($decl_type eq 'function') { + process_state3_function($_, $file); + } else { + process_state3_type($_, $file); + } + } elsif ($state == 4) { + # Documentation block + if (/$doc_block/) { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_end/) + { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = 0; + } + elsif (/$doc_content/) + { + if ( $1 eq "" ) + { + $contents .= $blankline; + } + else + { + $contents .= $1 . "\n"; + } + } + } + } + if ($initial_section_counter == $section_counter) { + print STDERR "Warning(${file}): no structured comments found\n"; + if ($output_mode eq "sgml" && $add_dummy_entry_per_file > 0) { + # The template wants at least one RefEntry here; make one. + print "\n"; + print " \n"; + print " \n"; + print " ${file}\n"; + print " \n"; + print " \n"; + print " Document generation inconsistency\n"; + print " \n"; + print " \n"; + print " \n"; + print " \n"; + print " Oops\n"; + print " \n"; + print " \n"; + print " \n"; + print " The template for this document tried to insert\n"; + print " the structured comment from the file\n"; + print " ${file} at this point,\n"; + print " but none was found.\n"; + print " This dummy section is inserted to allow\n"; + print " generation to continue.\n"; + print " \n"; + print " \n"; + print " \n"; + print "\n"; + } + } +} diff --git a/scripts/tmpl2sgml b/scripts/tmpl2sgml new file mode 100755 index 0000000..9c0424f --- /dev/null +++ b/scripts/tmpl2sgml @@ -0,0 +1,23 @@ +#!/usr/bin/perl +#warn "No digit found.\n"; + +use Env qw(PATH TMPL2SGML KERNELDOC); + +warn "Processing $ARGV[0]\n" ; +#warn "PATH=$PATH\n" ; +warn "KERNELDOC=$KERNELDOC\n" ; + +open (TMPLFILE, "$ARGV[0]"); + +while () { + $line=$_; + if($line=~m/^![EIF]/){ + ($srctype,$srcfile)= $line =~ /^!([EIF])(.*)$/ ; + warn "Found $srctype : $srcfile\n" ; + system "$KERNELDOC -docbook $srcfile"; + }else{ + print $line + } +} + +close TMPLFILE;