Commit 1b40c194 authored by Dan Luedtke's avatar Dan Luedtke Committed by Michal Marek
Browse files

scripts/kernel-doc: added support for html5 



New output option html5 writes validating HTML5 and adds
CSS classes ready to be selected by third-party stylesheets.
HTML ids have been added to block-level elements "article" for
direct reference of particular objects via URL.

Signed-off-by: default avatarDan Luedtke <mail@danrl.de>
Acked-by: default avatarRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: default avatarMichal Marek <mmarek@suse.cz>
parent 0d7614f0

scripts/kernel-doc

+266 −7
Original line number Diff line number Diff line
@@ -6,6 +6,7 @@ use strict; 
## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##

## Copyright (C) 2001  Simon Huggins                             ##

## Copyright (C) 2005-2012  Randy Dunlap                         ##

## Copyright (C) 2012  Dan Luedtke                               ##

## 								 ##

## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##

## Copyright (c) 2000 MontaVista Software, Inc.			 ##
@@ -35,6 +36,8 @@ use strict; 
#              Small fixes (like spaces vs. \s in regex)

# -- Tim Jansen <tim@tjansen.de>



# 25/07/2012 - Added support for HTML5

# -- Dan Luedtke <mail@danrl.de>



#

# This will read a 'c' file and scan for embedded comments in the
@@ -44,12 +47,16 @@ use strict; 
# Note: This only supports 'c'.



# usage:

# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ]

#           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile

# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]

#            [ -no-doc-sections ]

#            [ -function funcname [ -function funcname ...] ]

#            c file(s)s > outputfile

# or

#           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile

#            [ -nofunction funcname [ -function funcname ...] ]

#            c file(s)s > outputfile

#

#  Set output format using one of -docbook -html -text or -man.  Default is man.

#  Set output format using one of -docbook -html -html5 -text or -man.

#  Default is man.

#  The -list format is for internal use by docproc.

#

#  -no-doc-sections
@@ -182,6 +189,14 @@ my $local_lt = "\\\\\\\\lt:"; 
my $local_gt = "\\\\\\\\gt:";

my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"



# html version 5

my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",

			$type_func, "<span class=\"func\">\$1</span>",

			$type_struct_xml, "<span class=\"struct\">\$1</span>",

			$type_env, "<span class=\"env\">\$1</span>",

			$type_param, "<span class=\"param\">\$1</span>" );

my $blankline_html5 = $local_lt . "br /" . $local_gt;



# XML, docbook format

my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",

			$type_constant, "<constant>\$1</constant>",
