[PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array
Danilo Cesar Lemes de Paula
danilo.cesar at collabora.co.uk
Mon Sep 7 13:01:59 PDT 2015
The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
- @<function>device_for_each_child</function>
Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.
Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar at collabora.co.uk>
Cc: Randy Dunlap <rdunlap at infradead.org>
Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
Cc: Jonathan Corbet <corbet at lwn.net>
Cc: Herbert Xu <herbert at gondor.apana.org.au>
Cc: Stephan Mueller <smueller at chronox.de>
Cc: Michal Marek <mmarek at suse.cz>
Cc: linux-kernel at vger.kernel.org
Cc: linux-doc at vger.kernel.org
Cc: intel-gfx <intel-gfx at lists.freedesktop.org>
Cc: dri-devel <dri-devel at lists.freedesktop.org>
---
scripts/kernel-doc | 104 ++++++++++++++++++++++++++++++-----------------------
1 file changed, 60 insertions(+), 44 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9a08fb5..0affe4f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -206,59 +206,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
@@ -273,7 +287,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;
@@ -374,31 +388,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;
@@ -2671,9 +2685,11 @@ $kernelversion = get_kernel_version();
# generate a sequence of code that will splice in highlighting information
# using the s// operator.
-foreach my $pattern (sort 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
--
2.4.3
More information about the dri-devel
mailing list