Skip to content

Commit 1b40c19

Browse files
Dan Luedtkemichal42
Dan Luedtke
authored and
michal42
committed
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: Dan Luedtke <mail@danrl.de> Acked-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Michal Marek <mmarek@suse.cz>
1 parent 0d7614f commit 1b40c19

File tree

1 file changed

+266
-7
lines changed

1 file changed

+266
-7
lines changed

‎scripts/kernel-doc‎

Lines changed: 266 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ use strict;
66
## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
77
## Copyright (C) 2001 Simon Huggins ##
88
## Copyright (C) 2005-2012 Randy Dunlap ##
9+
## Copyright (C) 2012 Dan Luedtke ##
910
## ##
1011
## #define enhancements by Armin Kuster <akuster@mvista.com> ##
1112
## Copyright (c) 2000 MontaVista Software, Inc. ##
@@ -35,6 +36,8 @@ use strict;
3536
# Small fixes (like spaces vs. \s in regex)
3637
# -- Tim Jansen <tim@tjansen.de>
3738

39+
# 25/07/2012 - Added support for HTML5
40+
# -- Dan Luedtke <mail@danrl.de>
3841

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

4649
# usage:
47-
# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ]
48-
# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
50+
# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
51+
# [ -no-doc-sections ]
52+
# [ -function funcname [ -function funcname ...] ]
53+
# c file(s)s > outputfile
4954
# or
50-
# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
55+
# [ -nofunction funcname [ -function funcname ...] ]
56+
# c file(s)s > outputfile
5157
#
52-
# Set output format using one of -docbook -html -text or -man. Default is man.
58+
# Set output format using one of -docbook -html -html5 -text or -man.
59+
# Default is man.
5360
# The -list format is for internal use by docproc.
5461
#
5562
# -no-doc-sections
@@ -182,6 +189,14 @@ my $local_lt = "\\\\\\\\lt:";
182189
my $local_gt = "\\\\\\\\gt:";
183190
my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
184191

