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