From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755368AbbIAR6c (ORCPT ); Tue, 1 Sep 2015 13:58:32 -0400 Received: from bhuna.collabora.co.uk ([93.93.135.160]:55924 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754352AbbIAR5m (ORCPT ); Tue, 1 Sep 2015 13:57:42 -0400 Subject: Re: [PATCH] scripts/kernel-doc: Improve Markdown results Cc: Randy Dunlap , Daniel Vetter , Laurent Pinchart , Jonathan Corbet , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, intel-gfx , dri-devel , Graham Whaley References: <1440185942-31030-1-git-send-email-danilo.cesar@collabora.co.uk> From: Danilo Cesar Lemes de Paula X-Enigmail-Draft-Status: N1110 Message-ID: <55E5E70D.4050201@collabora.co.uk> Date: Tue, 1 Sep 2015 14:57:33 -0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 MIME-Version: 1.0 In-Reply-To: <1440185942-31030-1-git-send-email-danilo.cesar@collabora.co.uk> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit To: unlisted-recipients:; (no To-header on input) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 08/21/2015 04:39 PM, Danilo Cesar Lemes de Paula wrote: > 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 > --- > Thanks to Graham Whaley who helped me to debug this. > > scripts/kernel-doc | 48 ++++++++++++++++++++++++++++++++++-------------- > 1 file changed, 34 insertions(+), 14 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index 3850c1e..12a106c 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; > @@ -529,8 +530,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; > } > @@ -605,7 +609,7 @@ sub output_highlight { > $line =~ s/^\s*//; > } > if ($line eq ""){ > - if (! $output_preformatted) { > + if (! $output_preformatted && ! $use_markdown) { > print $lineprefix, local_unescape($blankline); > } > } else { > @@ -1026,7 +1030,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}); > @@ -1034,7 +1038,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"; > @@ -1066,7 +1070,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"; > > @@ -1104,10 +1110,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 { > @@ -1143,7 +1151,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"; > > @@ -1196,9 +1206,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"; > @@ -1237,7 +1249,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"; > > @@ -1267,9 +1281,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"; > @@ -1335,14 +1351,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'}) { > @@ -2684,7 +2700,11 @@ sub process_file($) { > { > if ( $1 eq "" ) > { > - $contents .= $blankline; > + if ($use_markdown) { > + $contents .= "\n"; > + } else { > + $contents .= $blankline; > + } > } > else > { > Hey Jonathan, Did you find time to check this patch? As you mentioned that you applied the Markdown support for the linux-next tree, this patch might be needed (maybe "wanted" is a better word). Intel guys are working on improving documentation and I believe they need this. Thanks, Danilo