Re: [PATCH] scripts/kernel-doc: Improve Markdown results

From: Danilo Cesar Lemes de Paula
Date: Tue Sep 01 2015 - 13:58:34 EST

Next message: pinskia: "Re: [PATCHv2] ARM64: Add AT_ARM64_MIDR to the aux vector"
Previous message: Jeff Layton: "Re: [PATCH] fs: have flush_delayed_fput flush the workqueue job"
Next in thread: Jonathan Corbet: "Re: [PATCH] scripts/kernel-doc: Improve Markdown results"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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 <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@xxxxxxxxxxxxxxx>
> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Cc: Daniel Vetter <daniel.vetter@xxxxxxxx>
> Cc: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: Herbert Xu <herbert@xxxxxxxxxxxxxxxxxxx>
> Cc: Stephan Mueller <smueller@xxxxxxxxxx>
> Cc: Michal Marek <mmarek@xxxxxxx>
> Cc: linux-kernel@xxxxxxxxxxxxxxx
> Cc: linux-doc@xxxxxxxxxxxxxxx
> Cc: intel-gfx <intel-gfx@xxxxxxxxxxxxxxxxxxxxx>
> Cc: dri-devel <dri-devel@xxxxxxxxxxxxxxxxxxxxx>
> Cc: Graham Whaley <graham.whaley@xxxxxxxxxxxxxxx>
> ---
> 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 <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;
> }
> @@ -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 "<programlisting>\n" unless $use_markdown;
> $output_preformatted = 1;
> - } else {
> + } elsif (! $use_markdown) {
> print "<para>\n";
> }
> output_highlight($args{'sections'}{$section});
> @@ -1034,7 +1038,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";
> @@ -1066,7 +1070,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";
>
> @@ -1104,10 +1110,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 {
> @@ -1143,7 +1151,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";
>
> @@ -1196,9 +1206,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";
> @@ -1237,7 +1249,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";
>
> @@ -1267,9 +1281,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";
> @@ -1335,14 +1351,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'}) {
> @@ -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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

Next message: pinskia: "Re: [PATCHv2] ARM64: Add AT_ARM64_MIDR to the aux vector"
Previous message: Jeff Layton: "Re: [PATCH] fs: have flush_delayed_fput flush the workqueue job"
Next in thread: Jonathan Corbet: "Re: [PATCH] scripts/kernel-doc: Improve Markdown results"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]