From patchwork Mon Sep 7 20:02:03 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Danilo Cesar Lemes de Paula X-Patchwork-Id: 7137661 Return-Path: X-Original-To: patchwork-intel-gfx@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 2F821BEEC1 for ; Mon, 7 Sep 2015 20:03:25 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 19321208C3 for ; Mon, 7 Sep 2015 20:03:24 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 341C0208D4 for ; Mon, 7 Sep 2015 20:03:19 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 3A1626E7AC; Mon, 7 Sep 2015 13:03:18 -0700 (PDT) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from bhuna.collabora.co.uk (bhuna.collabora.co.uk [93.93.135.160]) by gabe.freedesktop.org (Postfix) with ESMTPS id 407966E7AA; Mon, 7 Sep 2015 13:03:16 -0700 (PDT) Received: from [127.0.0.1] (localhost [127.0.0.1]) (Authenticated sender: danilo) with ESMTPSA id B1A123C886B4 From: Danilo Cesar Lemes de Paula To: Jonathan Corbet Date: Mon, 7 Sep 2015 17:02:03 -0300 Message-Id: <1441656124-8997-6-git-send-email-danilo.cesar@collabora.co.uk> X-Mailer: git-send-email 2.4.3 In-Reply-To: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> Cc: Michal Marek , Herbert Xu , Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-kernel@vger.kernel.org, dri-devel , Graham Whaley , Laurent Pinchart Subject: [Intel-gfx] [PATCH 5/6] scripts/kernel-doc: Improve Markdown results X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, T_RP_MATCHES_RCVD, 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 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 5fe572a..d6129e7 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'}) { @@ -2695,7 +2711,11 @@ sub process_file($) { { if ( $1 eq "" ) { - $contents .= $blankline; + if ($use_markdown) { + $contents .= "\n"; + } else { + $contents .= $blankline; + } } else {