Commit 4d732701 authored by Danilo Cesar Lemes de Paula's avatar Danilo Cesar Lemes de Paula Committed by Jonathan Corbet
Browse files

scripts/kernel-doc: Replacing highlights hash by an array 



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: default avatarDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 17666497

scripts/kernel-doc

+60 −44
Original line number Diff line number Diff line
@@ -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;
@@ -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

CRA Git | Maintained and supported by SUSTech CRA and CCSE