* [PATCH] scripts/kernel-doc: added support for html5
@ 2012-07-25 13:38 Dan Luedtke
2012-07-25 13:50 ` FYI: Example [Re: [PATCH] scripts/kernel-doc: added support for html5] Dan Luedtke
2012-07-25 18:14 ` [PATCH] scripts/kernel-doc: added support for html5 Randy Dunlap
0 siblings, 2 replies; 8+ messages in thread
From: Dan Luedtke @ 2012-07-25 13:38 UTC (permalink / raw)
To: rdunlap; +Cc: mail, linux-kernel
New output option html5 writes validating HTML5 and adds
CSS classes ready to be selected by third-party stylesheets.
Signed-off-by: Dan Luedtke <mail@danrl.de>
---
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 <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>"
+# modern html
+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,223 @@ 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;
+ print "<article class=\"enum\">\n";
+ 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;
+
+ print "<article class=\"typedef\">\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);
+
+ print "<article class=\"struct\">\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;
+
+ print "<article class=\"function\">\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;
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print "<article class=\"doc\">\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;
--
1.7.10
^ permalink raw reply related [flat|nested] 8+ messages in thread* FYI: Example [Re: [PATCH] scripts/kernel-doc: added support for html5]
2012-07-25 13:38 [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
@ 2012-07-25 13:50 ` Dan Luedtke
2012-07-25 18:14 ` [PATCH] scripts/kernel-doc: added support for html5 Randy Dunlap
1 sibling, 0 replies; 8+ messages in thread
From: Dan Luedtke @ 2012-07-25 13:50 UTC (permalink / raw)
To: linux-kernel
On Wed, 2012-07-25 at 15:38 +0200, Dan Luedtke wrote:
> New output option html5 writes validating HTML5 and adds
> CSS classes ready to be selected by third-party stylesheets.
An example, generated with the patched version of kernel-doc:
https://www.nonattached.net/lanyfs/doc-linux.php
Uses CSS like this:
article.doc,
article.enum,
article.typedef,
article.struct,
article.function {
margin-bottom: 50px;
}
/* markup */
span.keyword {
font-weight: bold;
color: #000;
}
span.type {
font-weight: normal;
color: #284689;
}
span.identifier {
font-weight: bold;
color: #c43;
}
--
Dan Luedtke
http://www.danrl.de
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [PATCH] scripts/kernel-doc: added support for html5
2012-07-25 13:38 [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
2012-07-25 13:50 ` FYI: Example [Re: [PATCH] scripts/kernel-doc: added support for html5] Dan Luedtke
@ 2012-07-25 18:14 ` Randy Dunlap
2012-07-26 6:52 ` [PATCH 1/3] " Dan Luedtke
2012-07-26 6:53 ` [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
1 sibling, 2 replies; 8+ messages in thread
From: Randy Dunlap @ 2012-07-25 18:14 UTC (permalink / raw)
To: Dan Luedtke; +Cc: linux-kernel
On 07/25/2012 06:38 AM, Dan Luedtke wrote:
> New output option html5 writes validating HTML5 and adds
> CSS classes ready to be selected by third-party stylesheets.
>
> Signed-off-by: Dan Luedtke <mail@danrl.de>
> ---
> 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
> @@ -182,6 +189,14 @@ my $local_lt = "\\\\\\\\lt:";
> my $local_gt = "\\\\\\\\gt:";
> my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
>
> +# modern html
Just say "html5" or "html version 5".
A few years from now it won't be modern.
> +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>",
Have you tested typedef, enum, DOC:, etc.?
The example web page that you posted does not use that AFAICT.
Otherwise it looks OK to me.
Thanks,
--
~Randy
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH 1/3] scripts/kernel-doc: added support for html5
2012-07-25 18:14 ` [PATCH] scripts/kernel-doc: added support for html5 Randy Dunlap
@ 2012-07-26 6:52 ` Dan Luedtke
2012-07-26 6:52 ` [PATCH 2/3] scripts/kernel-doc: modern html -> html version 5 Dan Luedtke
2012-07-26 6:52 ` [PATCH 3/3] scripts/kernel-doc: added ids to articles for reference Dan Luedtke
2012-07-26 6:53 ` [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
1 sibling, 2 replies; 8+ messages in thread
From: Dan Luedtke @ 2012-07-26 6:52 UTC (permalink / raw)
To: rdunlap, linux-kernel; +Cc: Dan Luedtke
New output option html5 writes validating HTML5 and adds
CSS classes ready to be selected by third-party stylesheets.
Signed-off-by: Dan Luedtke <mail@danrl.de>
---
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 <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>"
+# modern html
+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,223 @@ 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;
+ print "<article class=\"enum\">\n";
+ 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;
+
+ print "<article class=\"typedef\">\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);
+
+ print "<article class=\"struct\">\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;
+
+ print "<article class=\"function\">\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;
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print "<article class=\"doc\">\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;
--
1.7.10
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH 2/3] scripts/kernel-doc: modern html -> html version 5
2012-07-26 6:52 ` [PATCH 1/3] " Dan Luedtke
@ 2012-07-26 6:52 ` Dan Luedtke
2012-07-26 6:52 ` [PATCH 3/3] scripts/kernel-doc: added ids to articles for reference Dan Luedtke
1 sibling, 0 replies; 8+ messages in thread
From: Dan Luedtke @ 2012-07-26 6:52 UTC (permalink / raw)
To: rdunlap, linux-kernel; +Cc: Dan Luedtke
Fixed non-timeless comment.
Signed-off-by: Dan Luedtke <mail@danrl.de>
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f85b278..1d3c779 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -189,7 +189,7 @@ my $local_lt = "\\\\\\\\lt:";
my $local_gt = "\\\\\\\\gt:";
my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
-# modern html
+# 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>",
--
1.7.10
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 3/3] scripts/kernel-doc: added ids to articles for reference
2012-07-26 6:52 ` [PATCH 1/3] " Dan Luedtke
2012-07-26 6:52 ` [PATCH 2/3] scripts/kernel-doc: modern html -> html version 5 Dan Luedtke
@ 2012-07-26 6:52 ` Dan Luedtke
1 sibling, 0 replies; 8+ messages in thread
From: Dan Luedtke @ 2012-07-26 6:52 UTC (permalink / raw)
To: rdunlap, linux-kernel; +Cc: Dan Luedtke
An id has been added to block-level elements "article". This allows
jumping to a particular article via url. E.g. doc.html#func:foo
would sroll down to the documentation of function foo.
Signed-off-by: Dan Luedtke <mail@danrl.de>
---
scripts/kernel-doc | 30 +++++++++++++++++++++++-------
1 file changed, 23 insertions(+), 7 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 1d3c779..97e037a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -499,7 +499,7 @@ sub output_highlight {
}
}
-#output sections in html
+# output sections in html
sub output_section_html(%) {
my %args = %{$_[0]};
my $section;
@@ -659,7 +659,7 @@ sub output_blockhead_html(%) {
print "<hr>\n";
}
-#output sections in html5
+# output sections in html5
sub output_section_html5(%) {
my %args = %{$_[0]};
my $section;
@@ -679,7 +679,11 @@ sub output_enum_html5(%) {
my %args = %{$_[0]};
my ($parameter);
my $count;
- print "<article class=\"enum\">\n";
+ 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>";
@@ -719,8 +723,11 @@ sub output_typedef_html5(%) {
my %args = %{$_[0]};
my ($parameter);
my $count;
+ my $html5id;
- print "<article class=\"typedef\">\n";
+ $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";
@@ -737,8 +744,11 @@ sub output_typedef_html5(%) {
sub output_struct_html5(%) {
my %args = %{$_[0]};
my ($parameter);
+ my $html5id;
- print "<article class=\"struct\">\n";
+ $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";
@@ -806,8 +816,11 @@ sub output_function_html5(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $count;
+ my $html5id;
- print "<article class=\"function\">\n";
+ $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";
@@ -865,9 +878,12 @@ sub output_blockhead_html5(%) {
my %args = %{$_[0]};
my ($parameter, $section);
my $count;
+ my $html5id;
foreach $section (@{$args{'sectionlist'}}) {
- print "<article class=\"doc\">\n";
+ $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});
--
1.7.10
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] scripts/kernel-doc: added support for html5
2012-07-25 18:14 ` [PATCH] scripts/kernel-doc: added support for html5 Randy Dunlap
2012-07-26 6:52 ` [PATCH 1/3] " Dan Luedtke
@ 2012-07-26 6:53 ` Dan Luedtke
2012-07-26 15:13 ` Randy Dunlap
1 sibling, 1 reply; 8+ messages in thread
From: Dan Luedtke @ 2012-07-26 6:53 UTC (permalink / raw)
To: Randy Dunlap; +Cc: linux-kernel
On Wed, 2012-07-25 at 11:14 -0700, Randy Dunlap wrote:
> Just say "html5" or "html version 5".
> A few years from now it won't be modern.
Haven't thought of that. Will be changed, thanks!
> Have you tested typedef, enum, DOC:, etc.?
Yes, here are a few examples:
DOC:
https://www.nonattached.net/lanyfs/doc-linux.php#doc:LanyFS_Inode_Cache
Typedef:
https://www.nonattached.net/lanyfs/doc-linux.php#typedef:lanyfs_blk_t
(You were right, it wasn't there yesterday, sorry!)
Enum:
https://www.nonattached.net/lanyfs/doc-fsutils.php#enum:mklanyfs_time
(It is a userspace tool, but it uses kernel-doc format)
I'll send the patches out in a minute.
Thanks!
Dan
--
Dan Luedtke
http://www.danrl.de
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] scripts/kernel-doc: added support for html5
2012-07-26 6:53 ` [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
@ 2012-07-26 15:13 ` Randy Dunlap
0 siblings, 0 replies; 8+ messages in thread
From: Randy Dunlap @ 2012-07-26 15:13 UTC (permalink / raw)
To: Dan Luedtke; +Cc: linux-kernel
On 07/25/2012 11:53 PM, Dan Luedtke wrote:
> On Wed, 2012-07-25 at 11:14 -0700, Randy Dunlap wrote:
>> Just say "html5" or "html version 5".
>> A few years from now it won't be modern.
> Haven't thought of that. Will be changed, thanks!
>
>> Have you tested typedef, enum, DOC:, etc.?
> Yes, here are a few examples:
>
> DOC:
> https://www.nonattached.net/lanyfs/doc-linux.php#doc:LanyFS_Inode_Cache
>
> Typedef:
> https://www.nonattached.net/lanyfs/doc-linux.php#typedef:lanyfs_blk_t
> (You were right, it wasn't there yesterday, sorry!)
>
> Enum:
> https://www.nonattached.net/lanyfs/doc-fsutils.php#enum:mklanyfs_time
> (It is a userspace tool, but it uses kernel-doc format)
>
> I'll send the patches out in a minute.
>
> Thanks!
and thanks for the tested examples.
--
~Randy
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2012-07-26 15:15 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-07-25 13:38 [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
2012-07-25 13:50 ` FYI: Example [Re: [PATCH] scripts/kernel-doc: added support for html5] Dan Luedtke
2012-07-25 18:14 ` [PATCH] scripts/kernel-doc: added support for html5 Randy Dunlap
2012-07-26 6:52 ` [PATCH 1/3] " Dan Luedtke
2012-07-26 6:52 ` [PATCH 2/3] scripts/kernel-doc: modern html -> html version 5 Dan Luedtke
2012-07-26 6:52 ` [PATCH 3/3] scripts/kernel-doc: added ids to articles for reference Dan Luedtke
2012-07-26 6:53 ` [PATCH] scripts/kernel-doc: added support for html5 Dan Luedtke
2012-07-26 15:13 ` Randy Dunlap
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox