From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754892AbeBGR1X (ORCPT ); Wed, 7 Feb 2018 12:27:23 -0500 Received: from ms.lwn.net ([45.79.88.28]:41668 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754466AbeBGR1H (ORCPT ); Wed, 7 Feb 2018 12:27:07 -0500 From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, Jonathan Corbet Subject: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments Date: Wed, 7 Feb 2018 10:26:24 -0700 Message-Id: <20180207172624.24555-9-corbet@lwn.net> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180207172624.24555-1-corbet@lwn.net> References: <20180207172624.24555-1-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- 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