@@ -309,6 +324,10 @@ while ($ARGV[0] =~ m/^-(.*)/) { 
	$output_mode = "html";

	%highlights = %highlights_html;

	$blankline = $blankline_html;

    } elsif ($cmd eq "-html5") {

	$output_mode = "html5";

	%highlights = %highlights_html5;

	$blankline = $blankline_html5;

    } elsif ($cmd eq "-man") {

	$output_mode = "man";

	%highlights = %highlights_man;
@@ -351,10 +370,11 @@ while ($ARGV[0] =~ m/^-(.*)/) { 
# continue execution near EOF;



sub usage {

    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n";

    print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";

    print "         [ -no-doc-sections ]\n";

    print "         [ -function funcname [ -function funcname ...] ]\n";

    print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";

    print "         [ -v ]\n";

    print "         c source file(s) > outputfile\n";

    print "         -v : verbose output, more warnings & other info listed\n";

    exit 1;
@@ -448,7 +468,8 @@ sub output_highlight { 
#	confess "output_highlight got called with no args?\n";

#   }



    if ($output_mode eq "html" || $output_mode eq "xml") {

    if ($output_mode eq "html" || $output_mode eq "html5" ||

	$output_mode eq "xml") {

	$contents = local_unescape($contents);

	# convert data read & converted thru xml_escape() into &xyz; format:

	$contents =~ s/\\\\\\/\&/g;
@@ -458,6 +479,11 @@ sub output_highlight { 
    die $@ if $@;

#   print STDERR "contents af:$contents\n";



#   strip whitespaces when generating html5

    if ($output_mode eq "html5") {

	$contents =~ s/^\s+//;

	$contents =~ s/\s+$//;

    }

    foreach $line (split "\n", $contents) {

	if ($line eq ""){

	    print $lineprefix, local_unescape($blankline);
@@ -633,6 +659,239 @@ sub output_blockhead_html(%) { 
    print "<hr>\n";

}



# output sections in html5

sub output_section_html5(%) {

    my %args = %{$_[0]};

    my $section;



    foreach $section (@{$args{'sectionlist'}}) {

	print "<section>\n";

	print "<h1>$section</h1>\n";

	print "<p>\n";

	output_highlight($args{'sections'}{$section});

	print "</p>\n";

	print "</section>\n";

    }

}



# output enum in html5

sub output_enum_html5(%) {

    my %args = %{$_[0]};

    my ($parameter);

    my $count;

    my $html5id;



    $html5id = $args{'enum'};

    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;

    print "<article class=\"enum\" id=\"enum:". $html5id . "\">";

    print "<h1>enum " . $args{'enum'} . "</h1>\n";

    print "<ol class=\"code\">\n";

    print "<li>";

    print "<span class=\"keyword\">enum</span> ";

    print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";

    print "</li>\n";

    $count = 0;

    foreach $parameter (@{$args{'parameterlist'}}) {

	print "<li class=\"indent\">";

	print "<span class=\"param\">" . $parameter . "</span>";

	if ($count != $#{$args{'parameterlist'}}) {

	    $count++;

	    print ",";

	}

	print "</li>\n";

    }

    print "<li>};</li>\n";

    print "</ol>\n";



    print "<section>\n";

    print "<h1>Constants</h1>\n";

    print "<dl>\n";

    foreach $parameter (@{$args{'parameterlist'}}) {

	print "<dt>" . $parameter . "</dt>\n";

	print "<dd>";

	output_highlight($args{'parameterdescs'}{$parameter});

	print "</dd>\n";

    }

    print "</dl>\n";

    print "</section>\n";

    output_section_html5(@_);

    print "</article>\n";

}



# output typedef in html5

sub output_typedef_html5(%) {

    my %args = %{$_[0]};

    my ($parameter);

    my $count;

    my $html5id;



    $html5id = $args{'typedef'};

    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;

    print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";

    print "<h1>typedef " . $args{'typedef'} . "</h1>\n";



    print "<ol class=\"code\">\n";

    print "<li>";

    print "<span class=\"keyword\">typedef</span> ";

    print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";

    print "</li>\n";

    print "</ol>\n";

    output_section_html5(@_);

    print "</article>\n";

}



# output struct in html5

sub output_struct_html5(%) {

    my %args = %{$_[0]};

    my ($parameter);

    my $html5id;



    $html5id = $args{'struct'};

    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;

    print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";

    print "<hgroup>\n";

    print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";

    print "<h2>". $args{'purpose'} . "</h2>\n";

    print "</hgroup>\n";

    print "<ol class=\"code\">\n";

    print "<li>";

    print "<span class=\"type\">" . $args{'type'} . "</span> ";

    print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";

    print "</li>\n";

    foreach $parameter (@{$args{'parameterlist'}}) {

	print "<li class=\"indent\">";

	if ($parameter =~ /^#/) {

		print "<span class=\"param\">" . $parameter ."</span>\n";

		print "</li>\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 "<span class=\"type\">$1</span> ";

	    print "<span class=\"param\">$parameter</span>";

	    print "<span class=\"type\">)</span> ";

	    print "(<span class=\"args\">$2</span>);";

	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

	    # bitfield

	    print "<span class=\"type\">$1</span> ";

	    print "<span class=\"param\">$parameter</span>";

	    print "<span class=\"bits\">$2</span>;";

	} else {

	    print "<span class=\"type\">$type</span> ";

	    print "<span class=\"param\">$parameter</span>;";

	}

	print "</li>\n";

    }

    print "<li>};</li>\n";

    print "</ol>\n";



    print "<section>\n";

    print "<h1>Members</h1>\n";

    print "<dl>\n";

    foreach $parameter (@{$args{'parameterlist'}}) {

	($parameter =~ /^#/) && next;



	my $parameter_name = $parameter;

	$parameter_name =~ s/\[.*//;



	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

	print "<dt>" . $parameter . "</dt>\n";

	print "<dd>";

	output_highlight($args{'parameterdescs'}{$parameter_name});

	print "</dd>\n";

    }

    print "</dl>\n";

    print "</section>\n";

    output_section_html5(@_);

    print "</article>\n";

}



# output function in html5

sub output_function_html5(%) {

    my %args = %{$_[0]};

    my ($parameter, $section);

    my $count;

    my $html5id;



    $html5id = $args{'function'};

    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;

    print "<article class=\"function\" id=\"func:". $html5id . "\">\n";

    print "<hgroup>\n";

    print "<h1>" . $args{'function'} . "</h1>";

    print "<h2>" . $args{'purpose'} . "</h2>\n";

    print "</hgroup>\n";

    print "<ol class=\"code\">\n";

    print "<li>";

    print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";

    print "<span class=\"identifier\">" . $args{'function'} . "</span> (";

    print "</li>";

    $count = 0;

    foreach $parameter (@{$args{'parameterlist'}}) {

	print "<li class=\"indent\">";

	$type = $args{'parametertypes'}{$parameter};

	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {

	    # pointer-to-function

	    print "<span class=\"type\">$1</span> ";

	    print "<span class=\"param\">$parameter</span>";

	    print "<span class=\"type\">)</span> ";

	    print "(<span class=\"args\">$2</span>)";

	} else {

	    print "<span class=\"type\">$type</span> ";

	    print "<span class=\"param\">$parameter</span>";

	}

	if ($count != $#{$args{'parameterlist'}}) {

	    $count++;

	    print ",";

	}

	print "</li>\n";

    }

    print "<li>)</li>\n";

    print "</ol>\n";



    print "<section>\n";

    print "<h1>Arguments</h1>\n";

    print "<p>\n";

    print "<dl>\n";

    foreach $parameter (@{$args{'parameterlist'}}) {

	my $parameter_name = $parameter;

	$parameter_name =~ s/\[.*//;



	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

	print "<dt>" . $parameter . "</dt>\n";

	print "<dd>";

	output_highlight($args{'parameterdescs'}{$parameter_name});

	print "</dd>\n";

    }

    print "</dl>\n";

    print "</section>\n";

    output_section_html5(@_);

    print "</article>\n";

}



# output DOC: block header in html5

sub output_blockhead_html5(%) {

    my %args = %{$_[0]};

    my ($parameter, $section);

    my $count;

    my $html5id;



    foreach $section (@{$args{'sectionlist'}}) {

	$html5id = $section;

	$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;

	print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";

	print "<h1>$section</h1>\n";

	print "<p>\n";

	output_highlight($args{'sections'}{$section});

	print "</p>\n";

    }

    print "</article>\n";

}



sub output_section_xml(%) {

    my %args = %{$_[0]};

    my $section;

CRA Git | Maintained and supported by SUSTech CRA and CCSE