Re: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

[Jani Nikula]

On Wed, 14 Feb 2018, Jonathan Corbet  wrote:
> It can be useful to put code snippets into kerneldoc comments; that can be
> done with the "::" operator at the end of a line like this::
>
>if (desperate)
>run_in_circles();
>
> The ".. code-block::" directive can also be used to this end.  kernel-doc
> currently fails to understand these literal blocks and applies its normal
> markup to them, which is then treated as literal by sphinx.  The result is
> unsightly markup instead of a useful code snippet.
>
> Apply a hack to the output code to recognize literal blocks and avoid
> performing any special markup on them.  It's ugly, but that means it fits
> in well with the rest of the script.

With emphasis on part (d) of the reviewer's statement of oversight,

Reviewed-by: Jani Nikula 

>
> Signed-off-by: Jonathan Corbet 
> ---
>  scripts/kernel-doc | 69 
> ++
>  1 file changed, 64 insertions(+), 5 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fb8fbdb25036..cbe864e72a2f 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -748,14 +748,73 @@ sub output_blockhead_rst(%) {
>  }
>  }
>  
> -sub output_highlight_rst {
> -my $contents = join "\n",@_;
> -my $line;
> -
> +#
> +# Apply the RST highlights to a sub-block of text.
> +#   
> +sub highlight_block($) {
> +# The dohighlight kludge requires the text be called $contents
> +my $contents = shift;
>  eval $dohighlight;
>  die $@ if $@;
> +return $contents;
> +}
>  
> -foreach $line (split "\n", $contents) {
> +#
> +# Regexes used only here.
> +#
> +my $sphinx_literal = '^[^.].*::$';
> +my $sphinx_cblock = '^\.\.\ +code-block::';
> +
> +sub output_highlight_rst {
> +my $input = join "\n",@_;
> +my $output = "";
> +my $line;
> +my $in_literal = 0;
> +my $litprefix;
> +my $block = "";
> +
> +foreach $line (split "\n",$input) {
> + #
> + # If we're in a literal block, see if we should drop out
> + # of it.  Otherwise pass the line straight through unmunged.
> + #
> + if ($in_literal) {
> + if (! ($line =~ /^\s*$/)) {
> + #
> + # If this is the first non-blank line in a literal
> + # block we need to figure out what the proper indent is.
> + #
> + if ($litprefix eq "") {
> + $line =~ /^(\s*)/;
> + $litprefix = '^' . $1;
> + $output .= $line . "\n";
> + } elsif (! ($line =~ /$litprefix/)) {
> + $in_literal = 0;
> + } else {
> + $output .= $line . "\n";
> + }
> + } else {
> + $output .= $line . "\n";
> + }
> + }
> + #
> + # Not in a literal block (or just dropped out)
> + #
> + if (! $in_literal) {
> + $block .= $line . "\n";
> + if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
> + $in_literal = 1;
> + $litprefix = "";
> + $output .= highlight_block($block);
> + $block = ""
> + }
> + }
> +}
> +
> +if ($block) {
> + $output .= highlight_block($block);
> +}
> +foreach $line (split "\n", $output) {
>   print $lineprefix . $line . "\n";
>  }
>  }

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

[Jonathan Corbet]

It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

   if (desperate)
   run_in_circles();

The ".. code-block::" directive can also be used to this end.  kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx.  The result is
unsightly markup instead of a useful code snippet.

Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them.  It's ugly, but that means it fits
in well with the rest of the script.

Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 69 ++
 1 file changed, 64 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fb8fbdb25036..cbe864e72a2f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -748,14 +748,73 @@ sub output_blockhead_rst(%) {
 }
 }
 
