Add help command line and print usage information
[project-aon.git] / common / scripts / gblint.pl
1 #!/usr/bin/perl -Tw
2 #
3 # Each new section id requires adding it to the list (e.g. improved
4 # disciplines).
5 #
6 ###############################################################################
7 use strict;
8
9 my $endOfDTD = 0;
10
11 my %sectionDocLookup = (
12   '_unknown' => '_unknown',
13   'toc'      => 'toc',
14   'title'    => 'title',
15   'dedicate' => 'dedicate',
16   'acknwldg' => 'acknwldg',
17   'credits'  => 'acknwldg',
18   'coming'   => 'coming',
19   'tssf'     => 'tssf',
20   'gamerulz' => 'gamerulz',
21   'discplnz' => 'discplnz',
22   'camflage' => 'discplnz',
23   'hunting'  => 'discplnz',
24   'sixthsns' => 'discplnz',
25   'tracking' => 'discplnz',
26   'healing'  => 'discplnz',
27   'wepnskll' => 'discplnz',
28   'mndshld'  => 'discplnz',
29   'mndblst'  => 'discplnz',
30   'anmlknsp' => 'discplnz',
31   'mindomtr' => 'discplnz',
32   'mksumary' => 'discplnz',
33   'anmlctrl' => 'discplnz',
34   'curing'   => 'discplnz',
35   'invsblty' => 'discplnz',
36   'psisurge' => 'discplnz',
37   'psiscrn'  => 'discplnz',
38   'dvnation' => 'discplnz',
39   'wpnmstry' => 'discplnz',
40   'anmlmstr' => 'discplnz',
41   'deliver'  => 'discplnz',
42   'assimila' => 'discplnz',
43   'hntmstry' => 'discplnz',
44   'pthmnshp' => 'discplnz',
45   'kaisurge' => 'discplnz',
46   'kaiscrn'  => 'discplnz',
47   'nexus'    => 'discplnz',
48   'gnosis'   => 'discplnz',
49   'magi'     => 'discplnz',
50   'kalchemy' => 'discplnz',
51   'powers'   => 'powers',
52   'lessmcks' => 'powers',
53   'alchemy'  => 'powers',
54   'sorcery'  => 'powers',
55   'enchant'  => 'powers',
56   'elementl' => 'powers',
57   'prophecy' => 'powers',
58   'psycmncy' => 'powers',
59   'evcation' => 'powers',
60   'highmcks' => 'powers',
61   'thamtrgy' => 'powers',
62   'telergy'  => 'powers',
63   'physirgy' => 'powers',
64   'theurgy'  => 'powers',
65   'visionry' => 'powers',
66   'necrmncy' => 'powers',
67   'staff'    => 'powers',
68   'moonston' => 'powers',
69   'equipmnt' => 'equipmnt',
70   'howcarry' => 'equipmnt',
71   'howmuch'  => 'equipmnt',
72   'howuse'   => 'equipmnt',
73   'backpack' => 'equipmnt',
74   'ammpouch' => 'equipmnt',
75   'medikit'  => 'equipmnt',
76   'canteen'  => 'equipmnt',
77   'weapons'  => 'weapons',
78   'close'    => 'weapons',
79   'missile'  => 'weapons',
80   'cmbtrulz' => 'cmbtrulz',
81   'evasion'  => 'cmbtrulz',
82   'lorecrcl' => 'lorecrcl',
83   'lcbonus'  => 'lorecrcl',
84   'levels'   => 'levels',
85   'primate'  => 'levels',
86   'tutelary' => 'levels',
87   'mentora'  => 'levels',
88   'scion'    => 'levels',
89   'archmstr' => 'levels',
90   'prncpln'  => 'levels',
91   'imprvdsc' => 'imprvdsc',
92   'guardian' => 'imprvdsc',
93   'sunkght'  => 'imprvdsc',
94   'sunlord'  => 'imprvdsc',
95   'kaiwisdm' => 'kaiwisdm',
96   'sage'     => 'sage',
97   'numbered' => 'numbered',
98   'passing'  => 'passing',
99   'part1'    => 'part1',
100   'part2'    => 'part2',
101   'map'      => 'map',
102   'action'   => 'action',
103   'crsumary' => 'crsumary',
104   'smevazn'  => 'crsumary',
105   'crtable'  => 'crtable',
106   'random'   => 'random',
107   'errata'   => 'errata',
108   'errintro' => 'errata',
109   'errerr'   => 'errata',
110   'footnotz' => 'footnotz',
111   'illstrat' => 'illstrat',
112   'primill'  => 'illstrat',
113   'secill'   => 'illstrat',
114   'license'  => 'license',
115   'lic-pre'  => 'license',
116   'lic-1'    => 'license',
117   'lic-1-0'  => 'license',
118   'lic-1-1'  => 'license',
119   'lic-1-2'  => 'license',
120   'lic-1-3'  => 'license',
121   'lic-1-4'  => 'license',
122   'lic-1-5'  => 'license',
123   'lic-1-6'  => 'license',
124   'lic-1-7'  => 'license',
125   'lic-2'    => 'license',
126   'lic-2-0'  => 'license',
127   'lic-2-1'  => 'license',
128   'lic-2-2'  => 'license',
129   'lic-2-3'  => 'license',
130   'lic-2-4'  => 'license',
131   'lic-2-5'  => 'license',
132   'lic-3'    => 'license',
133   'lic-3-0'  => 'license',
134   'lic-3-1'  => 'license',
135   'lic-4'    => 'license',
136   'lic-4-0'  => 'license',
137   'lic-5'    => 'license',
138   'lic-5-0'  => 'license',
139   'lic-6'    => 'license',
140   'lic-6-0'  => 'license',
141   'lic-6-1'  => 'license',
142 );
143
144 my $errorCount = 0;
145 my $maxErrorCount = 0;
146 my $skipLines = 0;
147 my $initials = "??";
148 my $useCorr = 0;
149 my $checkNonASCII = 1;
150 my $language = 'en';
151
152 while( $#ARGV > -1 && $ARGV[ 0 ] =~ /^-/ ) {
153   if( $ARGV[ 0 ] eq "-e" && $#ARGV > 0 ) {
154     shift @ARGV;
155     $maxErrorCount = shift @ARGV;
156   }
157   elsif( $ARGV[ 0 ] eq "-s" && $#ARGV > 0 ) {
158     shift @ARGV;
159     $skipLines = shift @ARGV;
160   }
161   elsif( $ARGV[ 0 ] eq "-i" && $#ARGV > 0 ) {
162     shift @ARGV;
163     $initials = shift @ARGV;
164   }
165   elsif( $ARGV[ 0 ] eq "--use-corr" ) {
166     shift @ARGV;
167     $useCorr = 1;
168   }
169   elsif( $ARGV[ 0 ] eq '--skip-ASCII-check' ) {
170     shift @ARGV;
171     $checkNonASCII = 0;
172   }
173   elsif( $ARGV[ 0 ] eq '--language' ) {
174     shift @ARGV;
175     $language = shift @ARGV;
176   }
177   elsif( $ARGV[ 0 ] eq '-h' ) {
178     usage();
179     exit 0;
180   }
181 }
182
183 my $lineNumber = 1;
184 my $currentSection = '';
185
186 while( my $line = <> ) {
187   my @section = ( $line =~ /<section[^>]+id="([^"]*)"/g );
188   if( $#section > 0 ) { die( "Multiple sections begin at line $lineNumber\n" ); }
189   elsif( $#section == 0 ) {
190     if( $section[ 0 ] =~ /^sect[[:digit:]]+$/ ) {
191       $currentSection = $section[ 0 ];
192     }
193     else {
194       $currentSection = $sectionDocLookup{$section[ 0 ]};
195     }
196     $currentSection = '_unknown' unless defined $currentSection;
197   }
198
199   if( $skipLines >= $lineNumber ) {
200     ++$lineNumber;
201     next;
202   }
203
204   ##### Unescaped Characters
205   if( $line =~ /[\200-\377]/ ) {
206     if( $line =~ /\221/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped left single quotation mark(s)", "\221", "<quote>...</quote> or <ch.apos/>" ); }
207     if( $line =~ /\222/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped right single quotation mark(s)", "\222", "<quote>...</quote> or <ch.apos/>" ); }
208     if( $line =~ /\223/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped left double quotation mark(s)", "\223", "<quote>...</quote>" ); }
209     if( $line =~ /\224/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped right double quotation mark(s)", "\224", "<quote>...</quote>" ); }
210     if( $line =~ /\226/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped endash(es)", "\226", "<ch.endash/>" ); }
211     if( $line =~ /\227/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped emdash(es)", "\227", "<ch.emdash/>" ); }
212 #    if( $checkNonASCII && $line =~ /(.{0,4}?)?([\x80-\xff])(.{0,4})?/ ) {
213 #      &printError( "ne", $currentSection, $lineNumber, "unescaped non-ASCII character(s) in \"${1}[[HERE]]${3}\"; first found only", "$2" );
214 #    }
215     if( $line =~ /(.{0,4}?)?([\x80-\x9f])(.{0,4})?/ ) {
216       &printError( "ne", $currentSection, $lineNumber, "unsafe non-ASCII character(s) in \"${1}[[HERE]]${3}\"; first found only", "$2" );
217     }
218 }
219   if( $line =~ /'/ ) { &printError( "ne", $currentSection, $lineNumber, "unescaped apostrophe(s)", "'", "<ch.apos/> or <quote>...</quote>" ); }
220   if( $line =~ /`/ ) { &printError( "ne", $currentSection, $lineNumber, "backtick(s)", "`", "<ch.apos/> or <quote>...</quote>" ); }
221
222   # tab
223
224   if( $line =~ /\t/ ) { &printError( "ne", $currentSection, $lineNumber, "TAB character found; convert to equivalent SPACEs" ); }
225
226   # ampersand
227   if( $line =~ /\&\s/ ) { &printError( "ne", $currentSection, $lineNumber, "possible malformed ampersand or escape sequence", "&", "<ch.ampersand/>" ); }
228
229   # emdash
230   if( $line =~ /\s-\s/ ) { &printError( "ne", $currentSection, $lineNumber, "probable malformed emdash", " - ", "<ch.emdash/>" ); }
231   if( $line =~ /(?<!\!)--(?!>)/ ) { &printError( "ne", $currentSection, $lineNumber, "probable malformed emdash", "--", "<ch.emdash/>" ); }
232
233   # endash
234   if( $line =~ /([0-9])-([0-9]+)(?![^<]+>)/ ) { &printError( "ne", $currentSection, $lineNumber, "possible malformed endash", "$1-$2", "$1<ch.endash/>$2" ); }
235
236   # ellipsis
237   if( $line =~ /(\.\s*\.(\s*\.)?)/ ) { &printError( "ne", $currentSection, $lineNumber, "possible malformed ellipsis", "$1", "<ch.ellips/> or <ch.lellips/>" ); }
238   if( $line =~ m{([[:space:]]<ch\.ellips/>)} || $line =~ m{(<ch\.ellips/>[[:space:]])} ) { &printError( "ne", $currentSection, $lineNumber, "<ch.ellips/> with extraneous surrounding space", "$1", "<ch.ellips/>" ); }
239   if( $line =~ m{([^>])(<ch\.lellips/>)} ) { &printError( "ne", $currentSection, $lineNumber, "possible <ch.lellips/> used in place of <ch.ellips/>", "$1$2", "$1<ch.ellips/>" ); }
240   if( $line =~ m{(><ch\.ellips/>)} ) { &printError( "ne", $currentSection, $lineNumber, "possible <ch.ellips/> used in place of <ch.lellips/>", "$1", "><ch.lellips/>" ); }
241
242   # thinspace
243   if( $line =~ m{(</?quote>)\1} ) { &printError( "ne", $currentSection, $lineNumber, "probable candidate for thinspace", "$1$1", "$1<ch.thinspace/>$1" ); }
244   if( $line =~ m{(<quote>)(<ch.apos/>)} || $line =~ m{(<ch.apos/>)(</quote>)} ) { &printError( "ne", $currentSection, $lineNumber, "probable canidate for thinspace", "$1$2", "$1<ch.thinspace/>$2" ); }
245
246   # blankline
247   if( $line =~ /(__+)/ ) { &printError( "ne", $currentSection, $lineNumber, "probable candidate for blankline", "$1", "<ch.blankline/>" ); }
248
249   # percent
250   #  It should be safe to assume that there will be a "]>" at the end of
251   #  internal DTD subset. Previous to the end of the internal DTD subset
252   #  "%" has special meaning and shouldn't be detected.
253   if( $line =~ /]>/ ) { $endOfDTD = 1; }
254   if( $endOfDTD && $line =~ /\%/ ) { &printError( "ne", $currentSection, $lineNumber, "possible candidate for percent", "\%", "<ch.percent/>" ); }
255
256   ##### OCR Errors
257
258   if( $line !~ m{^[[:space:]]*</((p)|(choice))>} && $line =~ m{(([^.?!:);>]</((p)|(choice)))>)} ) { &printError( "??", $currentSection, $lineNumber, "possible missing punctuation", "$1" ); }
259   if( $line =~ /((?<![iIeE]\.[eg])[.?!]\s+[a-z])/ ) { &printError( "??", $currentSection, $lineNumber, "possible bad initial capitalization", "$1" ); }
260   if( $line =~ /([a-zA-Z][0-9][a-zA-Z])/ ) { &printError( "??", $currentSection, $lineNumber, "probable replacement of number for letter", "$1" ); }
261   if( $line =~ />[^<]*-[[:space:]]/ ) { &printError( "??", $currentSection, $lineNumber, "possible retained end-of-line hyphen(s)" ); }
262
263   ##### Obsolete Markup
264
265   if( $line =~ /\&lsquot;/ ) { &printError( "ne", $currentSection, $lineNumber, "probable obsolete markup", "\&lsquot;", "<quote>" ); }
266   if( $line =~ /\&rsquot;/ ) { &printError( "ne", $currentSection, $lineNumber, "probable obsolete markup", "\&rsquot;", "</quote>" ); }
267   if( $line =~ /\&ldquot;/ ) { &printError( "ne", $currentSection, $lineNumber, "probable obsolete markup", "\&ldquot;", "<quote>" ); }
268   if( $line =~ /\&rdquot;/ ) { &printError( "ne", $currentSection, $lineNumber, "probable obsolete markup", "\&rdquot;", "</quote>" ); }
269   if( $line =~ /\&quot;/ ) { &printError( "ne", $currentSection, $lineNumber, "possible obsolete markup", "\&quot;", "<quote> or </quote>" ); }
270   if( $line =~ /(\&link.[^;]+;)/ && ($1 ne '&link.staff.contact;') && ($1 ne '&link.project.website;')) { &printError( "ne", $currentSection, $lineNumber, "possibe obsolete markup", "$1", "use <bookref.../> instead" ); }
271   if( $line =~ /\&([^[:space:]]+);/ ) {
272     unless( $1 =~ /^(?:link|inclusion)/ ) {
273       &printError( "ne", $currentSection, $lineNumber, "possible obsolete markup", "\&$1\;", "<ch.$1/>" );
274     }
275   }
276   if( $line =~ /(<a([^>]*) class="footnote"(.*?)>)/ )  { &printError( "ne", $currentSection, $lineNumber, "obsolete markup", "$1", "<footref$2$3>" ); }
277
278   ##### Character Attributes
279   # The following test uses negative lookback (?<! ... )
280   if( $line =~ /[^>]((?<!CLOSE\s)COMBAT\s+SKILL)/ || $line =~ /((?<!CLOSE\s)COMBAT\s+SKILL)[^<]/ ) {
281     &printError( "ne", $currentSection, $lineNumber, "possible missing markup", "$1", "<typ class=\"attribute\">$1</typ>" );
282   }
283   if( $line =~ /[^>](CLOSE\sCOMBAT\sSKILL)/ || $line =~ /(CLOSE\s+COMBAT\s+SKILL)[^<]/ ) {
284     &printError( "ne", $currentSection, $lineNumber, "possible missing markup", "$1", "<typ class=\"attribute\">$1</typ>" );
285   }
286   if( $line =~ /[^>](ENDURANCE)/ || $line =~ /(ENDURANCE)[^<]/ ) {
287     &printError( "ne", $currentSection, $lineNumber, "possible missing markup", "ENDURANCE", "<typ class=\"attribute\">ENDURANCE</typ>" );
288   }
289   if( $line =~ /[^>](WILLPOWER)/ || $line =~ /(WILLPOWER)[^<]/ ) {
290     &printError( "ne", $currentSection, $lineNumber, "possible missing markup", "WILLPOWER", "<typ class=\"attribute\">WILLPOWER</typ>" );
291   }
292
293   ##### Links
294   if( $line =~ /[^>](random[[:space:]]+number[[:space:]]+table)/i ) {
295     &printError( "ne", $currentSection, $lineNumber, "possible missing markup", "$1", "<a idref=\"random\">$1</a>" );
296   }
297   if( $line =~ /[^>](action[[:space:]]+charts?)/i ) {
298     &printError( "ne", $currentSection, $lineNumber, "possible missing markup", "$1", "<a idref=\"action\">$1</a>" );
299   }
300
301   ##### Others
302   if( $line =~ m{<!--(?!/?ERRTAG)} ) { &printError( "ne", $currentSection, $lineNumber, "XML comment found (check for editor comments)" ); }
303   if( $line =~ /([[:upper:]]{5,})/ &&
304       $` !~ /<signpost>$/ &&
305       (($language eq 'en' && 
306         $1 ne "ENDURANCE" &&
307         $1 ne "COMBAT" &&
308         $1 ne "WILLPOWER" &&
309         $1 ne "HAVOC" &&
310         $1 ne "CLOSE") ||
311        ($language eq 'es' &&
312         $1 ne 'DESTREZA' &&
313         $1 ne 'RESISTENCIA')) &&
314         $1 ne "DOCTYPE" &&
315         $1 ne "ENTITY" &&
316         $1 ne "XVIII" &&
317         $1 ne "ERRTAG" )
318       { &printError( "ne", $currentSection, $lineNumber, "possible <signpost> needed", "$1", "<signpost>$1</signpost>" ); }
319
320   #####
321   ++$lineNumber;
322 }
323
324 unless( $endOfDTD || $skipLines > 0 ) { print "End of document reached without finding end of internal DTD subset \"]>\".\n"; }
325
326 ################################################################################
327
328 sub printError {
329   my ($type, $section, $line, $message, $original, $corrected) = @_;
330   my $report = "";
331
332   if( $useCorr ) {
333     $report = "($type) $section: ";
334     if( defined $original ) { $report .= "$original "; }
335     if( defined $corrected ) { $report .= "-> $corrected "; }
336     $report .= "[$initials: $message <line $line>]\n";
337   }
338   else {
339     $report = "line $line ($section): $message";
340     if( defined $original ) { $report .= " \"$original\""; }
341     if( defined $corrected ) { $report .= " ($corrected)"; }
342     $report .= "\n";
343   }
344
345   print $report;
346
347   ++$errorCount;
348   if( $maxErrorCount > 0 && $errorCount > $maxErrorCount ) { die "Maximum number of errors ($maxErrorCount) exceeded. Quitting.\n"; }
349 }
350
351 sub usage {
352     print "Gamebook lintian checker - reads from standard input a gamebook XML file and prints out possible errors\n\n";
353     print "Usage: gblint.pl [-e <NUMBER>] [-s <NUMBER>] [-i <TEXT>] [--use-corr] [--skip-ASCII-check] [--language CODE]\n";
354     print "Options:\n";
355     print "\t-e <NUMBER>\tStops when NUMBER errors have been reached (by default it does not stop)\n";
356     print "\t-s <NUMBER>\tSkips NUMBER of lines before analysing\n";
357     print "\t-i <TEXT>\tAdds TEXT to error messages (default: '??')\n";
358     print "\t--use-corr\tPrints correction in report (default: disabled)\n";
359     print "\t--skip-ASCII-check\tDoes not check for non-ASCCI characters (default: enabled)\n";
360     print "\t--language CODE\tDefines the language of the gamebook file (default: 'en'\n";
361     print "\t-h\tPrint this help and exit\n";
362 }