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; | |
25 | ||
26 | GetOptions( | |
27 | 'fix' => \$fix, | |
28 | 'h|help|usage' => \$help, | |
29 | ); | |
30 | ||
31 | if ($help != 0) { | |
40fc3eb0 | 32 | print "$scriptname [--help] [--fix]\n"; |
d2656095 MCC |
33 | exit -1; |
34 | } | |
35 | ||
36 | # Step 1: find broken references | |
37 | print "Finding broken references. This may take a while... " if ($fix); | |
38 | ||
39 | my %broken_ref; | |
40 | ||
894ee5ff MCC |
41 | my $doc_fix = 0; |
42 | ||
43 | open IN, "git grep ':doc:\`' Documentation/|" | |
44 | or die "Failed to run git grep"; | |
45 | while (<IN>) { | |
46 | next if (!m,^([^:]+):.*\:doc\:\`([^\`]+)\`,); | |
47 | ||
48 | my $d = $1; | |
49 | my $doc_ref = $2; | |
50 | ||
51 | my $f = $doc_ref; | |
52 | ||
53 | $d =~ s,(.*/).*,$1,; | |
54 | $f =~ s,.*\<([^\>]+)\>,$1,; | |
55 | ||
56 | $f ="$d$f.rst"; | |
57 | ||
58 | next if (grep -e, glob("$f")); | |
59 | ||
60 | if ($fix && !$doc_fix) { | |
61 | print STDERR "\nWARNING: Currently, can't fix broken :doc:`` fields\n"; | |
62 | } | |
63 | $doc_fix++; | |
64 | ||
65 | print STDERR "$f: :doc:`$doc_ref`\n"; | |
66 | } | |
67 | close IN; | |
68 | ||
d2656095 MCC |
69 | open IN, "git grep 'Documentation/'|" |
70 | or die "Failed to run git grep"; | |
71 | while (<IN>) { | |
72 | next if (!m/^([^:]+):(.*)/); | |
73 | ||
74 | my $f = $1; | |
75 | my $ln = $2; | |
76 | ||
fe3e4b9c MCC |
77 | # On linux-next, discard the Next/ directory |
78 | next if ($f =~ m,^Next/,); | |
79 | ||
2d69708f MCC |
80 | # Makefiles and scripts contain nasty expressions to parse docs |
81 | next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/); | |
82 | ||
d2656095 MCC |
83 | # Skip this script |
84 | next if ($f eq $scriptname); | |
85 | ||
2d69708f | 86 | if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) { |
d2656095 MCC |
87 | my $prefix = $1; |
88 | my $ref = $2; | |
89 | my $base = $2; | |
2d69708f MCC |
90 | my $extra = $3; |
91 | ||
92 | # some file references are like: | |
93 | # /usr/src/linux/Documentation/DMA-{API,mapping}.txt | |
94 | # For now, ignore them | |
95 | next if ($extra =~ m/^{/); | |
96 | ||
97 | # Remove footnotes at the end like: | |
98 | # Documentation/devicetree/dt-object-internal.txt[1] | |
99 | $ref =~ s/(txt|rst)\[\d+]$/$1/; | |
100 | ||
101 | # Remove ending ']' without any '[' | |
102 | $ref =~ s/\].*// if (!($ref =~ m/\[/)); | |
d2656095 | 103 | |
2d69708f | 104 | # Remove puntuation marks at the end |
d2656095 MCC |
105 | $ref =~ s/[\,\.]+$//; |
106 | ||
107 | my $fulref = "$prefix$ref"; | |
108 | ||
109 | $fulref =~ s/^(\<file|ref)://; | |
110 | $fulref =~ s/^[\'\`]+//; | |
111 | $fulref =~ s,^\$\(.*\)/,,; | |
112 | $base =~ s,.*/,,; | |
113 | ||
114 | # Remove URL false-positives | |
115 | next if ($fulref =~ m/^http/); | |
116 | ||
5d395fa6 MCC |
117 | # Remove sched-pelt false-positive |
118 | next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,); | |
119 | ||
d25c0634 MCC |
120 | # Discard some build examples from Documentation/target/tcm_mod_builder.txt |
121 | next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,); | |
122 | ||
d2656095 MCC |
123 | # Check if exists, evaluating wildcards |
124 | next if (grep -e, glob("$ref $fulref")); | |
125 | ||
a78513c6 MCC |
126 | # Accept relative Documentation patches for tools/ |
127 | if ($f =~ m/tools/) { | |
128 | my $path = $f; | |
129 | $path =~ s,(.*)/.*,$1,; | |
130 | next if (grep -e, glob("$path/$ref $path/$fulref")); | |
131 | } | |
132 | ||
aeaacbfe MCC |
133 | # Discard known false-positives |
134 | if (defined($false_positives{$f})) { | |
135 | next if ($false_positives{$f} eq $fulref); | |
136 | } | |
137 | ||
d2656095 | 138 | if ($fix) { |
be600e5a | 139 | if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) { |
d2656095 MCC |
140 | $broken_ref{$ref}++; |
141 | } | |
142 | } else { | |
143 | print STDERR "$f: $fulref\n"; | |
144 | } | |
145 | } | |
146 | } | |
894ee5ff | 147 | close IN; |
d2656095 MCC |
148 | |
149 | exit 0 if (!$fix); | |
150 | ||
151 | # Step 2: Seek for file name alternatives | |
152 | print "Auto-fixing broken references. Please double-check the results\n"; | |
153 | ||
154 | foreach my $ref (keys %broken_ref) { | |
155 | my $new =$ref; | |
156 | ||
9e78e7fc MCC |
157 | my $basedir = "."; |
158 | # On translations, only seek inside the translations directory | |
159 | $basedir = $1 if ($ref =~ m,(Documentation/translations/[^/]+),); | |
160 | ||
d2656095 MCC |
161 | # get just the basename |
162 | $new =~ s,.*/,,; | |
163 | ||
d2656095 MCC |
164 | my $f=""; |
165 | ||
be600e5a MCC |
166 | # usual reason for breakage: DT file moved around |
167 | if ($ref =~ /devicetree/) { | |
168 | my $search = $new; | |
169 | $search =~ s,^.*/,,; | |
170 | $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); | |
171 | if (!$f) { | |
172 | # Manufacturer name may have changed | |
173 | $search =~ s/^.*,//; | |
174 | $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); | |
175 | } | |
176 | } | |
d2656095 MCC |
177 | |
178 | # usual reason for breakage: file renamed to .rst | |
179 | if (!$f) { | |
180 | $new =~ s/\.txt$/.rst/; | |
9e78e7fc | 181 | $f=qx(find $basedir -iname $new) if ($new); |
d2656095 MCC |
182 | } |
183 | ||
e1f319fe MCC |
184 | # usual reason for breakage: use dash or underline |
185 | if (!$f) { | |
186 | $new =~ s/[-_]/[-_]/g; | |
9e78e7fc | 187 | $f=qx(find $basedir -iname $new) if ($new); |
e1f319fe MCC |
188 | } |
189 | ||
be600e5a MCC |
190 | # Wild guess: seek for the same name on another place |
191 | if (!$f) { | |
9e78e7fc | 192 | $f = qx(find $basedir -iname $new) if ($new); |
be600e5a MCC |
193 | } |
194 | ||
d2656095 MCC |
195 | my @find = split /\s+/, $f; |
196 | ||
197 | if (!$f) { | |
198 | print STDERR "ERROR: Didn't find a replacement for $ref\n"; | |
199 | } elsif (scalar(@find) > 1) { | |
200 | print STDERR "WARNING: Won't auto-replace, as found multiple files close to $ref:\n"; | |
201 | foreach my $j (@find) { | |
202 | $j =~ s,^./,,; | |
203 | print STDERR " $j\n"; | |
204 | } | |
205 | } else { | |
206 | $f = $find[0]; | |
207 | $f =~ s,^./,,; | |
208 | print "INFO: Replacing $ref to $f\n"; | |
209 | foreach my $j (qx(git grep -l $ref)) { | |
210 | qx(sed "s\@$ref\@$f\@g" -i $j); | |
211 | } | |
212 | } | |
213 | } |