From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933097Ab2GYNsi (ORCPT ); Wed, 25 Jul 2012 09:48:38 -0400 Received: from mail.nonattached.net ([193.160.39.60]:38952 "EHLO mail.nonattached.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933007Ab2GYNsh (ORCPT ); Wed, 25 Jul 2012 09:48:37 -0400 X-Greylist: delayed 454 seconds by postgrey-1.27 at vger.kernel.org; Wed, 25 Jul 2012 09:48:36 EDT From: Dan Luedtke To: rdunlap@xenotime.net Cc: mail@danrl.de, linux-kernel@vger.kernel.org Subject: [PATCH] scripts/kernel-doc: added support for html5 Date: Wed, 25 Jul 2012 15:38:08 +0200 Message-Id: <1343223488-1332-1-git-send-email-mail@danrl.de> X-Mailer: git-send-email 1.7.10 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org New output option html5 writes validating HTML5 and adds CSS classes ready to be selected by third-party stylesheets. Signed-off-by: Dan Luedtke --- scripts/kernel-doc | 255 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 249 insertions(+), 6 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9b0c0b8..f85b278 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -6,6 +6,7 @@ use strict; ## Copyright (C) 2000, 1 Tim Waugh ## ## Copyright (C) 2001 Simon Huggins ## ## Copyright (C) 2005-2012 Randy Dunlap ## +## Copyright (C) 2012 Dan Luedtke ## ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## @@ -35,6 +36,8 @@ use strict; # Small fixes (like spaces vs. \s in regex) # -- Tim Jansen +# 25/07/2012 - Added support for HTML5 +# -- Dan Luedtke # # 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 "

" +# modern html +my %highlights_html5 = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct_xml, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_html5 = $local_lt . "br /" . $local_gt; + # XML, docbook format my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", $type_constant, "\$1", @@ -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,223 @@ sub output_blockhead_html(%) { print "

\n"; } +#output sections in html5 +sub output_section_html5(%) { + my %args = %{$_[0]}; + my $section; + + foreach $section (@{$args{'sectionlist'}}) { + print "
\n"; + print "

$section

\n"; + print "

\n"; + output_highlight($args{'sections'}{$section}); + print "

\n"; + print "
\n"; + } +} + +# output enum in html5 +sub output_enum_html5(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "
\n"; + print "

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

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

Constants

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

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

\n"; + + print "
    \n"; + print "
  1. "; + print "typedef "; + print "" . $args{'typedef'} . ""; + print "
    2. \n"; + print "
\n"; + output_section_html5(@_); + print "
\n"; +} + +# output struct in html5 +sub output_struct_html5(%) { + my %args = %{$_[0]}; + my ($parameter); + + print "
\n"; + print "
\n"; + print "

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

"; + print "

". $args{'purpose'} . "

\n"; + print "
\n"; + print "
    \n"; + print "
  1. "; + print "" . $args{'type'} . " "; + print "" . $args{'struct'} . " {"; + print "
    2. \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "
  2. "; + if ($parameter =~ /^#/) { + print "" . $parameter ."\n"; + print "
    3. \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 "; + print "$parameter"; + print ") "; + print "($2);"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield + print "$1 "; + print "$parameter"; + print "$2;"; + } else { + print "$type "; + print "$parameter;"; + } + print "\n"; + } + print "
  3. };
    4. \n"; + print "
\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"; + } + print "
\n"; + print "
\n"; + output_section_html5(@_); + print "
\n"; +} + +# output function in html5 +sub output_function_html5(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print "
\n"; + print "
\n"; + print "

" . $args{'function'} . "

"; + print "

" . $args{'purpose'} . "

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

Arguments

\n"; + print "

\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"; + } + print "
\n"; + print "
\n"; + output_section_html5(@_); + print "
\n"; +} + +# output DOC: block header in html5 +sub output_blockhead_html5(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + foreach $section (@{$args{'sectionlist'}}) { + print "
\n"; + print "

$section

\n"; + print "

\n"; + output_highlight($args{'sections'}{$section}); + print "

\n"; + } + print "
\n"; +} + sub output_section_xml(%) { my %args = %{$_[0]}; my $section; -- 1.7.10