Tools/scripts/texcheck.py

   1 """ TeXcheck.py -- rough syntax checking on Python style LaTeX documents.
   2
   3    Written by Raymond D. Hettinger <python at rcn.com>
   4    Copyright (c) 2003 Python Software Foundation.  All rights reserved.
   5
   6 Designed to catch common markup errors including:
   7 * Unbalanced or mismatched parenthesis, brackets, and braces.
   8 * Unbalanced or mismatched \\begin and \\end blocks.
   9 * Misspelled or invalid LaTeX commands.
  10 * Use of forward slashes instead of backslashes for commands.
  11 * Table line size mismatches.
  12
  13 Sample command line usage:
  14     python texcheck.py -k chapterheading -m lib/librandomtex *.tex
  15
  16 Options:
  17     -m          Munge parenthesis and brackets. [0,n) would normally mismatch.
  18     -k keyword: Keyword is a valid LaTeX command. Do not include the backslash.
  19     -d:         Delimiter check only (useful for non-LaTeX files).
  20     -h:         Help
  21     -s lineno:  Start at lineno (useful for skipping complex sections).
  22     -v:         Verbose.  Trace the matching of //begin and //end blocks.
  23 """
  24
  25 import re
  26 import sys
  27 import getopt
  28 from itertools import izip, count, islice
  29 import glob
  30
  31 cmdstr = r"""
  32     \section \module \declaremodule \modulesynopsis \moduleauthor
  33     \sectionauthor \versionadded \code \class \method \begin
  34     \optional \var \ref \end \subsection \lineiii \hline \label
  35     \indexii \textrm \ldots \keyword \stindex \index \item \note
  36     \withsubitem \ttindex \footnote \citetitle \samp \opindex
  37     \noindent \exception \strong \dfn \ctype \obindex \character
  38     \indexiii \function \bifuncindex \refmodule \refbimodindex
  39     \subsubsection \nodename \member \chapter \emph \ASCII \UNIX
  40     \regexp \program \production \token \productioncont \term
  41     \grammartoken \lineii \seemodule \file \EOF \documentclass
  42     \usepackage \title \input \maketitle \ifhtml \fi \url \Cpp
  43     \tableofcontents \kbd \programopt \envvar \refstmodindex
  44     \cfunction \constant \NULL \moreargs \cfuncline \cdata
  45     \textasciicircum \n \ABC \setindexsubitem \versionchanged
  46     \deprecated \seetext \newcommand \POSIX \pep \warning \rfc
  47     \verbatiminput \methodline \textgreater \seetitle \lineiv
  48     \funclineni \ulink \manpage \funcline \dataline \unspecified
  49     \textbackslash \mimetype \mailheader \seepep \textunderscore
  50     \longprogramopt \infinity \plusminus \shortversion \version
  51     \refmodindex \seerfc \makeindex \makemodindex \renewcommand
  52     \indexname \appendix \protect \indexiv \mbox \textasciitilde
  53     \platform \seeurl \leftmargin \labelwidth \localmoduletable
  54     \LaTeX \copyright \memberline \backslash \pi \centerline
  55     \caption \vspace \textwidth \menuselection \textless
  56     \makevar \csimplemacro \menuselection \bfcode \sub \release
  57     \email \kwindex \refexmodindex \filenq \e \menuselection
  58     \exindex \linev \newsgroup \verbatim \setshortversion
  59     \author \authoraddress \paragraph \subparagraph \cmemberline
  60     \textbar \C \seelink
  61 """
  62
  63 def matchclose(c_lineno, c_symbol, openers, pairmap):
  64     "Verify that closing delimiter matches most recent opening delimiter"
  65     try:
  66         o_lineno, o_symbol = openers.pop()
  67     except IndexError:
  68         print "\nDelimiter mismatch.  On line %d, encountered closing '%s' without corresponding open" % (c_lineno, c_symbol)
  69         return
  70     if o_symbol in pairmap.get(c_symbol, [c_symbol]): return
  71     print "\nOpener '%s' on line %d was not closed before encountering '%s' on line %d" % (o_symbol, o_lineno, c_symbol, c_lineno)
  72     return
  73
  74 def checkit(source, opts, morecmds=[]):
  75     """Check the LaTeX formatting in a sequence of lines.
  76
  77     Opts is a mapping of options to option values if any:
  78         -m          munge parenthesis and brackets
  79         -d          delimiters only checking
  80         -v          verbose trace of delimiter matching
  81         -s lineno:  linenumber to start scan (default is 1).
  82
  83     Morecmds is a sequence of LaTeX commands (without backslashes) that
  84     are to be considered valid in the scan.
  85     """
  86
  87     texcmd = re.compile(r'\\[A-Za-z]+')
  88     falsetexcmd = re.compile(r'\/([A-Za-z]+)') # Mismarked with forward slash
  89
  90     validcmds = set(cmdstr.split())
  91     for cmd in morecmds:
  92         validcmds.add('\\' + cmd)
  93
  94     if '-m' in opts:
  95         pairmap = {']':'[(', ')':'(['}      # Munged openers
  96     else:
  97         pairmap = {']':'[', ')':'('}        # Normal opener for a given closer
  98     openpunct = set('([')                   # Set of valid openers
  99
 100     delimiters = re.compile(r'\\(begin|end){([_a-zA-Z]+)}|([()\[\]])')
 101     braces = re.compile(r'({)|(})')
 102     doubledwords = re.compile(r'(\b[A-za-z]+\b) \b\1\b')
 103     spacingmarkup = re.compile(r'\\(ABC|ASCII|C|Cpp|EOF|infinity|NULL|plusminus|POSIX|UNIX)\s')
 104
 105     openers = []                            # Stack of pending open delimiters
 106     bracestack = []                         # Stack of pending open braces
 107
 108     tablestart = re.compile(r'\\begin{(?:long)?table([iv]+)}')
 109     tableline = re.compile(r'\\line([iv]+){')
 110     tableend = re.compile(r'\\end{(?:long)?table([iv]+)}')
 111     tablelevel = ''
 112     tablestartline = 0
 113
 114     startline = int(opts.get('-s', '1'))
 115     lineno = 0
 116
 117     for lineno, line in izip(count(startline), islice(source, startline-1, None)):
 118         line = line.rstrip()
 119
 120         # Check balancing of open/close parenthesis, brackets, and begin/end blocks
 121         for begend, name, punct in delimiters.findall(line):
 122             if '-v' in opts:
 123                 print lineno, '|', begend, name, punct,
 124             if begend == 'begin' and '-d' not in opts:
 125                 openers.append((lineno, name))
 126             elif punct in openpunct:
 127                 openers.append((lineno, punct))
 128             elif begend == 'end' and '-d' not in opts:
 129                 matchclose(lineno, name, openers, pairmap)
 130             elif punct in pairmap:
 131                 matchclose(lineno, punct, openers, pairmap)
 132             if '-v' in opts:
 133                 print '   --> ', openers
 134
 135         # Balance opening and closing braces
 136         for open, close in braces.findall(line):
 137             if open == '{':
 138                 bracestack.append(lineno)
 139             if close == '}':
 140                 try:
 141                     bracestack.pop()
 142                 except IndexError:
 143                     print r'Warning, unmatched } on line %s.' % (lineno,)
 144
 145         # Optionally, skip LaTeX specific checks
 146         if '-d' in opts:
 147             continue
 148
 149         # Warn whenever forward slashes encountered with a LaTeX command
 150         for cmd in falsetexcmd.findall(line):
 151             if '822' in line or '.html' in line:
 152                 continue    # Ignore false positives for urls and for /rfc822
 153             if '\\' + cmd in validcmds:
 154                 print 'Warning, forward slash used on line %d with cmd: /%s' % (lineno, cmd)
 155
 156         # Check for markup requiring {} for correct spacing
 157         for cmd in spacingmarkup.findall(line):
 158             print r'Warning, \%s should be written as \%s{} on line %d' % (cmd, cmd, lineno)
 159
 160         # Validate commands
 161         nc = line.find(r'\newcommand')
 162         if nc != -1:
 163             start = line.find('{', nc)
 164             end = line.find('}', start)
 165             validcmds.add(line[start+1:end])
 166         for cmd in texcmd.findall(line):
 167             if cmd not in validcmds:
 168                 print r'Warning, unknown tex cmd on line %d: \%s' % (lineno, cmd)
 169
 170         # Check table levels (make sure lineii only inside tableii)
 171         m = tablestart.search(line)
 172         if m:
 173             tablelevel = m.group(1)
 174             tablestartline = lineno
 175         m = tableline.search(line)
 176         if m and m.group(1) != tablelevel:
 177             print r'Warning, \line%s on line %d does not match \table%s on line %d' % (m.group(1), lineno, tablelevel, tablestartline)
 178         if tableend.search(line):
 179             tablelevel = ''
 180
 181         # Style guide warnings
 182         if 'e.g.' in line or 'i.e.' in line:
 183             print r'Style warning, avoid use of i.e or e.g. on line %d' % (lineno,)
 184
 185         for dw in doubledwords.findall(line):
 186             print r'Doubled word warning.  "%s" on line %d' % (dw, lineno)
 187
 188     lastline = lineno
 189     for lineno, symbol in openers:
 190         print "Unmatched open delimiter '%s' on line %d" % (symbol, lineno)
 191     for lineno in bracestack:
 192         print "Unmatched { on line %d" % (lineno,)
 193     print 'Done checking %d lines.' % (lastline,)
 194     return 0
 195
 196 def main(args=None):
 197     if args is None:
 198         args = sys.argv[1:]
 199     optitems, arglist = getopt.getopt(args, "k:mdhs:v")
 200     opts = dict(optitems)
 201     if '-h' in opts or args==[]:
 202         print __doc__
 203         return 0
 204
 205     if len(arglist) < 1:
 206         print 'Please specify a file to be checked'
 207         return 1
 208
 209     for i, filespec in enumerate(arglist):
 210         if '*' in filespec or '?' in filespec:
 211             arglist[i:i+1] = glob.glob(filespec)
 212
 213     morecmds = [v for k,v in optitems if k=='-k']
 214     err = []
 215
 216     for filename in arglist:
 217         print '=' * 30
 218         print "Checking", filename
 219         try:
 220             f = open(filename)
 221         except IOError:
 222             print 'Cannot open file %s.' % arglist[0]
 223             return 2
 224
 225         try:
 226             err.append(checkit(f, opts, morecmds))
 227         finally:
 228             f.close()
 229
 230     return max(err)
 231
 232 if __name__ == '__main__':
 233     sys.exit(main())