Received: by 10.223.176.5 with SMTP id f5csp459395wra; Fri, 9 Feb 2018 01:48:42 -0800 (PST) X-Google-Smtp-Source: AH8x2247/RCWJcv/JLB4wsKub/RsgPOZaXHhOWVtb55u8c0I4B/SOFqwWSHGuYNosZMU/uTIIqZJ X-Received: by 2002:a17:902:c81:: with SMTP id 1-v6mr2007021plt.281.1518169722246; Fri, 09 Feb 2018 01:48:42 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518169722; cv=none; d=google.com; s=arc-20160816; b=rRGAKpKSGZYI+fIbVH5yJHgGDz9HzyVsaEKVrNbG0CLWyH7ROPKapDy//e9FfaBecO SeCfTwadWLHYkX0l+J5OwJ5HGtfUvBLF2O+B0VKaxR90zx5+o+xb/w/wAj9cJXlNbZrz KDvUS8huIrHgsqWCtqCegHi39NNYePWEoU9gdDrFU7e0wy4Ge3nrTCo2VVJbA9C6zIHP XqrQdRaZUDTwtn/+covTr+kc3tQJi8eKDghpEApOmGw9b4AQ9K7XQPABnw9DEQfZZRSG jWF35hY1xD0WlVj/QL9lH6OmWfQrCHe38UzL3ffPd01KxYDNgr6yA+gq+3bTRnVVohv4 VpqA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:mime-version:message-id:date:references :organization:in-reply-to:subject:cc:to:from :arc-authentication-results; bh=KfPaSwlRGSEhWgdd6SlUAzr3qbqFZXuSqTo1ReecMQ4=; b=rKT8npQuOJPhRun57O5Q5wphBOfHet/Y9ysiHRCNF+asAZydr691lAVVIqB5LTck7p 4dHBH3zbaDLWw0EX/rGP0xBZvrXp2WRN/1w942tS+A6Gx/V4m1f2IHHHlP73RR2cRYMZ wL3u7GM3smZe9AASI8qXqVs2nzvV6kTci8d/T7AWDamMrTb1BfObfp3mYy97N2iz/Rwm //V6ks9i9N+12EElrgs/vd/aaydJjnTrLthNipvxD3ocfBnDMZfXcobPhJ1NbN8i98CF D2APajlvZ//pFv8wpbQiWV1umVJ+Ocjpg/qmekra6IGIW1uK0WXO5pYHTBUin9pQjv3Y Iwjg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id i3si1134621pgp.805.2018.02.09.01.48.25; Fri, 09 Feb 2018 01:48:42 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752337AbeBIJrT (ORCPT + 99 others); Fri, 9 Feb 2018 04:47:19 -0500 Received: from mga12.intel.com ([192.55.52.136]:7523 "EHLO mga12.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751299AbeBIJrQ (ORCPT ); Fri, 9 Feb 2018 04:47:16 -0500 X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 Feb 2018 01:47:15 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,482,1511856000"; d="scan'208";a="29440709" Received: from jnikula-mobl2.fi.intel.com (HELO localhost) ([10.237.72.62]) by fmsmga001.fm.intel.com with ESMTP; 09 Feb 2018 01:47:13 -0800 From: Jani Nikula To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, Jonathan Corbet Subject: Re: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments In-Reply-To: <20180207172624.24555-9-corbet@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20180207172624.24555-1-corbet@lwn.net> <20180207172624.24555-9-corbet@lwn.net> Date: Fri, 09 Feb 2018 11:47:08 +0200 Message-ID: <87y3k28pgj.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 07 Feb 2018, Jonathan Corbet wrote: > 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 =~ /^[^.].*::$/) { I think you should also add "code-block:: " to the regexp. There are only a few uses now, but I think someone's bound to hit the same problem with those. Perhaps also extract the regexp to a variable with a self-documenting name. Thanks for doing this. Not that I like it, but as you say, it fits right in the script. I have some ideas on how to do all of the highlights nicely as post-processing in the Sphinx extension, but we need this now and not somewhere in the distant future. BR, Jani. > + $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"; > } > } -- Jani Nikula, Intel Open Source Technology Center