From patchwork Wed Nov 25 17:07:58 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 7701611 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id E78569F1BE for ; Wed, 25 Nov 2015 17:08:24 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 3123A2087D for ; Wed, 25 Nov 2015 17:08:23 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 20B562085A for ; Wed, 25 Nov 2015 17:08:20 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 4F23B6EAF4; Wed, 25 Nov 2015 09:08:15 -0800 (PST) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wm0-f45.google.com (mail-wm0-f45.google.com [74.125.82.45]) by gabe.freedesktop.org (Postfix) with ESMTPS id 400876EAEE for ; Wed, 25 Nov 2015 09:08:13 -0800 (PST) Received: by wmww144 with SMTP id w144so77898773wmw.0 for ; Wed, 25 Nov 2015 09:08:12 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=33A/cbxrPljW/RjEukvv7CriUmr1hJT7Cm6n/uITQCw=; b=HmYflEVQmyhP0FE9RF/UFadKDQJhj4TQdMrQypzLFc0mh6Ym1E3IKXJjx88Wqf+Q6Q W/2uWoaLSl1WTMp0jODD8PTs9B92D0utUguSnUmIgFZMRi80JG+IxTsCjqFd28Ul6g6A HK9IQy22YU4ykh6ZV8sxYd2F1vWoixBNBnWJY= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=33A/cbxrPljW/RjEukvv7CriUmr1hJT7Cm6n/uITQCw=; b=aX6ENhE2+BRJYkGHSmzg2YLY0nOu/uFj8blFmiFF7SeXeeAJMtC3wZcJpyq2V0UrV7 E8ibilnXtCsNG1t1A/4G/b6Xj5E5GYVreWjoftwP4rLEsRcSiZefXx/cuQWcNYtzngFm 3ie0V3IoVEUaTaEj8yHzd8RuTQFADYMwLwZNcxKESoAJSZjw/2xUU4Y5zLOShglvxFI8 o7qHMevl8aqTQ+jpGH8muR5jUeG0udDt1fphAH9aJ18LcKXhZds6DcfiNwbhVsBwu8bW qr1LbKWfZfc6MwCWt+LmEJyeDxk775nPudlm/Aq3tWDkATl1HHlzPe9S+wvvmUEDaQA4 Vq4w== X-Gm-Message-State: ALoCoQmmW2Gm3NDf/EW+l/wLFn4/El6F9s3RJrk4O3UT/MG/i5fJbV+kAnwuP27KVyXll0rQb59b X-Received: by 10.194.222.195 with SMTP id qo3mr2685191wjc.51.1448471291969; Wed, 25 Nov 2015 09:08:11 -0800 (PST) Received: from phenom.ffwll.local (212-51-149-109.fiber7.init7.net. [212.51.149.109]) by smtp.gmail.com with ESMTPSA id h4sm24070603wjx.41.2015.11.25.09.08.10 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 25 Nov 2015 09:08:11 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 4/5] scripts/kernel-doc: Use asciidoc instead of markdown Date: Wed, 25 Nov 2015 18:07:58 +0100 Message-Id: <1448471279-19748-5-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.5.1 In-Reply-To: <1448471279-19748-1-git-send-email-daniel.vetter@ffwll.ch> References: <1448471279-19748-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Danilo Cesar Lemes de Paula , Jonathan Corbet , Daniel Vetter , Intel Graphics Development , Thomas Wood , Daniel Vetter X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Spam-Status: No, score=-4.7 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,RP_MATCHES_RCVD,T_DKIM_INVALID,UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP By popular demand. This needs some adjustment/fixups after feeding snippets to asciidoc since compared to markdown asciidown escapes xml markup and doesn't just let it through. The other noticeable change is that build times increase a lot - we need to launch the markup process per-snippet, there's a few thousand of them and asciidoc (python) has a substantial higher overhead per invocation than pandoc (haskell). Cc: Danilo Cesar Lemes de Paula Cc: Thomas Wood Cc: Jonathan Corbet Signed-off-by: Daniel Vetter --- Documentation/DocBook/Makefile | 6 +++--- scripts/kernel-doc | 12 +++++++++++- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 246ad38550e5..5335955c0de5 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -104,8 +104,8 @@ define rule_docproc endef %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE - @(which pandoc > /dev/null 2>&1) || \ - (echo "*** To get propper documentation you need to install pandoc ***";) + @(which asciidoc > /dev/null 2>&1) || \ + (echo "*** To get propper documentation you need to install asciidoc ***";) $(call if_changed_rule,docproc) # Tell kbuild to always build the programs @@ -116,7 +116,7 @@ notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \ db2xtemplate = db2TYPE -o $(dir $@) $< xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $< -ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found) +ifneq ($(shell which asciidoc >/dev/null 2>&1 && echo found),found) MARKDOWNREADY := ""; endif diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e01e74f15a22..c8eed5299a4b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -524,7 +524,7 @@ sub dump_doc_section { sub markdown_to_docbook { my $orig_content = $_[0]; - my $pid = open3( \*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR, "pandoc --columns=80 -f markdown -t docbook" ); + my $pid = open3( \*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR, "asciidoc --no-header-footer --backend=docbook45 -" ); print CHLD_IN "$orig_content"; close(CHLD_IN); @@ -605,6 +605,16 @@ sub output_highlight { # print STDERR "contents af:$contents\n"; if ($use_markdown) { $contents = markdown_to_docbook($contents); + + # Compared to markdown asciidoc doesn't let through arbitrary xml + # markup. We need to un-escape the kerneldoc markup for functions, + # structures, ... + $contents =~ s/<quote>(\S*)<\/quote>/$1<\/quote>/g; + $contents =~ s/<constant>(\S*)<\/constant>/$1<\/constant>/g; + $contents =~ s/<structname>(\S*)<\/structname>/$1<\/structname>/g; + $contents =~ s/<parameter>(\S*)<\/parameter>/$1<\/parameter>/g; + $contents =~ s/<function>(\S*)<\/function>/$1<\/function>/g; + $contents =~ s/<envar>(\S*)<\/envar>/$1<\/envar>/g; } # strip whitespaces when generating html5