aboutsummaryrefslogtreecommitdiffstats
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorRandy Dunlap <randy.dunlap@oracle.com>2007-10-17 02:31:20 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-10-17 11:43:05 -0400
commit6b5b55f6c404fa730a09a8254eb19f5a038afcc2 (patch)
tree7d8398dbe550f13dcd2c6fb8116dc7393bfd2f2b /scripts/kernel-doc
parent51448e2ad72c3cdb50e4118edc47fbcbcc1d03d3 (diff)
kernel-doc: fix doc blocks and html
Johannes Berg reports (Thanks!) that &struct names are not highlighted in html output format when they are inside a DOC: block. DOC: blocks were not escaped thru xml_escape() like other kernel-doc comments were. Fixed that. However, that left a problem with <p> ($blankline_html) being processed thru xml_escape(), converting it to &lt;p&gt;, which isn't good for the generated html output (the <p> should remain unchanged), so this patch also introduces the notion of "local" kernel-doc meta-characters ('\\\\mnemonic:'), which are converted to html just before writing the stream to its output file. Please report any problems that you (anyone) see in "highlighting" in any output mode (text, man, html, xml). Also update copyright to include me. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc41
1 files changed, 32 insertions, 9 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 1f5835115cad..1d1401807e95 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -5,6 +5,7 @@ use strict;
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## 5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## 6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ## 7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2007 Randy Dunlap ##
8## ## 9## ##
9## #define enhancements by Armin Kuster <akuster@mvista.com> ## 10## #define enhancements by Armin Kuster <akuster@mvista.com> ##
10## Copyright (c) 2000 MontaVista Software, Inc. ## 11## Copyright (c) 2000 MontaVista Software, Inc. ##
@@ -161,7 +162,7 @@ my $type_constant = '\%([-_\w]+)';
161my $type_func = '(\w+)\(\)'; 162my $type_func = '(\w+)\(\)';
162my $type_param = '\@(\w+)'; 163my $type_param = '\@(\w+)';
163my $type_struct = '\&((struct\s*)*[_\w]+)'; 164my $type_struct = '\&((struct\s*)*[_\w]+)';
164my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)'; 165my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
165my $type_env = '(\$\w+)'; 166my $type_env = '(\$\w+)';
166 167
167# Output conversion substitutions. 168# Output conversion substitutions.
@@ -173,7 +174,9 @@ my %highlights_html = ( $type_constant, "<i>\$1</i>",
173 $type_struct_xml, "<i>\$1</i>", 174 $type_struct_xml, "<i>\$1</i>",
174 $type_env, "<b><i>\$1</i></b>", 175 $type_env, "<b><i>\$1</i></b>",
175 $type_param, "<tt><b>\$1</b></tt>" ); 176 $type_param, "<tt><b>\$1</b></tt>" );
176my $blankline_html = "<p>"; 177my $local_lt = "\\\\\\\\lt:";
178my $local_gt = "\\\\\\\\gt:";
179my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
177 180
178# XML, docbook format 181# XML, docbook format
179my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>", 182my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
@@ -391,17 +394,19 @@ sub output_highlight {
391# confess "output_highlight got called with no args?\n"; 394# confess "output_highlight got called with no args?\n";
392# } 395# }
393 396
397 if ($output_mode eq "html") {
398 $contents = local_unescape($contents);
399 # convert data read & converted thru xml_escape() into &xyz; format:
400 $contents =~ s/\\\\\\/&/g;
401 }
394# print STDERR "contents b4:$contents\n"; 402# print STDERR "contents b4:$contents\n";
395 eval $dohighlight; 403 eval $dohighlight;
396 die $@ if $@; 404 die $@ if $@;
397 if ($output_mode eq "html") {
398 $contents =~ s/\\\\//;
399 }
400# print STDERR "contents af:$contents\n"; 405# print STDERR "contents af:$contents\n";
401 406
402 foreach $line (split "\n", $contents) { 407 foreach $line (split "\n", $contents) {
403 if ($line eq ""){ 408 if ($line eq ""){
404 print $lineprefix, $blankline; 409 print $lineprefix, local_unescape($blankline);
405 } else { 410 } else {
406 $line =~ s/\\\\\\/\&/g; 411 $line =~ s/\\\\\\/\&/g;
407 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { 412 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
@@ -1752,7 +1757,13 @@ sub process_state3_type($$) {
1752 } 1757 }
1753} 1758}
1754 1759
1755# replace <, >, and & 1760# xml_escape: replace <, >, and & in the text stream;
1761#
1762# however, formatting controls that are generated internally/locally in the
1763# kernel-doc script are not escaped here; instead, they begin life like
1764# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
1765# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
1766# just before actual output; (this is done by local_unescape())
1756sub xml_escape($) { 1767sub xml_escape($) {
1757 my $text = shift; 1768 my $text = shift;
1758 if (($output_mode eq "text") || ($output_mode eq "man")) { 1769 if (($output_mode eq "text") || ($output_mode eq "man")) {
@@ -1764,6 +1775,18 @@ sub xml_escape($) {
1764 return $text; 1775 return $text;
1765} 1776}
1766 1777
1778# convert local escape strings to html
1779# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
1780sub local_unescape($) {
1781 my $text = shift;
1782 if (($output_mode eq "text") || ($output_mode eq "man")) {
1783 return $text;
1784 }
1785 $text =~ s/\\\\\\\\lt:/</g;
1786 $text =~ s/\\\\\\\\gt:/>/g;
1787 return $text;
1788}
1789
1767sub process_file($) { 1790sub process_file($) {
1768 my $file; 1791 my $file;
1769 my $identifier; 1792 my $identifier;
@@ -1903,7 +1926,7 @@ sub process_file($) {
1903 } elsif ($state == 4) { 1926 } elsif ($state == 4) {
1904 # Documentation block 1927 # Documentation block
1905 if (/$doc_block/) { 1928 if (/$doc_block/) {
1906 dump_section($section, $contents); 1929 dump_section($section, xml_escape($contents));
1907 output_intro({'sectionlist' => \@sectionlist, 1930 output_intro({'sectionlist' => \@sectionlist,
1908 'sections' => \%sections }); 1931 'sections' => \%sections });
1909 $contents = ""; 1932 $contents = "";
@@ -1923,7 +1946,7 @@ sub process_file($) {
1923 } 1946 }
1924 elsif (/$doc_end/) 1947 elsif (/$doc_end/)
1925 { 1948 {
1926 dump_section($section, $contents); 1949 dump_section($section, xml_escape($contents));
1927 output_intro({'sectionlist' => \@sectionlist, 1950 output_intro({'sectionlist' => \@sectionlist,
1928 'sections' => \%sections }); 1951 'sections' => \%sections });
1929 $contents = ""; 1952 $contents = "";