From: Daniel Vetter <daniel.vetter@ffwll.ch> To: DRI Development <dri-devel@lists.freedesktop.org> Cc: Intel Graphics Development <intel-gfx@lists.freedesktop.org>, Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>, Randy Dunlap <rdunlap@infradead.org>, Daniel Vetter <daniel.vetter@ffwll.ch>, Laurent Pinchart <laurent.pinchart@ideasonboard.com>, Jonathan Corbet <corbet@lwn.net>, Herbert Xu <herbert@gondor.apana.org.au>, Stephan Mueller <smueller@chronox.de>, Michal Marek <mmarek@suse.cz>, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, Graham Whaley <graham.whaley@linux.intel.com> Subject: [PATCH 3/5] scripts/kernel-doc: Improve Markdown results Date: Wed, 25 Nov 2015 18:07:57 +0100 [thread overview] Message-ID: <1448471279-19748-4-git-send-email-daniel.vetter@ffwll.ch> (raw) In-Reply-To: <1448471279-19748-1-git-send-email-daniel.vetter@ffwll.ch> From: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Using pandoc as the Markdown engine cause some minor side effects as pandoc includes main <para> 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: <something>..</something> <para>...</para> As kernel-doc was already including a <para> tag, it causes the presence of double <para> tags (<para><para>), 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 <para> 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 <para> is not needed, which is the <refpurpose> content. For those cases, we're using a $output_markdown_nopara = 1 control var. Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Herbert Xu <herbert@gondor.apana.org.au> Cc: Stephan Mueller <smueller@chronox.de> Cc: Michal Marek <mmarek@suse.cz> Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx <intel-gfx@lists.freedesktop.org> Cc: dri-devel <dri-devel@lists.freedesktop.org> Cc: Graham Whaley <graham.whaley@linux.intel.com> --- 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 <para></para>, we should remove them. - $content =~ s:\A\s*<para>\s*\n(.*)\n</para>\Z$:$1:egsm; + if ($output_markdown_nopara) { + # pandoc insists in adding Main <para></para>, sometimes we + # want to remove them. + $content =~ s:\A\s*<para>\s*\n(.*)\n</para>\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 "<programlisting>\n" unless $use_markdown; $output_preformatted = 1; - } else { + } elsif (! $use_markdown) { print "<para>\n"; } output_highlight($args{'sections'}{$section}); @@ -1043,7 +1047,7 @@ sub output_section_xml(%) { if ($section =~ m/EXAMPLE/i) { print "</programlisting>\n" unless $use_markdown; print "</informalexample>\n"; - } else { + } elsif (! $use_markdown) { print "</para>\n"; } print "</refsect1>\n"; @@ -1075,7 +1079,9 @@ sub output_function_xml(%) { print " <refname>" . $args{'function'} . "</refname>\n"; print " <refpurpose>\n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " </refpurpose>\n"; print "</refnamediv>\n"; @@ -1113,10 +1119,12 @@ sub output_function_xml(%) { $parameter_name =~ s/\[.*//; print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n"; - print " <listitem>\n <para>\n"; + print " <listitem>\n"; + print " <para>\n" unless $use_markdown; $lineprefix=" "; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para>\n </listitem>\n </varlistentry>\n"; + print " </para>\n" unless $use_markdown; + print " </listitem>\n </varlistentry>\n"; } print " </variablelist>\n"; } else { @@ -1152,7 +1160,9 @@ sub output_struct_xml(%) { print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n"; print " <refpurpose>\n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " </refpurpose>\n"; print "</refnamediv>\n"; @@ -1205,9 +1215,11 @@ sub output_struct_xml(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print " <varlistentry>"; print " <term>$parameter</term>\n"; - print " <listitem><para>\n"; + print " <listitem>\n"; + print " <para>\n" unless $use_markdown; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para></listitem>\n"; + print " </para>\n" unless $use_markdown; + print " </listitem>\n"; print " </varlistentry>\n"; } print " </variablelist>\n"; @@ -1246,7 +1258,9 @@ sub output_enum_xml(%) { print " <refname>enum " . $args{'enum'} . "</refname>\n"; print " <refpurpose>\n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " </refpurpose>\n"; print "</refnamediv>\n"; @@ -1276,9 +1290,11 @@ sub output_enum_xml(%) { print " <varlistentry>"; print " <term>$parameter</term>\n"; - print " <listitem><para>\n"; + print " <listitem>\n"; + print " <para>\n" unless $use_markdown; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para></listitem>\n"; + print " </para>\n" unless $use_markdown; + print " </listitem>\n"; print " </varlistentry>\n"; } print " </variablelist>\n"; @@ -1344,14 +1360,14 @@ sub output_blockhead_xml(%) { if ($section =~ m/EXAMPLE/i) { print "<example><para>\n"; $output_preformatted = 1; - } else { + } elsif (! $use_markdown) { print "<para>\n"; } output_highlight($args{'sections'}{$section}); $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "</para></example>\n"; - } else { + } elsif (! $use_markdown) { print "</para>"; } 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 { -- 2.5.1
WARNING: multiple messages have this Message-ID (diff)
From: Daniel Vetter <daniel.vetter@ffwll.ch> To: DRI Development <dri-devel@lists.freedesktop.org> Cc: Michal Marek <mmarek@suse.cz>, Herbert Xu <herbert@gondor.apana.org.au>, Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>, Jonathan Corbet <corbet@lwn.net>, Stephan Mueller <smueller@chronox.de>, Daniel Vetter <daniel.vetter@ffwll.ch>, Intel Graphics Development <intel-gfx@lists.freedesktop.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Graham Whaley <graham.whaley@linux.intel.com>, Laurent Pinchart <laurent.pinchart@ideasonboard.com> Subject: [PATCH 3/5] scripts/kernel-doc: Improve Markdown results Date: Wed, 25 Nov 2015 18:07:57 +0100 [thread overview] Message-ID: <1448471279-19748-4-git-send-email-daniel.vetter@ffwll.ch> (raw) In-Reply-To: <1448471279-19748-1-git-send-email-daniel.vetter@ffwll.ch> From: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Using pandoc as the Markdown engine cause some minor side effects as pandoc includes main <para> 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: <something>..</something> <para>...</para> As kernel-doc was already including a <para> tag, it causes the presence of double <para> tags (<para><para>), 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 <para> 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 <para> is not needed, which is the <refpurpose> content. For those cases, we're using a $output_markdown_nopara = 1 control var. Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Herbert Xu <herbert@gondor.apana.org.au> Cc: Stephan Mueller <smueller@chronox.de> Cc: Michal Marek <mmarek@suse.cz> Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx <intel-gfx@lists.freedesktop.org> Cc: dri-devel <dri-devel@lists.freedesktop.org> Cc: Graham Whaley <graham.whaley@linux.intel.com> --- 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 <para></para>, we should remove them. - $content =~ s:\A\s*<para>\s*\n(.*)\n</para>\Z$:$1:egsm; + if ($output_markdown_nopara) { + # pandoc insists in adding Main <para></para>, sometimes we + # want to remove them. + $content =~ s:\A\s*<para>\s*\n(.*)\n</para>\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 "<programlisting>\n" unless $use_markdown; $output_preformatted = 1; - } else { + } elsif (! $use_markdown) { print "<para>\n"; } output_highlight($args{'sections'}{$section}); @@ -1043,7 +1047,7 @@ sub output_section_xml(%) { if ($section =~ m/EXAMPLE/i) { print "</programlisting>\n" unless $use_markdown; print "</informalexample>\n"; - } else { + } elsif (! $use_markdown) { print "</para>\n"; } print "</refsect1>\n"; @@ -1075,7 +1079,9 @@ sub output_function_xml(%) { print " <refname>" . $args{'function'} . "</refname>\n"; print " <refpurpose>\n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " </refpurpose>\n"; print "</refnamediv>\n"; @@ -1113,10 +1119,12 @@ sub output_function_xml(%) { $parameter_name =~ s/\[.*//; print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n"; - print " <listitem>\n <para>\n"; + print " <listitem>\n"; + print " <para>\n" unless $use_markdown; $lineprefix=" "; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para>\n </listitem>\n </varlistentry>\n"; + print " </para>\n" unless $use_markdown; + print " </listitem>\n </varlistentry>\n"; } print " </variablelist>\n"; } else { @@ -1152,7 +1160,9 @@ sub output_struct_xml(%) { print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n"; print " <refpurpose>\n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " </refpurpose>\n"; print "</refnamediv>\n"; @@ -1205,9 +1215,11 @@ sub output_struct_xml(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print " <varlistentry>"; print " <term>$parameter</term>\n"; - print " <listitem><para>\n"; + print " <listitem>\n"; + print " <para>\n" unless $use_markdown; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para></listitem>\n"; + print " </para>\n" unless $use_markdown; + print " </listitem>\n"; print " </varlistentry>\n"; } print " </variablelist>\n"; @@ -1246,7 +1258,9 @@ sub output_enum_xml(%) { print " <refname>enum " . $args{'enum'} . "</refname>\n"; print " <refpurpose>\n"; print " "; + $output_markdown_nopara = 1; output_highlight ($args{'purpose'}); + $output_markdown_nopara = 0; print " </refpurpose>\n"; print "</refnamediv>\n"; @@ -1276,9 +1290,11 @@ sub output_enum_xml(%) { print " <varlistentry>"; print " <term>$parameter</term>\n"; - print " <listitem><para>\n"; + print " <listitem>\n"; + print " <para>\n" unless $use_markdown; output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para></listitem>\n"; + print " </para>\n" unless $use_markdown; + print " </listitem>\n"; print " </varlistentry>\n"; } print " </variablelist>\n"; @@ -1344,14 +1360,14 @@ sub output_blockhead_xml(%) { if ($section =~ m/EXAMPLE/i) { print "<example><para>\n"; $output_preformatted = 1; - } else { + } elsif (! $use_markdown) { print "<para>\n"; } output_highlight($args{'sections'}{$section}); $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "</para></example>\n"; - } else { + } elsif (! $use_markdown) { print "</para>"; } 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 { -- 2.5.1 _______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2015-11-25 17:08 UTC|newest] Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top 2015-11-25 17:07 [PATCH 0/5] Better markup for GPU DocBook Daniel Vetter 2015-11-25 17:07 ` [PATCH 1/5] drm/doc: Convert to markdown Daniel Vetter 2015-11-25 17:07 ` Daniel Vetter 2015-11-25 17:07 ` [PATCH 2/5] scripts/kernel-doc: Adding infrastructure for markdown support Daniel Vetter 2015-11-25 17:07 ` Daniel Vetter 2015-11-25 17:07 ` Daniel Vetter [this message] 2015-11-25 17:07 ` [PATCH 3/5] scripts/kernel-doc: Improve Markdown results Daniel Vetter 2015-11-25 17:07 ` [PATCH 4/5] scripts/kernel-doc: Use asciidoc instead of markdown Daniel Vetter 2015-12-02 9:34 ` [PATCH] " Daniel Vetter 2015-12-02 13:33 ` Jani Nikula 2015-12-02 15:32 ` Daniel Vetter 2015-12-02 15:57 ` Jani Nikula 2015-11-25 17:07 ` [PATCH 5/5] drm: Enable markdown^Wasciidoc for gpu.tmpl Daniel Vetter 2015-12-11 22:12 ` Jonathan Corbet 2015-12-12 11:13 ` Daniel Vetter 2016-01-12 1:12 ` Jonathan Corbet 2016-01-12 6:15 ` Jani Nikula 2016-01-12 8:34 ` Daniel Vetter 2016-01-12 11:06 ` Graham Whaley 2016-01-12 17:43 ` Daniel Vetter 2016-01-14 20:03 ` Jani Nikula 2016-01-14 20:18 ` Jonathan Corbet 2016-01-15 7:14 ` Jani Nikula
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=1448471279-19748-4-git-send-email-daniel.vetter@ffwll.ch \ --to=daniel.vetter@ffwll.ch \ --cc=corbet@lwn.net \ --cc=danilo.cesar@collabora.co.uk \ --cc=dri-devel@lists.freedesktop.org \ --cc=graham.whaley@linux.intel.com \ --cc=herbert@gondor.apana.org.au \ --cc=intel-gfx@lists.freedesktop.org \ --cc=laurent.pinchart@ideasonboard.com \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=mmarek@suse.cz \ --cc=rdunlap@infradead.org \ --cc=smueller@chronox.de \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.