diff mbox

[v2,2/4] scripts/kernel-doc: Replacing highlights hash by an array

Message ID 1438112718-12168-3-git-send-email-danilo.cesar@collabora.co.uk
State New, archived
Headers show

Commit Message

Danilo Cesar Lemes de Paula July 28, 2015, 7:45 p.m. UTC
The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted on Perl. It generates
faulty DocBook entries like:
	- @<function>device_for_each_child</function>

We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight won't change.

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>
---
 Changelog:
	v2: No changes

 scripts/kernel-doc | 104 ++++++++++++++++++++++++++++++-----------------------
 1 file changed, 60 insertions(+), 44 deletions(-)

Comments

Mauro Carvalho Chehab Nov. 17, 2015, 10:40 a.m. UTC | #1
Hi Danilo,

Em Tue, 28 Jul 2015 16:45:16 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> escreveu:

> The "highlight" code is very sensible to the order of the hash keys,
> but the order of the keys cannot be predicted on Perl. It generates
> faulty DocBook entries like:
> 	- @<function>device_for_each_child</function>
> 
> We should use an array for that job, so we can guarantee that the order
> of the regex execution on dohighlight won't change.

...

> @@ -2587,9 +2601,11 @@ $kernelversion = get_kernel_version();
>  
>  # generate a sequence of code that will splice in highlighting information
>  # using the s// operator.
> -foreach my $pattern (keys %highlights) {
> -#   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
> -    $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
> +foreach my $k (keys @highlights) {

The above causes some versions of perl to fail, as keys expect a
hash argument:

Execution of .//scripts/kernel-doc aborted due to compilation errors.
Type of arg 1 to keys must be hash (not private array) at .//scripts/kernel-doc line 2714, near "@highlights) "

This is happening at linuxtv.org server, with runs perl version 5.10.1.

I had to revert this patch in order to be able to keep building the
documentation of the media kABI on our server.

Regards,
Mauro
Jonathan Corbet Nov. 17, 2015, 2:44 p.m. UTC | #2
On Tue, 17 Nov 2015 08:40:46 -0200
Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:

> The above causes some versions of perl to fail, as keys expect a
> hash argument:
> 
> Execution of .//scripts/kernel-doc aborted due to compilation errors.
> Type of arg 1 to keys must be hash (not private array) at .//scripts/kernel-doc line 2714, near "@highlights) "
> 
> This is happening at linuxtv.org server, with runs perl version 5.10.1.

OK, that's not good.  But I'm not quite sure what to do about it.

Perl 5.10.1 is a little over six years old.  Nobody else has complained
(yet) about this problem.  So it might be best to "fix" this with a
minimum version added to the Changes file.

Or maybe we need to revert the patch.

So I'm far from a Perl expert, so I have no clue what the minimum version
would be if we were to say "5.10.1 is too old."  I don't suppose anybody
out there knows?

Thanks,

jon
Danilo Cesar Lemes de Paula Nov. 17, 2015, 3:48 p.m. UTC | #3
On 17-11-2015 13:29, Mauro Carvalho Chehab wrote:
> Em Tue, 17 Nov 2015 07:44:31 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
>> On Tue, 17 Nov 2015 08:40:46 -0200
>> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
>>
>>> The above causes some versions of perl to fail, as keys expect a
>>> hash argument:
>>>
>>> Execution of .//scripts/kernel-doc aborted due to compilation errors.
>>> Type of arg 1 to keys must be hash (not private array) at .//scripts/kernel-doc line 2714, near "@highlights) "
>>>
>>> This is happening at linuxtv.org server, with runs perl version 5.10.1.
>>
>> OK, that's not good.  But I'm not quite sure what to do about it.
>>
>> Perl 5.10.1 is a little over six years old.  Nobody else has complained
>> (yet) about this problem.  So it might be best to "fix" this with a
>> minimum version added to the Changes file.
>>
>> Or maybe we need to revert the patch.
>>
>> So I'm far from a Perl expert, so I have no clue what the minimum version
>> would be if we were to say "5.10.1 is too old."  I don't suppose anybody
>> out there knows?
> 
> I'm also not a Perl expert, and never saw before the usage of "keys" on
> an array. Yet, according with:
> 	http://perldoc.perl.org/functions/keys.html
> 
> "in Perl 5.12 or later only, the indices of an array"
> 
> If so, then maybe we could replace:
> 	foreach my $k (keys @highlights)
> 
> by a more C style variant, with all versions of perl 5:
> 	for (my $k = 0; $k < @highlights; $k++) {
> 
> The enclosed patch should do the trick. I tested it with perl 5.10 and 
> perl 5.22 it worked fine with both versions.

I'm Not a perl guru myself either =/.

But thanks for fixing it Mauro!

Danilo
Jonathan Corbet Nov. 18, 2015, 12:21 a.m. UTC | #4
On Tue, 17 Nov 2015 13:29:49 -0200
Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:

> The enclosed patch should do the trick. I tested it with perl 5.10 and 
> perl 5.22 it worked fine with both versions.

Indeed it seems to work - thanks!  Applied to the docs tree, I'll get it
upstream before too long.

jon
Mauro Carvalho Chehab Nov. 18, 2015, 9:14 a.m. UTC | #5
Em Tue, 17 Nov 2015 17:21:32 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 17 Nov 2015 13:29:49 -0200
> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> 
> > The enclosed patch should do the trick. I tested it with perl 5.10 and 
> > perl 5.22 it worked fine with both versions.
> 
> Indeed it seems to work - thanks!  Applied to the docs tree, I'll get it
> upstream before too long.

Thanks, Jon!

Regards,
Mauro
diff mbox

Patch

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9922e66..a38a69a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -182,59 +182,73 @@  my $type_env = '(\$\w+)';
 #  One for each output format
 
 # these work fairly well
-my %highlights_html = ( $type_constant, "<i>\$1</i>",
-			$type_func, "<b>\$1</b>",
-			$type_struct_xml, "<i>\$1</i>",
-			$type_env, "<b><i>\$1</i></b>",
-			$type_param, "<tt><b>\$1</b></tt>" );
+my @highlights_html = (
+                       [$type_constant, "<i>\$1</i>"],
+                       [$type_func, "<b>\$1</b>"],
+                       [$type_struct_xml, "<i>\$1</i>"],
+                       [$type_env, "<b><i>\$1</i></b>"],
+                       [$type_param, "<tt><b>\$1</b></tt>"]
+                      );
 my $local_lt = "\\\\\\\\lt:";
 my $local_gt = "\\\\\\\\gt:";
 my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
 
 # html version 5
-my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
-			$type_func, "<span class=\"func\">\$1</span>",
-			$type_struct_xml, "<span class=\"struct\">\$1</span>",
-			$type_env, "<span class=\"env\">\$1</span>",
-			$type_param, "<span class=\"param\">\$1</span>" );
+my @highlights_html5 = (
+                        [$type_constant, "<span class=\"const\">\$1</span>"],
+                        [$type_func, "<span class=\"func\">\$1</span>"],
+                        [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
+                        [$type_env, "<span class=\"env\">\$1</span>"],
+                        [$type_param, "<span class=\"param\">\$1</span>]"]
+		       );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 
 # XML, docbook format
-my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
-			$type_constant, "<constant>\$1</constant>",
-			$type_func, "<function>\$1</function>",
-			$type_struct_xml, "<structname>\$1</structname>",
-			$type_env, "<envar>\$1</envar>",
-			$type_param, "<parameter>\$1</parameter>" );
+my @highlights_xml = (
+                      ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
+                      [$type_constant, "<constant>\$1</constant>"],
+                      [$type_struct_xml, "<structname>\$1</structname>"],
+                      [$type_param, "<parameter>\$1</parameter>"],
+                      [$type_func, "<function>\$1</function>"],
+                      [$type_env, "<envar>\$1</envar>"]
+		     );
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
 
 # gnome, docbook format
-my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
-			 $type_func, "<function>\$1</function>",
-			 $type_struct, "<structname>\$1</structname>",
-			 $type_env, "<envar>\$1</envar>",
-			 $type_param, "<parameter>\$1</parameter>" );
+my @highlights_gnome = (
+                        [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
+                        [$type_func, "<function>\$1</function>"],
+                        [$type_struct, "<structname>\$1</structname>"],
+                        [$type_env, "<envar>\$1</envar>"],
+                        [$type_param, "<parameter>\$1</parameter>" ]
+		       );
 my $blankline_gnome = "</para><para>\n";
 
 # these are pretty rough
-my %highlights_man = ( $type_constant, "\$1",
-		       $type_func, "\\\\fB\$1\\\\fP",
-		       $type_struct, "\\\\fI\$1\\\\fP",
-		       $type_param, "\\\\fI\$1\\\\fP" );
+my @highlights_man = (
+                      [$type_constant, "\$1"],
+                      [$type_func, "\\\\fB\$1\\\\fP"],
+                      [$type_struct, "\\\\fI\$1\\\\fP"],
+                      [$type_param, "\\\\fI\$1\\\\fP"]
+		     );
 my $blankline_man = "";
 
 # text-mode
-my %highlights_text = ( $type_constant, "\$1",
-			$type_func, "\$1",
-			$type_struct, "\$1",
-			$type_param, "\$1" );
+my @highlights_text = (
+                       [$type_constant, "\$1"],
+                       [$type_func, "\$1"],
+                       [$type_struct, "\$1"],
+                       [$type_param, "\$1"]
+		      );
 my $blankline_text = "";
 
 # list mode
-my %highlights_list = ( $type_constant, "\$1",
-			$type_func, "\$1",
-			$type_struct, "\$1",
-			$type_param, "\$1" );
+my @highlights_list = (
+                       [$type_constant, "\$1"],
+                       [$type_func, "\$1"],
+                       [$type_struct, "\$1"],
+                       [$type_param, "\$1"]
+		      );
 my $blankline_list = "";
 
 # read arguments
@@ -249,7 +263,7 @@  my $verbose = 0;
 my $output_mode = "man";
 my $output_preformatted = 0;
 my $no_doc_sections = 0;
-my %highlights = %highlights_man;
+my @highlights = @highlights_man;
 my $blankline = $blankline_man;
 my $modulename = "Kernel API";
 my $function_only = 0;
@@ -328,31 +342,31 @@  while ($ARGV[0] =~ m/^-(.*)/) {
     my $cmd = shift @ARGV;
     if ($cmd eq "-html") {
 	$output_mode = "html";
-	%highlights = %highlights_html;
+	@highlights = @highlights_html;
 	$blankline = $blankline_html;
     } elsif ($cmd eq "-html5") {
 	$output_mode = "html5";
-	%highlights = %highlights_html5;
+	@highlights = @highlights_html5;
 	$blankline = $blankline_html5;
     } elsif ($cmd eq "-man") {
 	$output_mode = "man";
-	%highlights = %highlights_man;
+	@highlights = @highlights_man;
 	$blankline = $blankline_man;
     } elsif ($cmd eq "-text") {
 	$output_mode = "text";
-	%highlights = %highlights_text;
+	@highlights = @highlights_text;
 	$blankline = $blankline_text;
     } elsif ($cmd eq "-docbook") {
 	$output_mode = "xml";
-	%highlights = %highlights_xml;
+	@highlights = @highlights_xml;
 	$blankline = $blankline_xml;
     } elsif ($cmd eq "-list") {
 	$output_mode = "list";
-	%highlights = %highlights_list;
+	@highlights = @highlights_list;
 	$blankline = $blankline_list;
     } elsif ($cmd eq "-gnome") {
 	$output_mode = "gnome";
-	%highlights = %highlights_gnome;
+	@highlights = @highlights_gnome;
 	$blankline = $blankline_gnome;
     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
 	$modulename = shift @ARGV;
@@ -2587,9 +2601,11 @@  $kernelversion = get_kernel_version();
 
 # generate a sequence of code that will splice in highlighting information
 # using the s// operator.
-foreach my $pattern (keys %highlights) {
-#   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
-    $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
+foreach my $k (keys @highlights) {
+    my $pattern = $highlights[$k][0];
+    my $result = $highlights[$k][1];
+#   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
+    $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
 }
 
 # Read the file that maps relative names to absolute names for