%%
%%  ChkTeX v1.7.9, LaTeX documentation for ChkTeX program.
%%  Copyright (C) 1995-96 Jens T. Berger Thielemann
%%
%%  This program is free software; you can redistribute it and/or modify
%%  it under the terms of the GNU General Public License as published by
%%  the Free Software Foundation; either version 2 of the License, or
%%  (at your option) any later version.
%%
%%  This program is distributed in the hope that it will be useful,
%%  but WITHOUT ANY WARRANTY; without even the implied warranty of
%%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%  GNU General Public License for more details.
%%
%%  You should have received a copy of the GNU General Public License
%%  along with this program; if not, write to the Free Software
%%  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
%%
%%  Contact the author at:
%%              Jens Berger
%%              Spektrumvn. 4
%%              N-0666 Oslo
%%              Norway
%%              E-mail: <jensthi@ifi.uio.no>
%%
%% NOTE: This file is written in LaTeX, and should be compiled
%% before viewing. If you don't know how to do this, consult
%% your local TeX guru. If you don't possess LaTeX, you are
%% assumed to not need this program; so there's no text version
%% of this file...
%%
%% You may still be able to view the DVI or PostScript versions of
%% this file, though, they are included in the archive.
%%



\documentclass[a4paper]{article}
%endlatex
\newcommand{\jtbt}{Jens~T. Berger~Thielemann}
\newcommand{\Cmd}[1]{``\texttt{#1}''}
\newcommand{\rsrc}{``\texttt{chktexrc}''}
\newcommand{\chktex}{Chk\TeX}

\newcommand{\BS}{\verb@\@}\newcommand{\chktex}{ChkTeX}\newcommand{\slash}{/}%endlatex

% PDF table of contents
\usepackage{hyperref}
\hypersetup{
  colorlinks=true,
  allcolors=blue,
  pdfpagemode=UseOutlines
}
\usepackage{hypcap}


\title{\chktex\ v1.7.9}
\author{Jens~T. Berger~Thielemann}
\date{\today}


\begin{document}
\maketitle

%endlatex
\section{Introduction}

This program has been written in frustration because some constructs in
\LaTeX\ are sometimes non-intuitive, and easy to forget. It is
\emph{not} a replacement for the built-in checker in \LaTeX\@; however it
catches some typographic errors \LaTeX\ oversees. In other words, it
is Lint for \LaTeX. Filters are also provided for checking the
\LaTeX\ parts of CWEB documents.

It is written in ANSI C and compiles silently under GCC using
\Cmd{-Wall -ansi -pedantic} and almost all warning flags. This means
that you can compile \& use the program on your favorite machine.
Full source included.

The program also supports output formats suitable for further
processing by editors or other programs, making errors easy to cycle through.
For example, recent versions of AUC\TeX\ (the Emacs mode) interface
beautifully with \chktex.

The program itself does not have any machine requirements; However compiling
for other platforms has not been done for a long time now so the code has been
removed. If interest rises it can be resurrected.


\section{Features}
\chktex\ begins to get quite a few bells \& whistles now.  However, you
should be aware of that in most cases, all this is transparent to the user.
As you will see, \chktex\ offers the ability to adapt to many environments
and configurations.

\begin{itemize}
\item Supports over 40 warnings. Warnings include:
%endlatex
      \begin{itemize}
      \item Commands terminated with space. Ignores \Cmd{\BS{}tt}, etc.
      \item Space in front of references instead of \Cmd{\~{}}.
      \item Forgetting to group parenthesis characters when
        sub-\slash{}super\-scripting.
      \item Italic correction (\Cmd{\BS/}) mistakes (double,
        missing, unnecessary).
      \item Parenthesis and environment matching.
      \item Ellipsis detection; also checks whether to use
        \Cmd{\BS{}dots}, \Cmd{\BS{}cdots} or \Cmd{\BS{}ldots}.
      \item Enforcement of normal space after abbreviation. Detects
        most abbreviations automagically.
      \item Enforcement of end-of-sentence space when the last
        sentence ended with capital letter.
      \item Math-mode on/off detection.
      \item Quote checking, both wrong types (\Cmd{"}) and wrong
        direction.
      \item Recommends splitting three quotes in a row.
      \item Searching for user patterns.
      \item Displays comments.
      \item Space in front of \Cmd{\BS{}label} and similar commands.
      \item Use of \Cmd{x} instead of \Cmd{\$\BS{}times\$} between numbers.
      \item Multiple spaces in input which will be rendered as one
        space (or multiple spaces, where that is undesirable).
      \item Warns about text which may be ignored.
      \item Mathematical operators typeset as variables.
      \item No space in front of/after parenthesis.
      \item Demands a consistent quote style.
      \item Punctuation inside inner math mode/outside display math
        mode.
      \item Use of \TeX\ primitives where \LaTeX\ equivalents are
        available.
      \item Space in front of footnotes.
      \item Bogus characters following commands.
      \item Ability to suppress warnings on a single line.
      \end{itemize}
%endlatex
\item Fully customizable. Intelligent resource format makes it
  possible to make \chktex\ respect your \LaTeX\ setup.  Even
  command-line options may be specified globally in the \rsrc\ file.
\item Supports \Cmd{\BS{}input} command; both \TeX\ and \LaTeX\ version.
  Actually includes the files. \Cmd{TEXINPUTS}-equivalent search path.
\item Intelligent warning/error handling. The user may promote/mute
  warnings to suit his preferences. You may also mute warnings in the
  header of a file; thus killing much unwanted garbage.
\item Scripts included for checking CWEB files written in \LaTeX.
  (Requires perl v5).
\item Supports both \LaTeX\ 2.09 and \LaTeXe{}.
\item Flexible output handling. Has some predefined formats and lets
  the user specify his own format.  Uses a \Cmd{printf()} similar
  syntax. \Cmd{lacheck} compatible mode included for interfacing with
  systems which only support lacheck.
\item Written in ANSI C\@. \Cmd{configure} script included for easy
  setup and installation on UNIX systems.
\end{itemize}

Still, it is important to realize that the output from \chktex\ is
only intended as a \emph{guide} to fixing faults. However, it is by
no means always correct. This means that correct \LaTeX\ code may
produce errors in \chktex, and vice versa: Incorrect \LaTeX\ code may pass
silently through.



\section{Legal stuff}

\chktex{}, documentation, installations scripts, CWEB filters and other
materials provided are copyright \copyright\ 1995--96 Jens~T.
Berger~Thielemann, unless explicitly stated otherwise.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY\@; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE\@.  See the GNU General Public License for
more details.

You  should  have  received  a  copy of the GNU General Public License
along   with  this  program;  if  not,  write  to:
\begin{quote}
    The  Free  Software Foundation, Inc. \\
    51 Franklin Street \\
    Fifth Floor \\
    Boston \\
    MA 02110-1301 \\
    USA
\end{quote}


\section{Availability}

This program is on CTAN\@; thus it can be found at any mirrors of those.
It is also part of TeX Live 2011.

\section{Installation}

A few words on installation on various platforms:

\begin{description}
\item[UNIX:] Type \Cmd{configure}, \Cmd{make} and finally
  \Cmd{make~install}. To make sure everything proceeded correctly,
  type \Cmd{make~check}.  If you don't have superuser privileges and thus
  access to the default system areas, you should type
  \Cmd{configure~-{}-help} to help you set up correct paths.

  If you haven't installed any software like this before, that is
  distributed in source form, here are some guidelines to help you
  install it locally at your account. Please note that a mail to the
  system administrator may be less work for you.

  We assume that you have put the archive (\Cmd{chktex.tar.gz}) in a
  subdir of yours, with path \Cmd{\~{}/tmp}. We further assume that
  your shell is \Cmd{csh} or \Cmd{tcsh}. Do the following:

  \begin{enumerate}
  \item First of all, unpack the archive contents.

\begin{verbatim}
> cd ~/tmp
> gunzip chktex.tar.gz
> tar xf chktex.tar
\end{verbatim}

  \item Now, we can configure the program.  There are some
    configuration options you should know about:
    \begin{description}
    \item[\Cmd{-{}-enable-pcre}:] Allows using PCRE (perl compatible
      regular expressions) for use defined warnings.  The default is
      to use PCRE if it is installed on your system as determined by
      \Cmd{pcre-config}.  You can use \Cmd{-{}-disable-pcre} if you
      plan to distribute this for systems in which you cannot ensure
      PCRE will be installed.

      User defined regular expressions are defined using
      \texttt{UserWarnRegex} in the \rsrc\ file.  See warning~44 for
      more information.

    \item[\Cmd{-{}-enable-lacheck-replace}] This enables a quick
      hack for using \chktex\ instead of lacheck. This is done by
      installing a stub script which ``overrides'' the original
      lacheck executable. In this way, tools which support lacheck
      can be easily made to support chktex instead.

    \item[\Cmd{-{}-enable-debug-info}] \chktex\ has an ability to spit
      out various diagnostic messages using the \Cmd{-d} flag. This
      behaviour is on by default. By adding the flag
      \Cmd{-{}-disable-debug-info} to the commandline, this will not be
      compiled in.

      This may be useful if you're running short of disk space (the
      time savings are neglible).
    \end{description}

    If you are installing the program on your local account, use the
    following command:

\begin{verbatim}
> configure --prefix ~/
\end{verbatim}

    Add eventual extra flags as specified above. This command will
    generate a significant amount of output, this can usually be ignored.

  \item Finally, we can just build the program and install it.

\begin{verbatim}
> make
> make install
\end{verbatim}

  \item Finished! The program is now installed and ready to use. You
    may now tell other people to put your bindir in their path in
    order to benefit from your work. All that remains is to make the
    shell aware of your installation.

\begin{verbatim}
> rehash
\end{verbatim}

    To make the remaining parts of your system aware of this, you'll
    have to log out and re-log in, I'm afraid. However, you should delay this
    until you've completed this installation procedure.

  \item If you wish to make sure that everything is OK (you ought to),
    you may now ask \chktex\ to do a self-test:

\begin{verbatim}
> make check
\end{verbatim}

  \end{enumerate}

\item[Other platforms:] First of all, you have to copy the
  \Cmd{config.h.in} file to a file named \Cmd{config.h}.  Then, edit
  it to reflect your system.  Do the same with \Cmd{OpSys.h} (this
  file has been reduced significantly).  If you wish, you may define
  \Cmd{DATADIR} to the path you want the global resource file to be
  put.

  Now, I would suggest that you take a peak at the \Cmd{OpSys.c}
  file, and edit it appropiately, for more
  comfort.  This should not be necessary, though, at least not the
  first time.

  Finally, you may now compile and link all \verb@.c@ files.  Do not
  forget to define \Cmd{HAVE\_CONFIG\_H} to 1 (on the command-line,
  for instance).  If the \Cmd{config.h} you wish to use has another
  name, define \Cmd{CONFIG\_H\_NAME} to that (in that case, don't
  define \Cmd{HAVE\_CONFIG\_H}).

  Put the directory path of the \rsrc\ file in a environment variable
  named \Cmd{CHKTEXRC}.  The files \Cmd{deweb.in} and \Cmd{chkweb}
  should be moved to a directory in your path.  These files may need
  further setup, as they haven't got the location of perl
  initialized.

  If your compiler/the compiled program complains (or crashes!), you
  may try the hints listed below.  Please note that it only makes
  sense to try these hints if your compiler fails to produce a working
  program.

  \begin{enumerate}
  \item Increase the preprocessor buffers and line buffers. The
    \chktex{} sources define macros sized 3--4k (expanding to about
    the same), and passes arguments sized about 1k.
  \item Use the magic switch which lets us use large
    \Cmd{switch(\dots)\{\dots\}} statements; some of these statements
    have about 120 \Cmd{case} entries.
  \item The sources require that at least the first 12 of each
    identifier is significant.
  \end{enumerate}
\end{description}
\paragraph{Note:} You \emph{must} install the new \rsrc\ file; \chktex\ will
fail to function otherwise!

    After   doing   this,   you   may  enhance  \chktex's  behaviour  by
reading/editing the \rsrc\ file.

%endlatex
\section{Contacting the author}

If you wish to contact me for any reason or would like to participate in
the development of \chktex, please write to:
%endlatex
  \begin{quote}
    Jens Berger           \\
    Spektrumvn. 4         \\
    N-0666 Oslo           \\
    Norway                \\
    E-mail: \texttt{<jensthi@ifi.uio.no>}
  \end{quote}
%endlatex
Any signs of intelligent life are welcomed; that should exclude piracy.

Since the original author is unreachable, the maintainer these days is:
%endlatex
  \begin{quote}
    Ivan Andrus     \\
    E-mail: \texttt{<darthandrus@gmail.com>}
  \end{quote}
%endlatex

\medskip\noindent
Have fun.

\end{document}

% The "Make" target is my own.
% Local Variables:
% TeX-command-default: "Make"
% TeX-master: "ChkTeX.tex"
% End:
