2 # SPDX-License-Identifier: GPL-2.0
4 # Treewide grep for references to files under Documentation, and report
5 # non-existing files in stderr.
9 use Getopt::Long qw(:config no_auto_abbrev);
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
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",
20 $scriptname =~ s,.*/([^/]+/),$1,;
28 printf "Warning: can't check if file exists, as this is not a git tree";
35 'h|help|usage' => \$help,
39 print "$scriptname [--help] [--fix]\n";
43 # Step 1: find broken references
44 print "Finding broken references. This may take a while... " if ($fix);
50 open IN, "git grep ':doc:\`' Documentation/|"
51 or die "Failed to run git grep";
53 next if (!m,^([^:]+):.*\:doc\:\`([^\`]+)\`,);
61 $f =~ s,.*\<([^\>]+)\>,$1,;
65 next if (grep -e, glob("$f"));
67 if ($fix && !$doc_fix) {
68 print STDERR "\nWARNING: Currently, can't fix broken :doc:`` fields\n";
72 print STDERR "$f: :doc:`$doc_ref`\n";
76 open IN, "git grep 'Documentation/'|"
77 or die "Failed to run git grep";
79 next if (!m/^([^:]+):(.*)/);
84 # On linux-next, discard the Next/ directory
85 next if ($f =~ m,^Next/,);
87 # Makefiles and scripts contain nasty expressions to parse docs
88 next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/);
91 next if ($f eq $scriptname);
93 if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) {
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/^{/);
104 # Remove footnotes at the end like:
105 # Documentation/devicetree/dt-object-internal.txt[1]
106 $ref =~ s/(txt|rst)\[\d+]$/$1/;
108 # Remove ending ']' without any '['
109 $ref =~ s/\].*// if (!($ref =~ m/\[/));
111 # Remove puntuation marks at the end
112 $ref =~ s/[\,\.]+$//;
114 my $fulref = "$prefix$ref";
116 $fulref =~ s/^(\<file|ref)://;
117 $fulref =~ s/^[\'\`]+//;
118 $fulref =~ s,^\$\(.*\)/,,;
121 # Remove URL false-positives
122 next if ($fulref =~ m/^http/);
124 # Remove sched-pelt false-positive
125 next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
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,);
130 # Check if exists, evaluating wildcards
131 next if (grep -e, glob("$ref $fulref"));
133 # Accept relative Documentation patches for tools/
134 if ($f =~ m/tools/) {
136 $path =~ s,(.*)/.*,$1,;
137 next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref"));
140 # Discard known false-positives
141 if (defined($false_positives{$f})) {
142 next if ($false_positives{$f} eq $fulref);
146 if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
150 print STDERR "Warning: $f references a file that doesn't exist: $fulref\n";
152 print STDERR "$f: $fulref\n";
160 # Step 2: Seek for file name alternatives
161 print "Auto-fixing broken references. Please double-check the results\n";
163 foreach my $ref (keys %broken_ref) {
167 # On translations, only seek inside the translations directory
168 $basedir = $1 if ($ref =~ m,(Documentation/translations/[^/]+),);
170 # get just the basename
175 # usual reason for breakage: DT file moved around
176 if ($ref =~ /devicetree/) {
177 # usual reason for breakage: DT file renamed to .yaml
180 $new_ref =~ s/\.txt$/.yaml/;
181 $f=$new_ref if (-f $new_ref);
187 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
189 # Manufacturer name may have changed
191 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
196 # usual reason for breakage: file renamed to .rst
198 $new =~ s/\.txt$/.rst/;
199 $f=qx(find $basedir -iname $new) if ($new);
202 # usual reason for breakage: use dash or underline
204 $new =~ s/[-_]/[-_]/g;
205 $f=qx(find $basedir -iname $new) if ($new);
208 # Wild guess: seek for the same name on another place
210 $f = qx(find $basedir -iname $new) if ($new);
213 my @find = split /\s+/, $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) {
221 print STDERR " $j\n";
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);