1 #!/usr/bin/env perl 1 #!/usr/bin/env perl
2 # SPDX-License-Identifier: GPL-2.0 2 # SPDX-License-Identifier: GPL-2.0
3 # 3 #
4 # Treewide grep for references to files under 4 # Treewide grep for references to files under Documentation, and report
5 # non-existing files in stderr. 5 # non-existing files in stderr.
6 6
7 use warnings; 7 use warnings;
8 use strict; 8 use strict;
9 use Getopt::Long qw(:config no_auto_abbrev); 9 use Getopt::Long qw(:config no_auto_abbrev);
10 10
11 # NOTE: only add things here when the file was <<
12 # to mention a past documentation file, for ex <<
13 # the original work. <<
14 my %false_positives = ( <<
15 "Documentation/scsi/scsi_mid_low_api.r <<
16 "drivers/vhost/vhost.c" => "Documentat <<
17 ); <<
18 <<
19 my $scriptname = $0; 11 my $scriptname = $0;
20 $scriptname =~ s,.*/([^/]+/),$1,; 12 $scriptname =~ s,.*/([^/]+/),$1,;
21 13
22 # Parse arguments 14 # Parse arguments
23 my $help = 0; 15 my $help = 0;
24 my $fix = 0; 16 my $fix = 0;
25 my $warn = 0; <<
26 <<
27 if (! -e ".git") { <<
28 printf "Warning: can't check if file e <<
29 exit 0; <<
30 } <<
31 17
32 GetOptions( 18 GetOptions(
33 'fix' => \$fix, 19 'fix' => \$fix,
34 'warn' => \$warn, <<
35 'h|help|usage' => \$help, 20 'h|help|usage' => \$help,
36 ); 21 );
37 22
38 if ($help != 0) { 23 if ($help != 0) {
39 print "$scriptname [--help] [--fix]\n"; 24 print "$scriptname [--help] [--fix]\n";
40 exit -1; 25 exit -1;
41 } 26 }
42 27
43 # Step 1: find broken references 28 # Step 1: find broken references
44 print "Finding broken references. This may tak 29 print "Finding broken references. This may take a while... " if ($fix);
45 30
46 my %broken_ref; 31 my %broken_ref;
47 32
48 my $doc_fix = 0; <<
49 <<
50 open IN, "git grep ':doc:\`' Documentation/|" <<
51 or die "Failed to run git grep"; <<
52 while (<IN>) { <<
53 next if (!m,^([^:]+):.*\:doc\:\`([^\`] <<
54 next if (m,sphinx/,); <<
55 <<
56 my $file = $1; <<
57 my $d = $1; <<
58 my $doc_ref = $2; <<
59 <<
60 my $f = $doc_ref; <<
61 <<
62 $d =~ s,(.*/).*,$1,; <<
63 $f =~ s,.*\<([^\>]+)\>,$1,; <<
64 <<
65 if ($f =~ m,^/,) { <<
66 $f = "$f.rst"; <<
67 $f =~ s,^/,Documentation/,; <<
68 } else { <<
69 $f = "$d$f.rst"; <<
70 } <<
71 <<
72 next if (grep -e, glob("$f")); <<
73 <<
74 if ($fix && !$doc_fix) { <<
75 print STDERR "\nWARNING: Curre <<
76 } <<
77 $doc_fix++; <<
78 <<
79 print STDERR "$file: :doc:`$doc_ref`\n <<
80 } <<
81 close IN; <<
82 <<
83 open IN, "git grep 'Documentation/'|" 33 open IN, "git grep 'Documentation/'|"
84 or die "Failed to run git grep"; 34 or die "Failed to run git grep";
85 while (<IN>) { 35 while (<IN>) {
86 next if (!m/^([^:]+):(.*)/); 36 next if (!m/^([^:]+):(.*)/);
87 37
88 my $f = $1; 38 my $f = $1;
89 my $ln = $2; 39 my $ln = $2;
90 40
91 # On linux-next, discard the Next/ dir <<
92 next if ($f =~ m,^Next/,); <<
93 <<
94 # Makefiles and scripts contain nasty 41 # Makefiles and scripts contain nasty expressions to parse docs
95 next if ($f =~ m/Makefile/ || $f =~ m/ 42 next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/);
96 43
97 # It doesn't make sense to parse hidde <<
98 next if ($f =~ m#/\.#); <<
99 <<
100 # Skip this script 44 # Skip this script
101 next if ($f eq $scriptname); 45 next if ($f eq $scriptname);
102 46
103 # Ignore the dir where documentation w <<
104 next if ($ln =~ m,\b(\S*)Documentation <<
105 <<
106 if ($ln =~ m,\b(\S*)(Documentation/[A- 47 if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) {
107 my $prefix = $1; 48 my $prefix = $1;
108 my $ref = $2; 49 my $ref = $2;
109 my $base = $2; 50 my $base = $2;
110 my $extra = $3; 51 my $extra = $3;
111 52
112 # some file references are lik 53 # some file references are like:
113 # /usr/src/linux/Documentation 54 # /usr/src/linux/Documentation/DMA-{API,mapping}.txt
114 # For now, ignore them 55 # For now, ignore them
115 next if ($extra =~ m/^{/); 56 next if ($extra =~ m/^{/);
116 57
117 # Remove footnotes at the end 58 # Remove footnotes at the end like:
118 # Documentation/devicetree/dt- 59 # Documentation/devicetree/dt-object-internal.txt[1]
119 $ref =~ s/(txt|rst)\[\d+]$/$1/ 60 $ref =~ s/(txt|rst)\[\d+]$/$1/;
120 61
121 # Remove ending ']' without an 62 # Remove ending ']' without any '['
122 $ref =~ s/\].*// if (!($ref =~ 63 $ref =~ s/\].*// if (!($ref =~ m/\[/));
123 64
124 # Remove puntuation marks at t 65 # Remove puntuation marks at the end
125 $ref =~ s/[\,\.]+$//; 66 $ref =~ s/[\,\.]+$//;
126 67
127 my $fulref = "$prefix$ref"; 68 my $fulref = "$prefix$ref";
128 69
129 $fulref =~ s/^(\<file|ref)://; 70 $fulref =~ s/^(\<file|ref)://;
130 $fulref =~ s/^[\'\`]+//; 71 $fulref =~ s/^[\'\`]+//;
131 $fulref =~ s,^\$\(.*\)/,,; 72 $fulref =~ s,^\$\(.*\)/,,;
132 $base =~ s,.*/,,; 73 $base =~ s,.*/,,;
133 74
134 # Remove URL false-positives 75 # Remove URL false-positives
135 next if ($fulref =~ m/^http/); 76 next if ($fulref =~ m/^http/);
136 77
137 # Remove sched-pelt false-posi 78 # Remove sched-pelt false-positive
138 next if ($fulref =~ m,^Documen 79 next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
139 80
140 # Discard some build examples !! 81 # Discard some build examples from Documentation/target/tcm_mod_builder.txt
141 next if ($fulref =~ m,mnt/sdb/ 82 next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
142 83
143 # Check if exists, evaluating 84 # Check if exists, evaluating wildcards
144 next if (grep -e, glob("$ref $ 85 next if (grep -e, glob("$ref $fulref"));
145 86
146 # Accept relative Documentatio 87 # Accept relative Documentation patches for tools/
147 if ($f =~ m/tools/) { 88 if ($f =~ m/tools/) {
148 my $path = $f; 89 my $path = $f;
149 $path =~ s,(.*)/.*,$1, 90 $path =~ s,(.*)/.*,$1,;
150 $path =~ s,testing/sel !! 91 next if (grep -e, glob("$path/$ref $path/$fulref"));
151 next if (grep -e, glob <<
152 } <<
153 <<
154 # Discard known false-positive <<
155 if (defined($false_positives{$ <<
156 next if ($false_positi <<
157 } 92 }
158 93
159 if ($fix) { 94 if ($fix) {
160 if (!($ref =~ m/(scrip 95 if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
161 $broken_ref{$r 96 $broken_ref{$ref}++;
162 } 97 }
163 } elsif ($warn) { <<
164 print STDERR "Warning: <<
165 } else { 98 } else {
166 print STDERR "$f: $ful 99 print STDERR "$f: $fulref\n";
167 } 100 }
168 } 101 }
169 } 102 }
170 close IN; <<
171 103
172 exit 0 if (!$fix); 104 exit 0 if (!$fix);
173 105
174 # Step 2: Seek for file name alternatives 106 # Step 2: Seek for file name alternatives
175 print "Auto-fixing broken references. Please d 107 print "Auto-fixing broken references. Please double-check the results\n";
176 108
177 foreach my $ref (keys %broken_ref) { 109 foreach my $ref (keys %broken_ref) {
178 my $new =$ref; 110 my $new =$ref;
179 111
180 my $basedir = "."; <<
181 # On translations, only seek inside th <<
182 $basedir = $1 if ($ref =~ m,(Document <<
183 <<
184 # get just the basename 112 # get just the basename
185 $new =~ s,.*/,,; 113 $new =~ s,.*/,,;
186 114
187 my $f=""; 115 my $f="";
188 116
189 # usual reason for breakage: DT file m 117 # usual reason for breakage: DT file moved around
190 if ($ref =~ /devicetree/) { 118 if ($ref =~ /devicetree/) {
191 # usual reason for breakage: D !! 119 my $search = $new;
192 if (!$f) { !! 120 $search =~ s,^.*/,,;
193 my $new_ref = $ref; !! 121 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
194 $new_ref =~ s/\.txt$/. <<
195 $f=$new_ref if (-f $ne <<
196 } <<
197 <<
198 if (!$f) { 122 if (!$f) {
199 my $search = $new; !! 123 # Manufacturer name may have changed
200 $search =~ s,^.*/,,; !! 124 $search =~ s/^.*,//;
201 $f = qx(find Documenta 125 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
202 if (!$f) { <<
203 # Manufacturer <<
204 $search =~ s/^ <<
205 $f = qx(find D <<
206 } <<
207 } 126 }
208 } 127 }
209 128
210 # usual reason for breakage: file rena 129 # usual reason for breakage: file renamed to .rst
211 if (!$f) { 130 if (!$f) {
212 $new =~ s/\.txt$/.rst/; 131 $new =~ s/\.txt$/.rst/;
213 $f=qx(find $basedir -iname $ne !! 132 $f=qx(find . -iname $new) if ($new);
214 } 133 }
215 134
216 # usual reason for breakage: use dash 135 # usual reason for breakage: use dash or underline
217 if (!$f) { 136 if (!$f) {
218 $new =~ s/[-_]/[-_]/g; 137 $new =~ s/[-_]/[-_]/g;
219 $f=qx(find $basedir -iname $ne !! 138 $f=qx(find . -iname $new) if ($new);
220 } 139 }
221 140
222 # Wild guess: seek for the same name o 141 # Wild guess: seek for the same name on another place
223 if (!$f) { 142 if (!$f) {
224 $f = qx(find $basedir -iname $ !! 143 $f = qx(find . -iname $new) if ($new);
225 } 144 }
226 145
227 my @find = split /\s+/, $f; 146 my @find = split /\s+/, $f;
228 147
229 if (!$f) { 148 if (!$f) {
230 print STDERR "ERROR: Didn't fi 149 print STDERR "ERROR: Didn't find a replacement for $ref\n";
231 } elsif (scalar(@find) > 1) { 150 } elsif (scalar(@find) > 1) {
232 print STDERR "WARNING: Won't a 151 print STDERR "WARNING: Won't auto-replace, as found multiple files close to $ref:\n";
233 foreach my $j (@find) { 152 foreach my $j (@find) {
234 $j =~ s,^./,,; 153 $j =~ s,^./,,;
235 print STDERR " $j\n 154 print STDERR " $j\n";
236 } 155 }
237 } else { 156 } else {
238 $f = $find[0]; 157 $f = $find[0];
239 $f =~ s,^./,,; 158 $f =~ s,^./,,;
240 print "INFO: Replacing $ref to 159 print "INFO: Replacing $ref to $f\n";
241 foreach my $j (qx(git grep -l 160 foreach my $j (qx(git grep -l $ref)) {
242 qx(sed "s\@$ref\@$f\@g 161 qx(sed "s\@$ref\@$f\@g" -i $j);
243 } 162 }
244 } 163 }
245 } 164 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.