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())