Received: by 10.223.176.5 with SMTP id f5csp911585wra; Wed, 7 Feb 2018 09:28:35 -0800 (PST) X-Google-Smtp-Source: AH8x227yu4WyyyvsOTzdoTj8CNpLQxeRFbZHGnWTgHsNUGSzIHizIDhsgsvsU1LO1vIIAOkbwKwB X-Received: by 10.99.63.11 with SMTP id m11mr5682538pga.422.1518024515453; Wed, 07 Feb 2018 09:28:35 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518024515; cv=none; d=google.com; s=arc-20160816; b=ShyUj2LNn3+DBW6l0qAtAGf5J1tN4BpOBoHO2+5bsLMA+v/JSV7l1UduNiPJztAMqr Sp0523rE8lNCUDNLaTiyrJH4VA35PpXHAq8bBU9syDCPDwIrRRp2duIIAFLmomWjD0W4 F6fl3vfaKh0PSVysLM8UZSRZha0pzGXDfNE7EFfjhi4QpszA0jEgWaPmOu/TQbj43QRT svH2DkUC2REkveX6tM9xvqAXM05Nka8p4paV2Dp/bvBp07KcMW7dwoChGt8ydnfMUs5e x60q04Vfn9vbuhdCqcYADUDWWaXh9HIVyMUMmaSRC0aoD2CQDYLLYXoYYuEiJlRHnTGO sy/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:arc-authentication-results; bh=n31qdi7pjZ397x6Y5RtOYzskiNK7wDwoEZX8imXtToI=; b=L6u0QCXatggybwNjSNfB9tBuf1a8NXqYARWxyhGbXXrKQcKXKy6OH3V5/pbdjDwpm0 UxiK13zUYhgim+c0FmBixq79MzWP/D1jNrIt0/0+gcJl8jYQvpxvz5VchxEyVZHq4f85 p1KWYdXDWI8XsOtWC6eLweJvbQUp8DFpz+SYd4rfOSEv35JCiIdTXcj/KYlDWEX2YV6p BMqknDJvRKQh0VGYL10VTp/N6NmmILf7GQuKIi9Un+qmei2Ys3q+R6I/lWwAyzLjwVPc WWLRpRTUPkMFwHIVxoAnPi8pmEPiHQsw4RvLeT8pfLm/AiVIX4bK7stNmEZpeOUYiQeK DOug== 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 j67si1174985pgc.743.2018.02.07.09.28.21; Wed, 07 Feb 2018 09:28:35 -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 S1754889AbeBGR1X (ORCPT + 99 others); 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 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 4766D2B2; Wed, 7 Feb 2018 17:27:06 +0000 (UTC) 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 Precedence: bulk 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