Skip to content

Commit

Permalink
scripts/kernel-doc: Replacing highlights hash by an array
Browse files Browse the repository at this point in the history 
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.

[jc: I think this is kind of papering around the real problem, that people
 are saying @function() when "function" is not a parameter.  But this makes
 things better than they were before, so...]

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
  • Loading branch information
Danilo Cesar Lemes de Paula authored and Jonathan Corbet committed Sep 13, 2015
1 parent 1766649 commit 4d73270
Showing 1 changed file with 60 additions and 44 deletions.
104 changes: 60 additions & 44 deletions scripts/kernel-doc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -2672,9 +2686,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
Expand Down

0 comments on commit 4d73270

Please sign in to comment.