Merge tag 'docs-for-linus' of git://git.lwn.net/linux

Pull documentation update from Jon Corbet:
 "There is a nice new document from Neil on how pathname lookups work
  and some new CAN driver documentation.  Beyond that, we have
  kernel-doc fixes, a bit more work to support reproducible builds, and
  the usual collection of small fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits)
  Documentation: add new description of path-name lookup.
  Documentation/vm/slub.txt: document slabinfo-gnuplot.sh
  Doc: ABI/stable: Fix typo in ABI/stable
  doc: Clarify that nmi_watchdog param is for hardlockups
  Typo correction for description in gpio document.
  DocBook: Fix kernel-doc to be case-insensitive for private:
  kernel-docs.txt: update kernelnewbies reference
  Doc:kvm: Fix typo in Doc/virtual/kvm
  Documentation/Changes: Add bc in "Current Minimal Requirements" section
  Documentation/email-clients.txt: remove trailing whitespace
  DocBook: Use a fixed encoding for output
  MAINTAINERS: The docs tree has moved
  Docs/kernel-parameters: Add earlycon devicetree usage
  SubmittingPatches: make Subject examples match the de facto standard
  Documentation: gpio: mention that <function>-gpio has been deprecated
  Documentation: cgroups: just fix a few typos
  Documentation: Update kselftest.txt
  Documentation: DMA API: Be more explicit that nents is always the same
  Documentation: Update the default value of crashkernel low
  zram: update documentation
  ...

1 files changed, 68 insertions, 51 deletions

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0276d2b5eefe..125b906cd1d4 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;
@@ -1746,7 +1760,7 @@ sub output_declaration {
     my $func = "output_${functype}_$output_mode";
     if (($function_only==0) ||
         ( $function_only == 1 && defined($function_table{$name})) ||
-        ( $function_only == 2 && !defined($function_table{$name})))
+        ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
     {
         &$func(@_);
         $section_counter++;
@@ -1791,8 +1805,8 @@ sub dump_struct($$) {
         $nested = $1;
 
         # ignore members marked private:
-        $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-        $members =~ s/\/\*\s*private:.*//gos;
+        $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+        $members =~ s/\/\*\s*private:.*//gosi;
         # strip comments:
         $members =~ s/\/\*.*?\*\///gos;
         $nested =~ s/\/\*.*?\*\///gos;
@@ -2416,12 +2430,13 @@ sub process_file($) {
     my $descr;
     my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
+    my ($orig_file) = @_;
 
     if (defined($ENV{'SRCTREE'})) {
-        $file = "$ENV{'SRCTREE'}" . "/" . "@_";
+        $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
     }
     else {
-        $file = "@_";
+        $file = $orig_file;
     }
     if (defined($source_map{$file})) {
         $file = $source_map{$file};
@@ -2665,7 +2680,7 @@ sub process_file($) {
             print "<refentry>\n";
             print " <refnamediv>\n";
             print "  <refname>\n";
-            print "   ${file}\n";
+            print "   ${orig_file}\n";
             print "  </refname>\n";
             print "  <refpurpose>\n";
             print "   Document generation inconsistency\n";
@@ -2679,7 +2694,7 @@ sub process_file($) {
             print "   <para>\n";
             print "    The template for this document tried to insert\n";
             print "    the structured comment from the file\n";
-            print "    <filename>${file}</filename> at this point,\n";
+            print "    <filename>${orig_file}</filename> at this point,\n";
             print "    but none was found.\n";
             print "    This dummy section is inserted to allow\n";
             print "    generation to continue.\n";
@@ -2696,9 +2711,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