lkml.org 
[lkml]   [2015]   [Jul]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array
    Date
    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
    --
    2.4.6


    \
     
     \ /
      Last update: 2015-07-29 20:01    [W:4.960 / U:0.132 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site