192+
# html version 5
193+
my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
194+
$type_func, "<span class=\"func\">\$1</span>",
195+
$type_struct_xml, "<span class=\"struct\">\$1</span>",
196+
$type_env, "<span class=\"env\">\$1</span>",
197+
$type_param, "<span class=\"param\">\$1</span>" );
198+
my $blankline_html5 = $local_lt . "br /" . $local_gt;
199+
185200
# XML, docbook format
186201
my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
187202
$type_constant, "<constant>\$1</constant>",
@@ -309,6 +324,10 @@ while ($ARGV[0] =~ m/^-(.*)/) {
309324
$output_mode = "html";
310325
%highlights = %highlights_html;
311326
$blankline = $blankline_html;
327+
} elsif ($cmd eq "-html5") {
328+
$output_mode = "html5";
329+
%highlights = %highlights_html5;
330+
$blankline = $blankline_html5;
312331
} elsif ($cmd eq "-man") {
313332
$output_mode = "man";
314333
%highlights = %highlights_man;
@@ -351,10 +370,11 @@ while ($ARGV[0] =~ m/^-(.*)/) {
351370
# continue execution near EOF;
352371

353372
sub usage {
354-
print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n";
373+
print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";
355374
print " [ -no-doc-sections ]\n";
356375
print " [ -function funcname [ -function funcname ...] ]\n";
357376
print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
377+
print " [ -v ]\n";
358378
print " c source file(s) > outputfile\n";
359379
print " -v : verbose output, more warnings & other info listed\n";
360380
exit 1;
@@ -448,7 +468,8 @@ sub output_highlight {
448468
# confess "output_highlight got called with no args?\n";
449469
# }
450470

451-
if ($output_mode eq "html" || $output_mode eq "xml") {
471+
if ($output_mode eq "html" || $output_mode eq "html5" ||
472+
$output_mode eq "xml") {
452473
$contents = local_unescape($contents);
453474
# convert data read & converted thru xml_escape() into &xyz; format:
454475
$contents =~ s/\\\\\\/\&/g;
@@ -458,6 +479,11 @@ sub output_highlight {
458479
die $@ if $@;
459480
# print STDERR "contents af:$contents\n";
460481

482+
# strip whitespaces when generating html5
483+
if ($output_mode eq "html5") {
484+
$contents =~ s/^\s+//;
485+
$contents =~ s/\s+$//;
486+
}
461487
foreach $line (split "\n", $contents) {
462488
if ($line eq ""){
463489
print $lineprefix, local_unescape($blankline);
@@ -473,7 +499,7 @@ sub output_highlight {
473499
}
474500
}
475501

476-
#output sections in html
502+
# output sections in html
477503
sub output_section_html(%) {
478504
my %args = %{$_[0]};
479505
my $section;
@@ -633,6 +659,239 @@ sub output_blockhead_html(%) {
633659
print "<hr>\n";
634660
}
635661

662+
# output sections in html5
663+
sub output_section_html5(%) {
664+
my %args = %{$_[0]};
665+
my $section;
666+
667+
foreach $section (@{$args{'sectionlist'}}) {
668+
print "<section>\n";
669+
print "<h1>$section</h1>\n";
670+
print "<p>\n";
671+
output_highlight($args{'sections'}{$section});
672+
print "</p>\n";
673+
print "</section>\n";
674+
}
675+
}
676+
677+
# output enum in html5
678+
sub output_enum_html5(%) {
679+
my %args = %{$_[0]};
680+
my ($parameter);
681+
my $count;
682+
my $html5id;
683+
684+
$html5id = $args{'enum'};
685+
$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
686+
print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
687+
print "<h1>enum " . $args{'enum'} . "</h1>\n";
688+
print "<ol class=\"code\">\n";
689+
print "<li>";
690+
print "<span class=\"keyword\">enum</span> ";
691+
print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
692+
print "</li>\n";
693+
$count = 0;
694+
foreach $parameter (@{$args{'parameterlist'}}) {
695+
print "<li class=\"indent\">";
696+
print "<span class=\"param\">" . $parameter . "</span>";
697+
if ($count != $#{$args{'parameterlist'}}) {
698+
$count++;
699+
print ",";
700+
}
701+
print "</li>\n";
702+
}
703+
print "<li>};</li>\n";
704+
print "</ol>\n";
705+
706+
print "<section>\n";
707+
print "<h1>Constants</h1>\n";
708+
print "<dl>\n";
709+
foreach $parameter (@{$args{'parameterlist'}}) {
710+
print "<dt>" . $parameter . "</dt>\n";
711+
print "<dd>";
712+
output_highlight($args{'parameterdescs'}{$parameter});
713+
print "</dd>\n";
714+
}
715+
print "</dl>\n";
716+
print "</section>\n";
717+
output_section_html5(@_);
718+
print "</article>\n";
719+
}
720+
721+
# output typedef in html5
722+
sub output_typedef_html5(%) {
723+
my %args = %{$_[0]};
724+
my ($parameter);
725+
my $count;
726+
my $html5id;
727+
728+
$html5id = $args{'typedef'};
729+
$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
730+
print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
731+
print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
732+
733+
print "<ol class=\"code\">\n";
734+
print "<li>";
735+
print "<span class=\"keyword\">typedef</span> ";
736+
print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
737+
print "</li>\n";
738+
print "</ol>\n";
739+
output_section_html5(@_);
740+
print "</article>\n";
741+
}
742+
743+
# output struct in html5
744+
sub output_struct_html5(%) {
745+
my %args = %{$_[0]};
746+
my ($parameter);
747+
my $html5id;
748+
749+
$html5id = $args{'struct'};
750+
$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
751+
print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
752+
print "<hgroup>\n";
753+
print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
754+
print "<h2>". $args{'purpose'} . "</h2>\n";
755+
print "</hgroup>\n";
756+
print "<ol class=\"code\">\n";
757+
print "<li>";
758+
print "<span class=\"type\">" . $args{'type'} . "</span> ";
759+
print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
760+
print "</li>\n";
761+
foreach $parameter (@{$args{'parameterlist'}}) {
762+
print "<li class=\"indent\">";
763+
if ($parameter =~ /^#/) {
764+
print "<span class=\"param\">" . $parameter ."</span>\n";
765+
print "</li>\n";
766+
next;
767+
}
768+
my $parameter_name = $parameter;
769+
$parameter_name =~ s/\[.*//;
770+
771+
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
772+
$type = $args{'parametertypes'}{$parameter};
773+
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
774+
# pointer-to-function
775+
print "<span class=\"type\">$1</span> ";
776+
print "<span class=\"param\">$parameter</span>";
777+
print "<span class=\"type\">)</span> ";
778+
print "(<span class=\"args\">$2</span>);";
779+
} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
780+
# bitfield
781+
print "<span class=\"type\">$1</span> ";
782+
print "<span class=\"param\">$parameter</span>";
783+
print "<span class=\"bits\">$2</span>;";
784+
} else {
785+
print "<span class=\"type\">$type</span> ";
786+
print "<span class=\"param\">$parameter</span>;";
787+
}
788+
print "</li>\n";
789+
}
790+
print "<li>};</li>\n";
791+
print "</ol>\n";
792+
793+
print "<section>\n";
794+
print "<h1>Members</h1>\n";
795+
print "<dl>\n";
796+
foreach $parameter (@{$args{'parameterlist'}}) {
797+
($parameter =~ /^#/) && next;
798+
799+
my $parameter_name = $parameter;
800+
$parameter_name =~ s/\[.*//;
801+
802+
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
803+
print "<dt>" . $parameter . "</dt>\n";
804+
print "<dd>";
805+
output_highlight($args{'parameterdescs'}{$parameter_name});
806+
print "</dd>\n";
807+
}
808+
print "</dl>\n";
809+
print "</section>\n";
810+
output_section_html5(@_);
811+
print "</article>\n";
812+
}
813+
814+
# output function in html5
815+
sub output_function_html5(%) {
816+
my %args = %{$_[0]};
817+
my ($parameter, $section);
818+
my $count;
819+
my $html5id;
820+
821+
$html5id = $args{'function'};
822+
$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
823+
print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
824+
print "<hgroup>\n";
825+
print "<h1>" . $args{'function'} . "</h1>";
826+
print "<h2>" . $args{'purpose'} . "</h2>\n";
827+
print "</hgroup>\n";
828+
print "<ol class=\"code\">\n";
829+
print "<li>";
830+
print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
831+
print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
832+
print "</li>";
833+
$count = 0;
834+
foreach $parameter (@{$args{'parameterlist'}}) {
835+
print "<li class=\"indent\">";
836+
$type = $args{'parametertypes'}{$parameter};
837+
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
838+
# pointer-to-function
839+
print "<span class=\"type\">$1</span> ";
840+
print "<span class=\"param\">$parameter</span>";
841+
print "<span class=\"type\">)</span> ";
842+
print "(<span class=\"args\">$2</span>)";
843+
} else {
844+
print "<span class=\"type\">$type</span> ";
845+
print "<span class=\"param\">$parameter</span>";
846+
}
847+
if ($count != $#{$args{'parameterlist'}}) {
848+
$count++;
849+
print ",";
850+
}
851+
print "</li>\n";
852+
}
853+
print "<li>)</li>\n";
854+
print "</ol>\n";
855+
856+
print "<section>\n";
857+
print "<h1>Arguments</h1>\n";
858+
print "<p>\n";
859+
print "<dl>\n";
860+
foreach $parameter (@{$args{'parameterlist'}}) {
861+
my $parameter_name = $parameter;
862+
$parameter_name =~ s/\[.*//;
863+
864+
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
865+
print "<dt>" . $parameter . "</dt>\n";
866+
print "<dd>";
867+
output_highlight($args{'parameterdescs'}{$parameter_name});
868+
print "</dd>\n";
869+
}
870+
print "</dl>\n";
871+
print "</section>\n";
872+
output_section_html5(@_);
873+
print "</article>\n";
874+
}
875+
876+
# output DOC: block header in html5
877+
sub output_blockhead_html5(%) {
878+
my %args = %{$_[0]};
879+
my ($parameter, $section);
880+
my $count;
881+
my $html5id;
882+
883+
foreach $section (@{$args{'sectionlist'}}) {
884+
$html5id = $section;
885+
$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
886+
print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
887+
print "<h1>$section</h1>\n";
888+
print "<p>\n";
889+
output_highlight($args{'sections'}{$section});
890+
print "</p>\n";
891+
}
892+
print "</article>\n";
893+
}
894+
636895
sub output_section_xml(%) {
637896
my %args = %{$_[0]};
638897
my $section;

0 commit comments

Comments
 (0)