Gitweb:     
http://git.kernel.org/git/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=6b5b55f6c404fa730a09a8254eb19f5a038afcc2
Commit:     6b5b55f6c404fa730a09a8254eb19f5a038afcc2
Parent:     51448e2ad72c3cdb50e4118edc47fbcbcc1d03d3
Author:     Randy Dunlap <[EMAIL PROTECTED]>
AuthorDate: Tue Oct 16 23:31:20 2007 -0700
Committer:  Linus Torvalds <[EMAIL PROTECTED]>
CommitDate: Wed Oct 17 08:43:05 2007 -0700

    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 <[EMAIL PROTECTED]>
    Cc: Johannes Berg <[EMAIL PROTECTED]>
    Signed-off-by: Andrew Morton <[EMAIL PROTECTED]>
    Signed-off-by: Linus Torvalds <[EMAIL PROTECTED]>
---
 scripts/kernel-doc |   41 ++++++++++++++++++++++++++++++++---------
 1 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 1f58351..1d14018 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -5,6 +5,7 @@ use strict;
 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
 ## Copyright (C) 2000, 1  Tim Waugh <[EMAIL PROTECTED]>          ##
 ## Copyright (C) 2001  Simon Huggins                             ##
+## Copyright (C) 2005-2007  Randy Dunlap                         ##
 ##                                                              ##
 ## #define enhancements by Armin Kuster <[EMAIL PROTECTED]>     ##
 ## Copyright (c) 2000 MontaVista Software, Inc.                         ##
@@ -161,7 +162,7 @@ my $type_constant = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w+)';
 my $type_struct = '\&((struct\s*)*[_\w]+)';
-my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';
+my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
 
 # Output conversion substitutions.
@@ -173,7 +174,9 @@ my %highlights_html = ( $type_constant, "<i>\$1</i>",
                        $type_struct_xml, "<i>\$1</i>",
                        $type_env, "<b><i>\$1</i></b>",
                        $type_param, "<tt><b>\$1</b></tt>" );
-my $blankline_html = "<p>";
+my $local_lt = "\\\\\\\\lt:";
+my $local_gt = "\\\\\\\\gt:";
+my $blankline_html = $local_lt . "p" . $local_gt;      # was "<p>"
 
 # XML, docbook format
 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
@@ -391,17 +394,19 @@ sub output_highlight {
 #      confess "output_highlight got called with no args?\n";
 #   }
 
+    if ($output_mode eq "html") {
+       $contents = local_unescape($contents);
+       # convert data read & converted thru xml_escape() into &xyz; format:
+       $contents =~ s/\\\\\\/&/g;
+    }
 #   print STDERR "contents b4:$contents\n";
     eval $dohighlight;
     die $@ if $@;
-    if ($output_mode eq "html") {
-       $contents =~ s/\\\\//;
-    }
 #   print STDERR "contents af:$contents\n";
 
     foreach $line (split "\n", $contents) {
        if ($line eq ""){
-           print $lineprefix, $blankline;
+           print $lineprefix, local_unescape($blankline);
        } else {
            $line =~ s/\\\\\\/\&/g;
            if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
@@ -1752,7 +1757,13 @@ sub process_state3_type($$) {
     }
 }
 
-# replace <, >, and &
+# xml_escape: replace <, >, and & in the text stream;
+#
+# however, formatting controls that are generated internally/locally in the
+# kernel-doc script are not escaped here; instead, they begin life like
+# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
+# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
+# just before actual output; (this is done by local_unescape())
 sub xml_escape($) {
        my $text = shift;
        if (($output_mode eq "text") || ($output_mode eq "man")) {
@@ -1764,6 +1775,18 @@ sub xml_escape($) {
        return $text;
 }
 
+# convert local escape strings to html
+# local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
+sub local_unescape($) {
+       my $text = shift;
+       if (($output_mode eq "text") || ($output_mode eq "man")) {
+               return $text;
+       }
+       $text =~ s/\\\\\\\\lt:/</g;
+       $text =~ s/\\\\\\\\gt:/>/g;
+       return $text;
+}
+
 sub process_file($) {
     my $file;
     my $identifier;
@@ -1903,7 +1926,7 @@ sub process_file($) {
        } elsif ($state == 4) {
                # Documentation block
                if (/$doc_block/) {
-                       dump_section($section, $contents);
+                       dump_section($section, xml_escape($contents));
                        output_intro({'sectionlist' => [EMAIL PROTECTED],
                                      'sections' => \%sections });
                        $contents = "";
@@ -1923,7 +1946,7 @@ sub process_file($) {
                }
                elsif (/$doc_end/)
                {
-                       dump_section($section, $contents);
+                       dump_section($section, xml_escape($contents));
                        output_intro({'sectionlist' => [EMAIL PROTECTED],
                                      'sections' => \%sections });
                        $contents = "";
-
To unsubscribe from this list: send the line "unsubscribe git-commits-head" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to