linux-kernel - [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20180207172624.24555-9-corbet@lwn.net>
Date:   Wed,  7 Feb 2018 10:26:24 -0700
From:   Jonathan Corbet <corbet@....net>
To:     linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org, mchehab@...nel.org, me@...in.cc,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

   if (desperate)
       run_in_circles();

kernel-doc currently fails to understand these literal blocks and applies
its normal markup to them, which is then treated as literal by sphinx.  The
result is unsightly markup instead of a useful code snippet.

Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them.  It's ugly, but that means it fits
in well with the rest of the script.

Signed-off-by: Jonathan Corbet <corbet@....net>
---
 scripts/kernel-doc | 55 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c6c9370a1e49..c984f82cb897 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -748,14 +748,59 @@ sub output_blockhead_rst(%) {
     }
 }
 
-sub output_highlight_rst {
-    my $contents = join "\n",@_;
-    my $line;
-
+#
+# Apply the RST highlights to a sub-block of text.
+#   
+sub highlight_block($) {
+    # The dohighlight kludge requires the text be called $contents
+    my $contents = shift;
     eval $dohighlight;
     die $@ if $@;
+    return $contents;
+}
 
-    foreach $line (split "\n", $contents) {
+sub output_highlight_rst {
+    my $input = join "\n",@_;
+    my $output = "";
+    my $line;
+    my $in_literal = 0;
+    my $litprefix;
+    my $block = "";
+
+    # The "dohighlight" hack requires that the data be called "$contents"
+    foreach $line (split "\n",$input) {
+	#
+	# If we're in a literal block, see if we should drop out
+	# of it.  Otherwise pass the line straight through unmunged.
+	#
+	if ($in_literal) {
+	    if (! ($line =~ /$litprefix/ || $line =~ /^\s*$/)) {
+		$in_literal = 0;
+	    }
+	    else {
+		$output .= $line . "\n";
+	    }
+	}
+	#
+	# Not in a literal block (or just dropped out)
+	#
+	if (! $in_literal) {
+	    $block .= $line . "\n";
+	    if ($line =~ /^[^.].*::$/) {
+		$in_literal = 1;
+		# Note current indentation - we'll go as long as it's deeper.
+		$line =~ /^(\s*)/;
+		$litprefix = '^' . $1 . ' ';
+		$output .= highlight_block($block);
+		$block = ""
+	    }
+	}
+    }
+
+    if ($block) {
+	$output .= highlight_block($block);
+    }
+    foreach $line (split "\n", $output) {
 	print $lineprefix . $line . "\n";
     }
 }
-- 
2.14.3