-sub output_highlight_rst {
-my $contents = join "\n",@_;
-my $line;
-
+#
+# Apply the RST highlights to a sub-block of text.
+#   
+sub highlight_block($) {
+# The dohighlight kludge requires the text be called $contents
+my $contents = shift;
 eval $dohighlight;
 die $@ if $@;
+return $contents;
+}
 
-foreach $line (split "\n", $contents) {
+#
+# Regexes used only here.
+#
+my $sphinx_literal = '^[^.].*::$';
+my $sphinx_cblock = '^\.\.\ +code-block::';
+
+sub output_highlight_rst {
+my $input = join "\n",@_;
+my $output = "";
+my $line;
+my $in_literal = 0;
+my $litprefix;
+my $block = "";
+
+foreach $line (split "\n",$input) {
+   #
+   # If we're in a literal block, see if we should drop out
+   # of it.  Otherwise pass the line straight through unmunged.
+   #
+   if ($in_literal) {
+   if (! ($line =~ /^\s*$/)) {
+   #
+   # If this is the first non-blank line in a literal
+   # block we need to figure out what the proper indent is.
+   #
+   if ($litprefix eq "") {
+   $line =~ /^(\s*)/;
+   $litprefix = '^' . $1;
+   $output .= $line . "\n";
+   } elsif (! ($line =~ /$litprefix/)) {
+   $in_literal = 0;
+   } else {
+   $output .= $line . "\n";
+   }
+   } else {
+   $output .= $line . "\n";
+   }
+   }
+   #
+   # Not in a literal block (or just dropped out)
+   #
+   if (! $in_literal) {
+   $block .= $line . "\n";
+   if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
+   $in_literal = 1;
+   $litprefix = "";
+   $output .= highlight_block($block);
+   $block = ""
+   }
+   }
+}
+
+if ($block) {
+   $output .= highlight_block($block);
+}
+foreach $line (split "\n", $output) {
print $lineprefix . $line . "\n";
 }
 }
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

[Markus Heiser]

> Am 07.02.2018 um 18:26 schrieb Jonathan Corbet :
> 
> It can be useful to put code snippets into kerneldoc comments; that can be
> done with the "::" operator at the end of a line like this::
> 
>  if (desperate)
>  run_in_circles();
> 
> kernel-doc currently fails to understand these literal blocks and applies
> its normal markup to them, which is then treated as literal by sphinx.  The
> result is unsightly markup instead of a useful code snippet.
> 
> Apply a hack to the output code to recognize literal blocks and avoid
> performing any special markup on them.  It's ugly, but that means it fits
> in well with the rest of the script.
> 
> Signed-off-by: Jonathan Corbet 


[...]

FYI; added similar patch to python version of kernel-doc:

 https://github.com/return42/linuxdoc/commit/3205b8a68

may you like to add regexpr for code-block directive to your patch (jani 
mentioned already).

-- Markus --


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

[Jonathan Corbet]

It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

   if (desperate)
   run_in_circles();

kernel-doc currently fails to understand these literal blocks and applies
its normal markup to them, which is then treated as literal by sphinx.  The
result is unsightly markup instead of a useful code snippet.

Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them.  It's ugly, but that means it fits
in well with the rest of the script.

Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 55 +-
 1 file changed, 50 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c6c9370a1e49..c984f82cb897 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -748,14 +748,59 @@ sub output_blockhead_rst(%) {
 }
 }
 
-sub output_highlight_rst {
-my $contents = join "\n",@_;
-my $line;
-
+#
+# Apply the RST highlights to a sub-block of text.
+#   
+sub highlight_block($) {
+# The dohighlight kludge requires the text be called $contents
+my $contents = shift;
 eval $dohighlight;
 die $@ if $@;
+return $contents;
+}
 
-foreach $line (split "\n", $contents) {
+sub output_highlight_rst {
+my $input = join "\n",@_;
+my $output = "";
+my $line;
+my $in_literal = 0;
+my $litprefix;
+my $block = "";
+
+# The "dohighlight" hack requires that the data be called "$contents"
+foreach $line (split "\n",$input) {
+   #
+   # If we're in a literal block, see if we should drop out
+   # of it.  Otherwise pass the line straight through unmunged.
+   #
+   if ($in_literal) {
+   if (! ($line =~ /$litprefix/ || $line =~ /^\s*$/)) {
+   $in_literal = 0;
+   }
+   else {
+   $output .= $line . "\n";
+   }
+   }
+   #
+   # Not in a literal block (or just dropped out)
+   #
+   if (! $in_literal) {
+   $block .= $line . "\n";
+   if ($line =~ /^[^.].*::$/) {
+   $in_literal = 1;
+   # Note current indentation - we'll go as long as it's deeper.
+   $line =~ /^(\s*)/;
+   $litprefix = '^' . $1 . ' ';
+   $output .= highlight_block($block);
+   $block = ""
+   }
+   }
+}
+
+if ($block) {
+   $output .= highlight_block($block);
+}
+foreach $line (split "\n", $output) {
print $lineprefix . $line . "\n";
 }
 }
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html