# 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. In
-# structs and unions you must declare one member per declaration
-# (comma-separated members are not allowed - the parser does not support
-# this).
+# Use the argument mechanism to document members or constants.
# e.g.
# /**
# * struct my_struct - short description
$type_param, "<tt><b>\$1</b></tt>" );
my $blankline_html = "<p>";
-# sgml, docbook format
-my %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
+# XML, docbook format
+my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
$type_constant, "<constant>\$1</constant>",
$type_func, "<function>\$1</function>",
$type_struct, "<structname>\$1</structname>",
$type_env, "<envar>\$1</envar>",
$type_param, "<parameter>\$1</parameter>" );
-my $blankline_sgml = "</para><para>\n";
+my $blankline_xml = "</para><para>\n";
# gnome, docbook format
my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
%highlights = %highlights_text;
$blankline = $blankline_text;
} elsif ($cmd eq "-docbook") {
- $output_mode = "sgml";
- %highlights = %highlights_sgml;
- $blankline = $blankline_sgml;
+ $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 sgml, inherits from calling document
+ } 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;
print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>\n";
print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ if ($parameter =~ /^#/) {
+ print "$parameter<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 "<h3>Members</h3>\n";
print "<dl>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ ($parameter =~ /^#/) && next;
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
print "<dt><b>".$parameter."</b>\n";
print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
print "</dl>\n";
output_section_html(@_);
print "<h3>Arguments</h3>\n";
print "<dl>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
print "<dt><b>".$parameter."</b>\n";
print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
print "</dl>\n";
output_section_html(@_);
print "<hr>\n";
}
-sub output_section_sgml(%) {
+sub output_section_xml(%) {
my %args = %{$_[0]};
my $section;
# print out each section
$lineprefix=" ";
foreach $section (@{$args{'sectionlist'}}) {
- print "<refsect1>\n <title>$section</title>\n <para>\n";
+ print "<refsect1>\n";
+ print "<title>$section</title>\n";
if ($section =~ m/EXAMPLE/i) {
- print "<example><para>\n";
+ print "<informalexample><programlisting>\n";
+ } else {
+ print "<para>\n";
}
output_highlight($args{'sections'}{$section});
if ($section =~ m/EXAMPLE/i) {
- print "</para></example>\n";
+ print "</programlisting></informalexample>\n";
+ } else {
+ print "</para>\n";
}
- print " </para>\n</refsect1>\n";
+ print "</refsect1>\n";
}
}
-# output function in sgml DocBook
-sub output_function_sgml(%) {
+# output function in XML DocBook
+sub output_function_xml(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $count;
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
+ print "<refentryinfo>\n";
+ print " <title>LINUX</title>\n";
+ print " <productname>Kernel Hackers Manual</productname>\n";
+ print " <date>$man_date</date>\n";
+ print "</refentryinfo>\n";
print "<refmeta>\n";
- print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
+ print " <refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
+ print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>".$args{'function'}."</refname>\n";
}
}
} else {
- print " <void>\n";
+ print " <void/>\n";
}
print " </funcprototype></funcsynopsis>\n";
print "</refsynopsisdiv>\n";
if ($#{$args{'parameterlist'}} >= 0) {
print " <variablelist>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
print " <listitem>\n <para>\n";
$lineprefix=" ";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " </para>\n </listitem>\n </varlistentry>\n";
}
print " </variablelist>\n";
}
print "</refsect1>\n";
- output_section_sgml(@_);
+ output_section_xml(@_);
print "</refentry>\n\n";
}
-# output struct in sgml DocBook
-sub output_struct_sgml(%) {
+# output struct in XML DocBook
+sub output_struct_xml(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $id;
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
+ print "<refentryinfo>\n";
+ print " <title>LINUX</title>\n";
+ print " <productname>Kernel Hackers Manual</productname>\n";
+ print " <date>$man_date</date>\n";
+ print "</refentryinfo>\n";
print "<refmeta>\n";
- print "<refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
+ print " <refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
+ print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
print " <programlisting>\n";
print $args{'type'}." ".$args{'struct'}." {\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- defined($args{'parameterdescs'}{$parameter}) || next;
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ 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 " <variablelist>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- defined($args{'parameterdescs'}{$parameter}) || next;
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ ($parameter =~ /^#/) && next;
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ defined($args{'parameterdescs'}{$parameter_name}) || next;
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
print " <varlistentry>";
print " <term>$parameter</term>\n";
print " <listitem><para>\n";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " </para></listitem>\n";
print " </varlistentry>\n";
}
print " </variablelist>\n";
print " </refsect1>\n";
- output_section_sgml(@_);
+ output_section_xml(@_);
print "</refentry>\n\n";
}
-# output enum in sgml DocBook
-sub output_enum_sgml(%) {
+# output enum in XML DocBook
+sub output_enum_xml(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $count;
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
+ print "<refentryinfo>\n";
+ print " <title>LINUX</title>\n";
+ print " <productname>Kernel Hackers Manual</productname>\n";
+ print " <date>$man_date</date>\n";
+ print "</refentryinfo>\n";
print "<refmeta>\n";
- print "<refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
+ print " <refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
+ print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>enum ".$args{'enum'}."</refname>\n";
print " <title>Constants</title>\n";
print " <variablelist>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
print " <varlistentry>";
print " <term>$parameter</term>\n";
print " <listitem><para>\n";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " </para></listitem>\n";
print " </varlistentry>\n";
}
print " </variablelist>\n";
print "</refsect1>\n";
- output_section_sgml(@_);
+ output_section_xml(@_);
print "</refentry>\n\n";
}
-# output typedef in sgml DocBook
-sub output_typedef_sgml(%) {
+# output typedef in XML DocBook
+sub output_typedef_xml(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $id;
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
+ print "<refentryinfo>\n";
+ print " <title>LINUX</title>\n";
+ print " <productname>Kernel Hackers Manual</productname>\n";
+ print " <date>$man_date</date>\n";
+ print "</refentryinfo>\n";
print "<refmeta>\n";
- print "<refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
+ print " <refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
+ print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>typedef ".$args{'typedef'}."</refname>\n";
print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
print "</refsynopsisdiv>\n";
- output_section_sgml(@_);
+ output_section_xml(@_);
print "</refentry>\n\n";
}
-# output in sgml DocBook
-sub output_intro_sgml(%) {
+# output in XML DocBook
+sub output_intro_xml(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $count;
print "\n\n";
}
-# output in sgml DocBook
+# output in XML DocBook
sub output_function_gnome {
my %args = %{$_[0]};
my ($parameter, $section);
print "<colspec colwidth=\"8*\">\n";
print "<tbody>\n";
foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
print " <entry>\n";
$lineprefix=" ";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " </entry></row>\n";
}
print " </tbody></tgroup></informaltable>\n";
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});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
foreach $section (@{$args{'sectionlist'}}) {
print ".SH \"", uc $section, "\"\n";
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});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
foreach $section (@{$args{'sectionlist'}}) {
print ".SH \"$section\"\n";
print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
print ".SH SYNOPSIS\n";
- print $args{'type'}." ".$args{'struct'}." {\n";
+ print $args{'type'}." ".$args{'struct'}." {\n.br\n";
foreach my $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
- print "\n.br\n";
+ 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 ".SH Arguments\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ ($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});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
foreach $section (@{$args{'sectionlist'}}) {
print ".SH \"$section\"\n";
print "Arguments:\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- print $parameter."\n\t".$args{'parameterdescs'}{$parameter}."\n";
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
}
output_section_text(@_);
}
print $args{'type'}." ".$args{'struct'}.":\n\n";
print $args{'type'}." ".$args{'struct'}." {\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ 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 "Members:\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+ ($parameter =~ /^#/) && next;
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
print "$parameter\n\t";
- print $args{'parameterdescs'}{$parameter}."\n";
+ print $args{'parameterdescs'}{$parameter_name}."\n";
}
print "\n";
output_section_text(@_);
$arg =~ s/\s*$//;
$arg =~ s/\s+/ /;
- if ($arg =~ m/\(/) {
+ 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 {
- # evil magic to get fixed array parameters to work
- $arg =~ s/(.+\s+)(.+)\[.*/$1* $2/;
- my @args = split('\s', $arg);
-
- $param = pop @args;
- if ($param =~ m/^(\*+)(.*)/) {
- $param = $2;
- push @args, $1;
- }
- elsif ($param =~ m/(.*?)\s*:\s*(\d+)/) {
- $param = $1;
- push @args, ":$2";
+ $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);
+ }
}
- $type = join " ", @args;
}
+ }
+}
+
+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="...";
+ $type="";
$param="...";
$parameterdescs{"..."} = "variable arguments";
}
$param="void";
$parameterdescs{void} = "no arguments";
}
- if (defined $type && $type && !defined $parameterdescs{$param}) {
- $parameterdescs{$param} = $undescribed;
+ 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 ".
push @parameterlist, $param;
$parametertypes{$param} = $type;
- }
}
##
$prototype =~ s/^static +//;
$prototype =~ s/^extern +//;
+ $prototype =~ s/^fastcall +//;
+ $prototype =~ s/^asmlinkage +//;
$prototype =~ s/^inline +//;
$prototype =~ s/^__inline__ +//;
$prototype =~ s/^#define +//; #ak added
my $x = shift;
my $file = shift;
- if ($x =~ m#\s*/\*\s+MACDOC\s*#io) {
+ if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
# do nothing
}
elsif ($x =~ /([^\{]*)/) {
$prototype .= $1;
}
- if (($x =~ /\{/) || ($x =~ /\#/) || ($x =~ /;/)) {
+ if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
$prototype =~ s@/\*.*?\*/@@gos; # strip comments.
$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
$prototype =~ s@^\s+@@gos; # strip leading spaces
$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 =~ /([^{};]*)([{};])(.*)/ ) {
}
}
+# replace <, >, and &
+sub xml_escape($) {
+ my $text = shift;
+ $text =~ s/\&/\\\\\\amp;/g;
+ $text =~ s/\</\\\\\\lt;/g;
+ $text =~ s/\>/\\\\\\gt;/g;
+ return $text;
+}
+
sub process_file($) {
- my ($file) = @_;
+ my ($file) = "$ENV{'SRCTREE'}@_";
my $identifier;
my $func;
my $initial_section_counter = $section_counter;
$state = 2;
if (/-(.*)/) {
- $declaration_purpose = $1;
+ $declaration_purpose = xml_escape($1);
} else {
$declaration_purpose = "";
}
$newcontents = $2;
if ($contents ne "") {
- $contents =~ s/\&/\\\\\\amp;/g;
- $contents =~ s/\</\\\\\\lt;/g;
- $contents =~ s/\>/\\\\\\gt;/g;
- dump_section($section, $contents);
+ dump_section($section, xml_escape($contents));
$section = $section_default;
}
} elsif (/$doc_end/) {
if ($contents ne "") {
- $contents =~ s/\&/\\\\\\amp;/g;
- $contents =~ s/\</\\\\\\lt;/g;
- $contents =~ s/\>/\\\\\\gt;/g;
- dump_section($section, $contents);
+ dump_section($section, xml_escape($contents));
$section = $section_default;
$contents = "";
}
# @parameter line to signify start of description
if ($1 eq "" &&
($section =~ m/^@/ || $section eq $section_context)) {
- $contents =~ s/\&/\\\\\\amp;/g;
- $contents =~ s/\</\\\\\\lt;/g;
- $contents =~ s/\>/\\\\\\gt;/g;
- dump_section($section, $contents);
+ dump_section($section, xml_escape($contents));
$section = $section_default;
$contents = "";
} else {
}
if ($initial_section_counter == $section_counter) {
print STDERR "Warning(${file}): no structured comments found\n";
- if ($output_mode eq "sgml") {
+ if ($output_mode eq "xml") {
# The template wants at least one RefEntry here; make one.
print "<refentry>\n";
print " <refnamediv>\n";