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.
Showing the changes to scripts/kernel-doc (1 of 1 file). Show all
Unified · Split
| @@ -6,6 +6,7 @@ use strict; · 5 unmodified lines | ||
| 6 | 6 | ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## |
| 7 | 7 | ## Copyright (C) 2001 Simon Huggins ## |
| 8 | 8 | ## Copyright (C) 2005-2012 Randy Dunlap ## |
| 9 | +## Copyright (C) 2012 Dan Luedtke ## | |
| 9 | 10 | ## ## |
| 10 | 11 | ## #define enhancements by Armin Kuster <akuster@mvista.com> ## |
| 11 | 12 | ## Copyright (c) 2000 MontaVista Software, Inc. ## |
| @@ -35,6 +36,8 @@ use strict; · 23 unmodified lines | ||
| 35 | 36 | # Small fixes (like spaces vs. \s in regex) |
| 36 | 37 | # -- Tim Jansen <tim@tjansen.de> |
| 37 | 38 | |
| 39 | +# 25/07/2012 - Added support for HTML5 | |
| 40 | +# -- Dan Luedtke <mail@danrl.de> | |
| 38 | 41 | |
| 39 | 42 | # |
| 40 | 43 | # This will read a 'c' file and scan for embedded comments in the |
| @@ -44,12 +47,16 @@ use strict; · 3 unmodified lines | ||
| 44 | 47 | # Note: This only supports 'c'. |
| 45 | 48 | |
| 46 | 49 | # 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 | |
| 49 | 54 | # or |
| 50 | −# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile | |
| 55 | +# [ -nofunction funcname [ -function funcname ...] ] | |
| 56 | +# c file(s)s > outputfile | |
| 51 | 57 | # |
| 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. | |
| 53 | 60 | # The -list format is for internal use by docproc. |
| 54 | 61 | # |
| 55 | 62 | # -no-doc-sections |
| @@ -182,6 +189,14 @@ my $local_lt = "\\\\\\\\lt:"; · 126 unmodified lines | ||
| 182 | 189 | my $local_gt = "\\\\\\\\gt:"; |
| 183 | 190 | my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" |
| 184 | 191 | |
| 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 | + | |
| 185 | 200 | # XML, docbook format |
| 186 | 201 | my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>", |
| 187 | 202 | $type_constant, "<constant>\$1</constant>", |
| @@ -309,6 +324,10 @@ while ($ARGV[0] =~ m/^-(.*)/) { · 121 unmodified lines | ||
| 309 | 324 | $output_mode = "html"; |
| 310 | 325 | %highlights = %highlights_html; |
| 311 | 326 | $blankline = $blankline_html; |
| 327 | + } elsif ($cmd eq "-html5") { | |
| 328 | + $output_mode = "html5"; | |
| 329 | + %highlights = %highlights_html5; | |
| 330 | + $blankline = $blankline_html5; | |
| 312 | 331 | } elsif ($cmd eq "-man") { |
| 313 | 332 | $output_mode = "man"; |
| 314 | 333 | %highlights = %highlights_man; |
| @@ -351,10 +370,11 @@ while ($ARGV[0] =~ m/^-(.*)/) { · 36 unmodified lines | ||
| 351 | 370 | # continue execution near EOF; |
| 352 | 371 | |
| 353 | 372 | sub usage { |
| 354 | − print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n"; | |
| 373 | + print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n"; | |
| 355 | 374 | print " [ -no-doc-sections ]\n"; |
| 356 | 375 | print " [ -function funcname [ -function funcname ...] ]\n"; |
| 357 | 376 | print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; |
| 377 | + print " [ -v ]\n"; | |
| 358 | 378 | print " c source file(s) > outputfile\n"; |
| 359 | 379 | print " -v : verbose output, more warnings & other info listed\n"; |
| 360 | 380 | exit 1; |
| @@ -448,7 +468,8 @@ sub output_highlight { · 87 unmodified lines | ||
| 448 | 468 | # confess "output_highlight got called with no args?\n"; |
| 449 | 469 | # } |
| 450 | 470 | |
| 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") { | |
| 452 | 473 | $contents = local_unescape($contents); |
| 453 | 474 | # convert data read & converted thru xml_escape() into &xyz; format: |
| 454 | 475 | $contents =~ s/\\\\\\/\&/g; |
| @@ -458,6 +479,11 @@ sub output_highlight { · 3 unmodified lines | ||
| 458 | 479 | die $@ if $@; |
| 459 | 480 | # print STDERR "contents af:$contents\n"; |
| 460 | 481 | |
| 482 | +# strip whitespaces when generating html5 | |
| 483 | + if ($output_mode eq "html5") { | |
| 484 | + $contents =~ s/^\s+//; | |
| 485 | + $contents =~ s/\s+$//; | |
| 486 | + } | |
| 461 | 487 | foreach $line (split "\n", $contents) { |
| 462 | 488 | if ($line eq ""){ |
| 463 | 489 | print $lineprefix, local_unescape($blankline); |
| @@ -473,7 +499,7 @@ sub output_highlight { · 9 unmodified lines | ||
| 473 | 499 | } |
| 474 | 500 | } |
| 475 | 501 | |
| 476 | −#output sections in html | |
| 502 | +# output sections in html | |
| 477 | 503 | sub output_section_html(%) { |
| 478 | 504 | my %args = %{$_[0]}; |
| 479 | 505 | my $section; |
| @@ -633,6 +659,239 @@ sub output_blockhead_html(%) { · 153 unmodified lines | ||
| 633 | 659 | print "<hr>\n"; |
| 634 | 660 | } |
| 635 | 661 | |
| 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 | + | |
| 636 | 895 | sub output_section_xml(%) { |
| 637 | 896 | my %args = %{$_[0]}; |
| 638 | 897 | my $section; |