From patchwork Wed Feb 7 17:26:24 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 127196 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp683351ljc; Wed, 7 Feb 2018 09:27:25 -0800 (PST) X-Google-Smtp-Source: AH8x227dUbI4ebAy6Yj//Fg1xaff2BDcQE8bdq4gaqq/n8//QOCljntZJJ7+VSG8HxWvlvodTzn4 X-Received: by 2002:a17:902:4101:: with SMTP id e1-v6mr6756152pld.332.1518024445605; Wed, 07 Feb 2018 09:27:25 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518024445; cv=none; d=google.com; s=arc-20160816; b=B3234pUIGqIio6dv0nN5z9BHbHtxyh5H1L852mZ952s93BACp+kUdMY1ZoCa0Td4ff DHOqR7Yk0zPqs9GbETzNvQ279oTbRdLakKPtjYda6JHQVXK4EBfoqEqcHdpfhCpBxuPb WqUyIh9IDNvbFuCtiBmje9MCJzTi1fSkgjCaBrOF/IQpuwneD7ECtey2y9MyQHG4yi/T nGO8qcwCQoMax8Vpzp2tMKu/XoMnlPrcvG56KPhSlEP3nDvuUDZmJUe5W2o99EMod2Sy J+x0j5zYEumGL6UzOCmdJJDGKCCdS3jYG6V2qbs/aO8ilq0SxrEViP8xgAOTJgbPGxfv 26wA== 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 c19-v6si1370618plo.278.2018.02.07.09.27.25; Wed, 07 Feb 2018 09:27:25 -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 S1754893AbeBGR1X (ORCPT + 18 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(-) -- 2.14.3 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"; } }