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(-)
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