From patchwork Wed Nov 25 17:07:57 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 7701631 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 9DDA4C05CA for ; Wed, 25 Nov 2015 17:08:25 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id C4C6B20890 for ; Wed, 25 Nov 2015 17:08:20 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 4B3C920804 for ; Wed, 25 Nov 2015 17:08:15 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 166F96EAEA; Wed, 25 Nov 2015 09:08:13 -0800 (PST) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wm0-f52.google.com (mail-wm0-f52.google.com [74.125.82.52]) by gabe.freedesktop.org (Postfix) with ESMTPS id 33D8D6EAE9 for ; Wed, 25 Nov 2015 09:08:12 -0800 (PST) Received: by wmvv187 with SMTP id v187so266807518wmv.1 for ; Wed, 25 Nov 2015 09:08:11 -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=Fg7visGFXzYXFDK9kw3fl41uPYZVOWWUpm+iyLqBAfU=; b=M838lZDjnY2hohALAGB8Hy2HziyB2VR4I7i2qo4nVLcxryz+VwTqCD87fP2c8Nz5If DJ6qJlkDr/Dwtq3aQH8bbgiSYZgWoSSGsDpakagOSdkP1ZF/s2XRTvqvrR2ADP967/bl xLSoRHjEaJ0kXsYfreP3NbFILHYPzhC9B0lLY= 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=Fg7visGFXzYXFDK9kw3fl41uPYZVOWWUpm+iyLqBAfU=; b=QYdbTyHxrSRR/TJFsbCvHH5o6yJTBIYL5QjXSK4at7s/w1SCytgTg3aF+LleaqTYqR jvrtJLYfaR5MAg0yyk/JHpXZcVg4jevlI2q4qkZPZ3RfB4d/wqL9sd+643dEX/mO+c0E crABsFuuL5aGZuBdIl2gkkEmJBySmOaUezNRHdfT+Hmc6uurDMxoNaj7ZDc9Yjes3I/g JMPOBcikaIyGayFM8dsLmSmVDCFpunHEVn/7Ox0ZgJ0Mim6wGoVBwsDr2YAfSD2O6hEH SIJ+ifZXyLvEMy2dKWXAWJ/BK6IxL96YTlTcpPkYyBqqpsVrRaI1YgJlZFvF6SCiwmsW t11g== X-Gm-Message-State: ALoCoQl3vOhVuoeImskzr5BluNfPfvW81BY+fgWljj/kJe/3s9gbON0H79vYCXSCkIUlLq2cuXCL X-Received: by 10.194.185.234 with SMTP id ff10mr44027430wjc.170.1448471290908; Wed, 25 Nov 2015 09:08:10 -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.09 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 25 Nov 2015 09:08:10 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 3/5] scripts/kernel-doc: Improve Markdown results Date: Wed, 25 Nov 2015 18:07:57 +0100 Message-Id: <1448471279-19748-4-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: Michal Marek , Herbert Xu , Danilo Cesar Lemes de Paula , Jonathan Corbet , Stephan Mueller , Daniel Vetter , Intel Graphics Development , Randy Dunlap , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Graham Whaley , Laurent Pinchart 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 From: Danilo Cesar Lemes de Paula Using pandoc as the Markdown engine cause some minor side effects as pandoc includes main tags for almost everything. Original Markdown support approach removes those main tags, but it caused some inconsistencies when that tag is not the main one, like: .. ... As kernel-doc was already including a tag, it causes the presence of double tags (), which is not supported by DocBook spec. Html target gets away with it, so it causes no harm, although other targets might not be so lucky (pdf as example). We're now delegating the inclusion of the main tag to pandoc only, as it knows when it's necessary or not. That behavior causes a corner case, the only situation where we're certainly that is not needed, which is the content. For those cases, we're using a $output_markdown_nopara = 1 control var. Signed-off-by: Danilo Cesar Lemes de Paula Cc: Randy Dunlap Cc: Daniel Vetter Cc: Laurent Pinchart Cc: Jonathan Corbet Cc: Herbert Xu Cc: Stephan Mueller Cc: Michal Marek Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx Cc: dri-devel Cc: Graham Whaley --- scripts/kernel-doc | 48 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 14 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 28737053395a..e01e74f15a22 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -288,6 +288,7 @@ my $use_markdown = 0; my $verbose = 0; my $output_mode = "man"; my $output_preformatted = 0; +my $output_markdown_nopara = 0; my $no_doc_sections = 0; my @highlights = @highlights_man; my $blankline = $blankline_man; @@ -538,8 +539,11 @@ sub markdown_to_docbook { close(CHLD_OUT); close(CHLD_ERR); - # pandoc insists in adding Main , we should remove them. - $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm; + if ($output_markdown_nopara) { + # pandoc insists in adding Main , sometimes we + # want to remove them. + $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm; + } return $content; } @@ -614,7 +618,7 @@ sub output_highlight { $line =~ s/^\s*//; } if ($line eq ""){ - if (! $output_preformatted) { + if (! $output_preformatted && ! $use_markdown) { print $lineprefix, local_unescape($blankline); } } else { @@ -1035,7 +1039,7 @@ sub output_section_xml(%) { # programlisting is already included by pandoc print "\n" unless $use_markdown; $output_preformatted = 1; - } else { + } elsif (! $use_markdown) { print "\n"; } output_highlight($args{'sections'}{$section}); @@ -1043,7 +1047,7 @@ sub output_section_xml(%) { if ($section =~ m/EXAMPLE/i) { print "\n" unless $use_markdown; print "\n"; - } else { + } elsif (! $use_markdown) { print "\n"; } print "\n"; @@ -1075,7 +1079,9 @@ sub output_function_xml(%) { print " " . $args{'function'} . "\n"; print " \n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " \n"; print "\n"; @@ -1113,10 +1119,12 @@ sub output_function_xml(%) { $parameter_name =~ s/\[.*//; print " \n $parameter\n"; - print " \n \n"; + print " \n"; + print " \n" unless $use_markdown; $lineprefix=" "; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " \n \n \n"; + print " \n" unless $use_markdown; + print " \n \n"; } print " \n"; } else { @@ -1152,7 +1160,9 @@ sub output_struct_xml(%) { print " " . $args{'type'} . " " . $args{'struct'} . "\n"; print " \n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " \n"; print "\n"; @@ -1205,9 +1215,11 @@ sub output_struct_xml(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print " "; print " $parameter\n"; - print " \n"; + print " \n"; + print " \n" unless $use_markdown; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " \n"; + print " \n" unless $use_markdown; + print " \n"; print " \n"; } print " \n"; @@ -1246,7 +1258,9 @@ sub output_enum_xml(%) { print " enum " . $args{'enum'} . "\n"; print " \n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " \n"; print "\n"; @@ -1276,9 +1290,11 @@ sub output_enum_xml(%) { print " "; print " $parameter\n"; - print " \n"; + print " \n"; + print " \n" unless $use_markdown; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " \n"; + print " \n" unless $use_markdown; + print " \n"; print " \n"; } print " \n"; @@ -1344,14 +1360,14 @@ sub output_blockhead_xml(%) { if ($section =~ m/EXAMPLE/i) { print "\n"; $output_preformatted = 1; - } else { + } elsif (! $use_markdown) { print "\n"; } output_highlight($args{'sections'}{$section}); $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "\n"; - } else { + } elsif (! $use_markdown) { print ""; } if (!$args{'content-only'}) { @@ -2721,7 +2737,11 @@ sub process_file($) { { if ( $1 eq "" ) { - $contents .= $blankline; + if ($use_markdown) { + $contents .= "\n"; + } else { + $contents .= $blankline; + } } else {