%% %% ChkTeX v1.2, LaTeX documentation for ChkTeX program. %% Copyright (C) 1995 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., 675 Mass Ave, Cambridge, MA 02139, USA. %% %% Contact the author at: %% Jens Berger %% Spektrumvn. 4 %% N-0666 Oslo %% Norway %% E-mail: %% %% 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. %% \documentstyle[a4, array, tabularx, isolatin, verbatim, em]{article} \def\jtbt{Jens~T. Berger~Thielemann} \newcolumntype{Y}{>{\raggedright\arraybackslash}X} \newcounter{errornum} \setcounter{errornum}{1} \def\theerrornum{\arabic{errornum}} \newenvironment{errdesc}[1] { \vfil \noindent \begin{tabularx}{\textwidth}{lY} \bf \large Warning/error \theerrornum: & \tt\large #1 \\ \end{tabularx} \stepcounter{errornum} \begin{quote} } {\end{quote}} \newenvironment{errexam} { \begin{samepage} Example:\\ \vspace{-0.5cm} \begin{center} } { \end{center} \end{samepage} } \newcommand{\chktex}{Chk\TeX} \title{\chktex\ v1.2} \author{\jtbt} \date{\today} \def\rsrc{``{\tt .chktexrc}''} \begin{document} \maketitle \section{Introduction} This program was written in frustration of that some constructs in \LaTeX\ are sometimes non-intuitive, and easy to forget. It is {\em 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. While written on an Amiga, it is written in ANSI C, so you can use this at your UN*X/MSDOS/whatever site also. Full source included. The program also supports output formats suitable for further processing by editors or other programs, making errors easy to catch. An ARexx script for interfacing with SCMSG (and via that, other editors) is included. A special script for CygnusED and an experimental script for GoldED is included. % In the Amiga version, however, the program is localized. The % localization was created by using C2LOCAL, the automatically generated % source code is not included. A catalog for Norwegian is included, % plus a skeleton for further translation. The program itself does not have any machine requirements, an Amiga compiled version is included which should work on all Amigas. Of course, you'll need ARexx and SCMSG to benefit from the ARexx scripts, though. % You'll % get translations only on 2.1+, though. \section{Legal stuff} \chktex, its documentation and its installations scripts are copyright \copyright\ 1995--96 \jtbt. 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. \\ 675 Mass Ave \\ Cambridge \\ MA 02139 \\ USA \end{quote} \section{Installation} Amiga users should use the supplied Installer installation script. If you are using a different platform, compile and link all\ .c files, and move the binary to a suitable place. The \rsrc\ file should be moved to your \verb@$HOME@ directory on UNIX; other platforms may put its directory path in a environment variable named {\tt CHKTEXRC}. You may wish to read section~\ref{porting} first. After doing this, you may enhance \chktex' behaviour by reading/editing the \rsrc\ file. \section{New features} Changes from v1.1: \begin{description} \item[] {\bf Added:} \begin{itemize} \item Warns about `\verb@"@' and `\verb@´@' now --- advices about use of better accenting characters. \item The user may now specify own patterns that will be searched and warned about. \item You may now make it dump comments; sometimes useful (default: off). \item Will now search for user-specified patterns. \item 5--6 other new warnings. We've got a total of 25 warnings now! \item Wildcard matching (Amiga only). Will now match file patterns internally, which should save a lot of work. This is, however, platform-specific code --- on UNIX boxes this is done by the shell. \item ``{\tt chktex ?}'' now gives help, too. \item Command-line options may be specified globally in the \rsrc\ file. \item You may now use another string than a single colon to split fields in the {\tt -v0} output format. This will solve problems on machines using colons in path names. \item VT100 and VT102 support added. {\tt -v2} switch now works on such terminals, too. Checks {\tt\$TERM} environment variable. \item ``Debugging'' mode. \item An ARexx script for interfacing with SCMSG, the SAS/C message browser. \item A Perl script which transforms the \verb@-v0@ output into a UNIX-error like. \end{itemize} \item[] {\bf Modified:} \begin{itemize} \item More intelligent \rsrc\ format; it is now in a more shell/free-form style, thus more readable. Introduced C-like escape codes (using `{\tt !}' as escape character instead of `{\tt\string\ }'). \item More logical option names \& better option parsing. \item A few more options, too\dots \item Dash-checking has been improved. \item Better error reporting of program errors; routines have been rewritten. \item ASCII version of the document is discontinued; users needing this product are assumed to possess \LaTeX\ (or at least, a DVI/PS viewer). \item Localization has also been discontinued\dots\ :-/ Too much fuzz when nobody is willing to write translations. \end{itemize} \end{description} \section{Usage} Unfortunately, the template has changed {\em slightly\/} from v1.1 to provide a more logical format. Thus, a {\em very\/} few scripts may be incompatible, more precisely those using either the {\tt -g}, {\tt -b}, {\tt -x} or {\tt -t} switches in peculiar ways (saying these twice on a commandline is now the same as not saying them at all). This problem is assumed to be neglible. \begin{description} \item[\bf Template:] A UNIX-compliant template format follows: \begin{tabularx}{\textwidth}{lY} \tt chktex & \tt [-hiqr] [-v[0|1|2]] [-l ] \\ & \tt [-[w|e|m|n] <[1-25]>] [-d ] \\ & \tt [-o ] [-b[0|1]] [-t[0|1]] \\ & \tt [-x[0|1]] [-g[0|1]] \end{tabularx} \item[\bf Options:] These are the options \chktex\ currently accepts. Please note that single-lettered options requiring a numerical or no argument may be concatenated. E.g.\ saying ``{\tt -v0qb0w2}'' is the same as saying ``{\tt -v0 -q -b0 -w2}'', except for being less to type. Enough general talk; here's a rather detailed description of all options: \begin{description} \item[Misc.\ options:] General options which aren't related to some specific subpart of \chktex. \begin{description} \item[{\tt -h [--help]}] Gives you a command summary. \item[{\tt -i [--license]}] Shows distribution information. \item[{\tt -l [--localrc]}] Will read a resource-file formatted as the global resource-file \rsrc, in addition to the global resource-file. This option needs the name of the resource-file as a parameter. See also {\tt -g}. \item[{\tt -r [--reset]}] This will reset all settings to their defaults. This may be useful if you use the {\tt CMDLINE} directive in your \rsrc\ file, and wish to do something unusual. \item[{\tt -d [--debug]}] Given a numeric argument above zero, it will output some status information during run-time. \end{description} \item[Muting warning messages:] Controls whether and in what form error messages will appear. \begin{description} \item[{\tt -w [--warnon]}] Makes the message number passed as parameter a warning and turns it on. \item[{\tt -e [--erroron]}] Makes the message number passed as parameter an error and turns it on. \item[{\tt -m [--msgon]}] Makes the message number passed as parameter a message and turns it on. Messages are not counted. \item[{\tt -n [--nowarn]}] Turns the warning/error number passed as a parameter off. \end{description} \item[Output control flags:] Determines the appearance and destination of the error reports. \begin{description} \item[{\tt -q [--quiet]}] Shuts up about copyright information. \item[{\tt -o [--output]}] Normally, all errors are piped to stdout. Using this option with a parameter, errors will be sent to the named file instead. Only information relative to the \LaTeX\ file will be sent to that file. Memory problems, etc., will as as always be sent to {\tt stderr}. If a file with the name given already exists, it will be renamed to `{\tt foobar.bak}', {\tt foobar} being the name of the file. See also {\tt -b}. \item[{\tt -v [--verbosity]}] Specifies how much and how you wish the error reports to be displayed. This option currently accepts the following numerical levels: \begin{description} \item[0] Will show the information in a way that should be suitable for further parsing by {\tt awk}, {\tt sed} or similar. The format is as follows: \begin{quote} {\tt File:Line:Column:Warning number:Warning message} \end{quote} The colons may be replaced with another string; use the \verb@-s@ switch for this. This format will also turn off any twirling baton's, and other things which make the program unsuitable for pipes and batch scripts. As the program does yet not output all errors in quite order, this output format is also suitable for piping through `{\tt sort}'. \item[1] Shows the information in a way which is more comprehensible for humans, but which still doesn't need anything but a glass tty. \item[2] Shows the information in a fancy way, using escape codes and stuff. It is the indeed most readable of all modes; however, it needs proper set up of the `{\tt chktex.h}' file. \end{description} The default is mode 1, using {\tt -v} without any parameter will give you mode 2. \item[{\tt -s [--splitchar]}] String to use instead of the colons when doing {\tt -v0}; e.g.\ this string will be output between the fields. \end{description} \item[Boolean switches:] Common for all of these are that they take an optional parameter. If it is {\tt 0}, the feature will be disabled, if it is {\tt 1}, it will be enabled. All these features are on by default; and are toggled if you don't give any parameter. \begin{description} \item[{\tt -b [--backup]}] If you use the {\tt -o} switch, and the named outputfile exists, it will be renamed to {\tt filename.bak}. \item[{\tt -g [--globalrc]}] Read in the global resource file. This switch may be useful together with the {\tt -l} option. \item[{\tt -t [--tictoc]}] Display a twirling baton, to show that we're working. {\tt -v0} does an {\tt -t0}, too, as it assumes that the user then uses the program non-interactively. \item[{\tt -x [--wipeverb]}] Ignore the `\verb@\verb@' command found within the \LaTeX\ file and its argument is completely by the checking routines. This is done by simply overwriting them. If you somehow don't like that (for instance, you would like to count brackets inside those commands, too), use this switch. \end{description} \end{description} \end{description} The parameters {\tt -m}, {\tt -w}, {\tt -e} and {\tt -n} may need some further explanation. With these it is possible to control muting of certain warnings. Currently, there is no real difference between errors and warnings, except that they are counted separately. If you don't specify any input \LaTeX-files on the commandline, we'll read from {\tt stdin}. To abort {\tt stdin} input on the Amiga, press \fbox{\tt Ctrl} + \fbox{\tt\string\ }. By default, we're using the 1994 version of GNU's {\tt getopt()} routine. For those of you who have only used the Amiga's ReadArgs(), here are some quick instructions: \begin{itemize} \item Options may be given in any order; the names of the \LaTeX-files do not have to be the last arguments. This behaviour may be turned off by creating an environment variable named `\verb@POSIXLY_CORRECT@'. \item The special argument `\verb@--@' forces an end of option-scanning. \item Long-named options begin with `\verb@--@' instead of `\verb@-@'. Their names may be abbreviated as long as the abbreviation is unique or is an exact match for some defined option. If they have an argument, it follows the option name in the argument, separated from the option name by a `=', or else the in next argument. \end{itemize} You should also take a look at the \rsrc\ file. The method for finding has been changed, it is now done as follows: \begin{enumerate} \item Look for it in the current directory. \item Look for it in the directory pointed to by the environment variable {\tt CHKTEXRC}. \item Look in the following directories: \begin{tabular}{ll} \bf Machine & \bf Directory \\ 2.04+ Amiga & {\tt ENV:} \\ 1.3 Amiga & {\tt S:} \\ UNIX & {\tt \$HOME} \\ \end{tabular} \end{enumerate} It should be rather self-explanatory, and should help you customize the program to your own needs. \section{Explanation of error messages} \begin{errdesc}{Command terminated with space.} You tried to terminate a command with a blank space. Usually, this is an error as these are ignored by \LaTeX. In most cases, you would like to have a real space there. \begin{errexam} \verb@\LaTeX@\underline{ }\verb@is a typesetter.@ \\ \LaTeX is a typesetter. \\ \smallskip \verb@\LaTeX\ is a typesetter.@ \\ \LaTeX\ is a typesetter. \\ \end{errexam} \end{errdesc} \begin{errdesc}{Non-breaking space (`\~{ }') should have been used.} When reading a document, it is not very pretty when references are split across lines. If you use the \verb@~@ character, \LaTeX\ will assign a very high penalty for splitting a line at that point. \chktex\ issues this warning if you have forgot to do this. \begin{errexam} \verb@Please refer to figure@\underline{ }\verb@\ref{foo}.@ \\ Please refer to figure 11. \\ % Gotta cheat here! :) \smallskip \verb@Please refer to figure~\ref{foo}.@ \\ Please refer to figure~11. \\ \end{errexam} \end{errdesc} \begin{errdesc}{You should enclose the previous parenthesis with `\{\}'.} This is a warning which you may ignore, but for maximum aestethic pleasure, you should enclose your bracket characters with `\{\}'s. \begin{errexam} \verb@$@\underline{ }\verb@[(ab)^{-1}]@\underline{ }\verb@\^{-2}$@ \\ $[(ab)^{-1}]^{-2}$ \\ \smallskip \verb@${[{(ab)}^{-1}]}^{-2}$@ \\ ${[(ab)^{-1}]}^{-2}$ \\ \end{errexam} \end{errdesc} \begin{errdesc}{Italic correction (`{\string\/}') found in non-italic buffer.} If you try to use the \verb@\/@ command when \chktex\ believes that the buffer is not outputted as italic, you'll get this warning. \begin{errexam} \verb@This is an@\underline{\tt\string\/}\verb@ example@ \\ This is an\/ example. \\ \smallskip \verb@This is an example.@ \\ This is an example. \\ \end{errexam} \end{errdesc} \begin{errdesc}{Italic correction (`{\tt\string\/}') found more than once.} If the buffer is italic, and you try to use the \verb@\/@ command more than once, you'll get this warning. \begin{errexam} \verb@This {\it example\/@\underline{\tt\string\/}\verb@} is not amusing.@ \\ This {\it example\/\/} is not amusing. \\ \smallskip \verb@This {\it example\/} is not amusing.@ \\ This {\it example\/} is not amusing. \\ \end{errexam} \end{errdesc} \begin{errdesc}{No italic correction (`{\tt\string\/}') found.} You get this error if \chktex\ believes that you are switching from italic to non-italic, and you've forgot to use the \verb@\/@ command to insert that extra little spacing. If you use the {\tt em} option, you may ignore this warning. \begin{errexam} \verb@This {\it example@\underline{ }\verb@} is not amusing, either.@ \\ This {\it example} is not amusing, either. \\ \smallskip \verb@This {\it example\/} is not amusing, either.@ \\ This {\it example\/} is not amusing, either. \\ \end{errexam} \end{errdesc} \begin{errdesc}{Accent command `command' needs use of `command'.} If you're using accenting commands, `i' and `j' should lose their dots before they get accented. This is accomplished by using the \verb@\i@, \verb@\j@, \verb@\imath@ and \verb@\jmath@ command. \begin{errexam} \verb@This is an example of use of accents: \'{@\underline{\tt i}\verb@}.@ \\ This is an example of use of accents: \'{i}. \\ \smallskip \verb@This is an example of use of accents: \'{\i}.@ \\ This is an example of use of accents: \'{\i}. \\ \end{errexam} \end{errdesc} \begin{errdesc}{Wrong length of dash may have been used.} This warning suggests that a wrong number of dashes may have been used. This check has now gotten somewhat better than previous version. It will now check the both the character in front and after the dashes. If they are of the same type, \chktex\ will use the table below to determine how many dashes there should be; if not, it will shut up and accept that it doesn't know. \begin{tabular}{ll} \bf Character type & \bf \# of dashes \\ Space & 3 \\ Number & 2 \\ Alphabetic character & 1 \\ \end{tabular} This is more or less correct, according to my references. Hopefully this check can be even more improved (suggestions?). \begin{errexam} \verb@It wasn't anything @\underline{\tt-}\verb@ just a 2@\underline {\tt---}\verb@3 star@\underline{\tt--}\verb@shots.@ \\ It wasn't anything - just a 2---3 star--shots. \\ \smallskip \verb@It wasn't anything --- just a 2--3 star-shots@ \\ It wasn't anything --- just a 2--3 star-shots. \\ \end{errexam} \end{errdesc} \begin{errdesc}{`character' expected, found `character'.} You get this warning when you try to mix brackets --- \chktex\ expect to find matching brackets in the same order as their opposites were found. While not an explicit error, it is usually a sign that something is wrong. \end{errdesc} \begin{errdesc}{Solo `character' found.} This warning is triggered if we find a single, {\em closing\/} bracket. While not an explicit error, it is usually a sign that something is wrong. \end{errdesc} \begin{errdesc}{You should use `{\tt\string\dots}' to achieve an ellipsis.} Simply typing three `.' in a row will not give a perfect spacing between the `.'s. The \verb@\dots@ is much more suitable for this. \begin{errexam} \verb@I don't know quite@\underline{\tt...}\verb@I think it's wrong.@ \\ I don't know quite...I think it's wrong. \\ \smallskip \verb@I don't know quite\dots I think it's wrong.@ \\ I don't know quite\dots I think it's wrong. \\ \end{errexam} \end{errdesc} \begin{errdesc}{Interword spacing (`{\tt\string\ }') should been used.} One of the specified abbreviations were found. Unless you have previously said \verb@\frenchspacing@, you'll have incorrect spacing, which one should avoid if possible. \begin{errexam} \verb@This is an example, i.e.@\underline{ }\verb@an demonstration.@ \\ This is an example, i.e. an demonstration. \\ \smallskip \verb@This is an example, i.e.\ an demonstration.@ \\ This is an example, i.e.\ an demonstration. \\ \end{errexam} \end{errdesc} \begin{errdesc}{Intersentence spacing (`{\tt\string\@}') should perhaps been used.} \LaTeX' detection of whether a period ends a sentence or not, is only based upon the character in front of the period. If it's uppercase, it assumes that it does not end a sentence. While this may be correct in many cases, it may be incorrect in others. \chktex\ thus outputs this warning in every such case. \begin{errexam} \verb@I've seen an UFO!@\underline{ }\verb@Right over there!@ \\ I've seen an UFO! Right over there! \\ \smallskip \verb+I've seen an UFO\@! Right over there!+ \\ I've seen an UFO\@! Right over there! \\ \end{errexam} \end{errdesc} \begin{errdesc}{Could not find argument for command `command'.} \chktex\ will in some cases need the argument of a function to detect an error. As \chktex\ currently processes the \LaTeX\ file on a line-by-line basis, it won't find the argument if the command which needed it was on the previous line. On the other hand, this {\em may\/} also be an error; you ought to check it to be safe. \begin{errexam} \verb@$\hat$@ \\ This will give a \LaTeX\ error\dots \\ \smallskip \verb@$\hat{a}$@ \\ $\hat{a}$ \\ \end{errexam} \end{errdesc} \begin{errdesc}{No match found for character `character'.} This warning is triggered if we find a single, {\em opening\/} bracket. While not an explicit error, it is usually a sign that something is wrong. \end{errdesc} \begin{errdesc}{Mathmode still on at end of LaTeX file.} This error is triggered if you at some point have turned on mathmode, and \chktex\ couldn't see that you remembered to turn it off. \end{errdesc} \begin{errdesc}{Number of `character' doesn't match the number of `character'!} Should be self-explanatory. \chktex\ didn't find the same number of an opening bracket as it found of a closing bracket. \end{errdesc} \begin{errdesc}{You should use either `` or '' as an alternative to `\,"\,'.} Self-explanatory. Look in the example, and you'll understand why. \begin{errexam} \verb@This is an @\underline{"}\verb@example@\underline{"} \\ This is an "example" \\ \smallskip \verb@This is an ``example''@ \\ This is an ``example'' \\ \end{errexam} \end{errdesc} \begin{errdesc}{You should use "'" (ASCII 39) instead of "'" (ASCII 180).} On some keyboards you might get the wrong quote. This quote looks, IMHO, {\em ugly\/} compared to the standard quotes, it doesn't even come out as a quote! Just see in the example. \begin{errexam} % Sorry, had to cheat - the 's aren't really 180's, they look like this: ´ \verb@``There@\underline{\tt '}\verb@s quotes and there@\underline{\tt '}\verb@s quotes@ \underline{\tt ''} \\ % '' ``There´s quotes and there´s quotes´´ \\ % '' \smallskip \verb@``There's quotes and there's quotes''@ \\ ``There's quotes and there's quotes'' \\ \end{errexam} \end{errdesc} \begin{errdesc}{User-specified pattern found.} A keyword you've specified using {\tt USERWARN} in the \rsrc\ file, has been found. \end{errdesc} \begin{errdesc}{This command might not be intended.} I implemented this because a friend of mine kept on making these mistakes. Easily done if you haven't gotten quite into the syntax of \LaTeX. \begin{errexam} \verb@\LaTeX\ is an extension of \TeX@\underline{\tt\string\.}\verb@ Right?@ \\ \LaTeX\ is an extension of \TeX\. Right? \\ \smallskip \verb@\LaTeX\ is an extension of \TeX. Right?@ \\ \LaTeX\ is an extension of \TeX. Right? \\ \end{errexam} \end{errdesc} \begin{errdesc}{Comment displayed.} This warning is by default off. If you turn it on, \chktex\ will dump all comments it finds, which in some cases is useful. I usually keep all my notes in the comments, and like to review them before I ship the final version. For commenting out parts of the document, the {\tt comment} environment is better suited. \end{errdesc} \begin{errdesc}{Either ''{\tt\string\,}' or '{\tt\string\,}'' will look better.} This error is generated whenever you try to typeset three quotes in a row; this will not look pretty, and one of them should be separated from the rest. \begin{errexam} \underline{\tt```}\verb@Hello', I heard him said'', she remembered.@ \\ ```Hello', I heard him said'', she remembered. \\ \smallskip \verb@``\,`Hello', I heard him said'', she remembered.@ \\ ``\,`Hello', I heard him said'', she remembered. \end{errexam} \end{errdesc} \begin{errdesc}{Delete this space to maintain correct pagereferences.} This message, issued when a space is found in front of a \verb@\index@, \verb@\label@ or similar command (can be set in the \rsrc\ file). Sometimes, this space may cause that the word and the index happens on separate pages, if a pagebreak happens just there. You might also use this warning to warn you about spaces in front of footnotes; however, the warning text may not be entirely correct then. \begin{errexam} \verb@Indexing text@\underline{ }\verb@\index{text} is fun!@ \\ \smallskip \verb@Indexing text\index{text} is fun!@ \\ \end{errexam} \end{errdesc} \begin{errdesc}{You might wish to put this between a pair of `\{\}'} This warning is given whenever \chktex\ finds a `{\tt \^{ }}' or a {\tt \_} followed by either two or more numberic digits or two or more alphabetic characters. In most situations, this means that you've forgotten some \{\}'s. \begin{errexam} \verb@$5\cdot10^@\underline{10}\verb@$@ \\ $5\cdot10^10$ \\ \smallskip \verb@$5\cdot10^{10}$@ \\ $5\cdot10^{10}$ \end{errexam} \end{errdesc} \section{Porting\label{porting}} Porting should be rather easy. However, to ensure that the porting proceeds painless, read the first lines of the `{\tt ChkTeX.h}' file. Not very much to do, and it will make life easier later. By the way: Set tabsize to 4. To compile it, just {\tt cd} to the {\tt source} directory, and compile and link all {\tt .c} files. On UNIX, type the following in a shell: \verb@gcc -o chktex *.c@ % You may also try to type `{\tt make}', however the {\tt stdarg.h} header % file seems to be rather uncommon in many C implementation. You may also wish to modify some of the routines in {\tt OpSys.c} --- unless you compiling the program on a UNIX or Amiga box. % If you wish to translate the strings used in the programs (should only % need 5 minutes of work), look in the Catalogs directory. Write your % translations in the file \verb@ChkTeX_locale.ct@, and mail it to me. I'll % include it in the next release. In advance, thanks for your support. % % Write your translations in the file \verb@ChkTeX_locale.ct@, and upload it % on AmiNet as `\verb@ChkTeX_???.lha@', where \verb@???@ is your language % code (Norway = NOR, Germany = GER, etc.). If you contact me in advance, % you'll also have the chance to get your file distributed with the main % \chktex\ archive. However, I'm always upgrading \chktex, so there may be % some changes/extra strings you have to translate. In advance, thanks for % your support. \section{Bugs} No fatal ones, I think, but the program currently has some problems when a \LaTeX\ command/parameter stretch over a two lines --- some extra spaces may be inserted into the input. I regard the program as fairly well tested; using the SAS/C {\tt cover} utility I was able to make sure that approximately 95\% of the code has actually been run successfully in the final version. Which leaves about 140 possibly buggy lines, most of these are procedure terminating brackets or `can't happen' lines, though. The detection of whether we're in math mode is not perfect. The program does not trust this check very much, either. The only codes which are recognized for getting in/out of math mode are: `\verb"$"', `\verb"$$"', `\verb"\("', `\verb"\)"', `\verb"\["' and `\verb"\]"'. Environments like \verb@\begin{displaymath}@, user-defined commands, etc., do thus not work. This is usually no problem, as it just creates a bit more warnings than needed. We've got some of the same problems when isolating the arguments of a command. Although improved, it will certainly fail in certain cases. Currently, this should cause nothing but a few extra warnings. Before submitting a bug report, please first see whether the problem can be solved by editing the \rsrc\ file appropiately. \section{Future plans} In a somewhat prioritized sequence, this is what I'd like to put into the think --- if I have the time. \begin{itemize} \item A {\tt configure} script for Unix boxes. \item An Emacs-hook which does much the same as the ARexx script. \item Probably some more warnings/errors; just have to think them out first. Suggestions are appreciated. I'll also see what I can implement from {\tt lacheck}, a similar program. Currently, I can think of the following: \begin{itemize} \item Quote nesting plus advices on which way quotes should be put. \item \verb@\ldots@ where \verb@\cdots@ should have been used, and vice versa. \item Space before footnotes (although this could be accomplished by editing the {\tt POSTLINK} field of the \rsrc\ file). \item Whitespace before punctuation. \item Support for \verb@\input@ --- read the file! \item Emacs compile mode compatible output (this can also be achieved by an appropiate filter, though). \item Support for some environments, like \verb@verbatim@, etc. \end{itemize} \item Get indentation consistent. I used to favour Allman style when doing C, however, I was forced to use K\&R style by Emacs' Perl-mode. And, as I must admit, it is more suitable once you've gotten into the braces. A result of this is that old code uses Allman style, while new code uses K\&R. \item Amiga Workbench support. It would be nice to put shift-clicking into the program; until this is implemented by someone, use the included ARexx program. \item Put some garbage collecting into the thing. We're buffering almost one half of the lines in the file for the length of the program. 99\% of these can be expunged {\em much\/} earlier. However, if you're dealing with so large files that you get out-of-mem errors, please consider splitting and using \verb@\input@ instead. Besides; if \chktex\ runs out of memory when processing your files, \LaTeX\ will indeed do the same! \item Rewrite the thing in Perl? Get regexp's for free, at least. \end{itemize} \section{Notes} \subsection{Wish to help?} As most other living creatures, I have only a limited amount of time. If you like \chktex\ and would like to help improving it, here's a few things I would like to receive. Think of it as giftware --- if you like it, you help improving it. The following ideas are given: \begin{itemize} \item If somebody would like to write an Emacs interface for \chktex, it would be {\em very\/} welcomed. I don't know Emacs-LISP, and haven't got the time to get into it. You should be able to model a gcc interface to suit your needs. To a certain degree, however, this is possible already. In Emacs, using AUC TeX, you can type \verb@M-x compile RET chktex.pl texfile.tex@, and you should be able to browse through the error messages. Then, \verb@C-x `@ to parse the messages. \item If you have access to a dictionary listing English abbreviations, I would appreciate an updated version of the \rsrc\ file with these filled in. In fact, if you update the \rsrc\ file in anyway that is not strictly local, I would appreciate to receive your updated version. \item ARexx interfaces for other editors are also welcomed; these should be rather fast to write. They should to the following: \begin{enumerate} \item Get the filename of the active file. \item If possible, save the file to disk if there has been any changes. \item Call the program `{\tt ChkTeX.rexx}' with the filename as the only parameter. \end{enumerate} \item If somebody out there actually possess (and uses) GoldED, it would be nice if they checked whether the ARexx script included actually work. If not, please send me a fixed copy; perhaps also one which supports point 2 above, too. I don't have GoldEd in my possession; the script was just modelled after Juergen Zeschky's, ({\tt }) PGP$\leftrightarrow$GoldED interface. \end{itemize} Of course, people doing any of this will be mentioned in the doc and readme, and thus receive eternal glory and appreciation. \subsection{Caps and stuff} This program uses the {\tt getopt()} routine, as supplied from GNU\@. The source included in this distribution has been modified slightly. To make the use of C2LOCAL easier, portions which were \verb@#ifdef@'ed out, have now been commented out. Where trademarks have been used, the author is aware of that they belong to someone, and has tried to stick to the original caps. \section{About the author} {\noindent\tt \#ifdef EGO\_TRIP} \begin{quote} A quick summary of who I am and what I do: I'm 20 years old, and live in Oslo, the capital of Norway. I'm currently studying maths and computer science at the University~of~Oslo; planning to get a degree within mathematical modelling, with a dash of physics and emphasing the computer part of the study. At home I now possess 4 computers, of which 1 is regular use: A vanilla Amiga 1200, expanded only by a HD\@. The others are a {\tt 80286} PC and an Amiga 500, both semi-out-of-order. The last one is a Commodore VIC-20, which for some peculiar reason never seems to be used. Most of the time in front of these computers (including SGI Indy's and SPARC stations at our university) is spent on C and shell programming, plus some textprocessing. I am also involved in writing the document for {\sc Isaac} --- Interactive Simulation as an Alternative to Advanced Calculations. This is planned to help newcomers to physics, by providing a computer program which enables one to simulate most experiments relating to classical mechanics. C and shell programming is not my only knowledge areas regarding computers, however. I write the following languages more or less: Perl, Motorola {\tt 68000} assembly code, ARexx, Simula, C++, \LaTeX, HTML, Amos Basic and Installer LISP\@. Once I also mastered Commodore Basic V2 (the one included with my VIC-20 :-) ). However, I also try to not to end up as a computer nerd. Thus, in addition to the obligatory (?) interest for computers, I am a scout. Still running into the woods, climbing the trees, falling down and climbing up once more, in other words. To be more specific, I am a now a troop leader for `Ulven' scoutgroup; Norwegian Scouts Association. I am also a active rover in `Vålerenga' scoutgroup. Certainly a lot more to tell; but I'll stop here before you fall asleep\dots \end{quote}\nopagebreak {\par\noindent\tt \#endif} \section{Thanks} The author wishes to thank Kasper B. Graversen, for lots of creative suggestions and improvements. Thanks also goes to Frank Luithle, being the only one writing a translation for v1.0. Unfortunately, he remained unreachable after that\dots :-/ \section{Contacting the author} I am currently hunting for a rather powerful wildcard pattern-matching/regular expressions routine; preferably one more or less equivalent to the one of {\tt csh}, AmigaOS' {\tt Match\-Pattern()} or similar. If you have access to a freely distributable version of such a routine, I would be pleased if you would mind contacting me at the below address. It is meant to be used in a future version of \chktex. If you wish to contact me for whatever reason (more tests, bug reports, suggestions, hellos, smiley's, etc.) or would like to participate in the development of \chktex, write to: \begin{quote} Jens Berger \\ Spektrumvn. 4 \\ N-0666 Oslo \\ Norway \\ E-mail: {\tt } \end{quote} Any signs of intelligent life is welcomed; that should exclude piracy. Have fun. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{comment} \def\eone{\medskip\hrule\smallskip\begin{center}} \def\etwo{\nopagebreak\end{center}\nopagebreak} \def\ethr{\nopagebreak\begin{center}\nopagebreak} \def\efou{\end{center}} \section{Errors searched for} Currently, it will catch the following errors, the error being underlined. There are a few more errors which are catched; see the error-reference for further information. \eone \verb@\LaTeX@\underline{\verb@ @}\verb@is a typesetting package.@ \etwo Most probably, you would like this to look like this: \ethr \verb@\LaTeX\ is a typesetting package.@ \efou This is the most common, and the most irritating errors of them all. You'll certainly save lots of time proof-reading for such errors! Still, an environment file tells ChkTeX which commands that may end with a normal space, like `\verb@\bf@' or similar, which don't produce any text output. In math mode, this checking is of course turned off. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@This is an example of use of accents: \'{@\underline{\verb@i@}\verb@}.@ \etwo This will not look pretty. It should rather be: \ethr \verb@This is an example of use of accents: \'{\i}.@ \efou % It does also try to differ between whether we're in math mode or not. It is possible to customize which functions which needs the use of \verb@\i@ or \verb@\j@. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@$@\underline{\verb@ @}\verb@[(ab)^{-1}]@\underline{\verb@ @}\verb@\^{-2}$@ \etwo Although the error is very small, things look better and are more readable like this: \ethr \verb@${[{(ab)}^{-1}]}^{-2}$@ \efou % We are, of course, also checking subscripts the same way. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@Please refer to figure@\underline{\verb@ @}\verb@\ref{foo}.@ \etwo This should rather look like this: \ethr \verb@Please refer to figure~\ref{foo}.@ \efou % An environment file tells \chktex\ which commands that should be prefaced with a non-breaking space. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@This is an example, i.e.@\underline{\verb@ @}\verb@an demonstration.@ \etwo This will cause incorrect spacing, and should be written as: \ethr \verb@This is an example, i.e.\ an demonstration.@ \efou %%S The abbrevs which you wish to search for, are of course kept in the very same env-file. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@I've seen an UFO!@\underline{\verb@ @}\verb@Right over there!@ \etwo Will once more cause incorrect spacing, it should read: \ethr \verb+I've seen an UFO\@! Right over there!+ \efou %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@I don't know quite@\underline{\verb@...@}\verb@I think it's wrong.@ \etwo This ellipsis will not look good. You should rather write: \ethr \verb@I don't know quite\dots I think it's wrong.@ \efou %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@It wasn't anything @\underline{\verb@-@}\verb@ just a 2@\underline {\verb@---@}\verb@3 star@\underline{\verb@--@}\verb@shots, or something else.@ \etwo In all cases, an incorrect dash-length was used, it should be like this: \ethr \verb@It wasn't anything --- just a 2--3 star-shots, or something else.@ \efou This check is rather vague, as it will only check the character in front of the dashes. It uses the following table: \begin{itemize} \item If the dashes are leaded by a space, there should be three `-'s. \item If the dashes are leaded by a digit, there should be two `-'s. \item If the dashes are leaded by a character, there should be one `-'. \end{itemize} This is more or less correct, according to my references. Hopefully this check can be improved (suggestions?). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \eone \verb@Sometimes, you have to {\em emphasise@\underline{\verb@ @}\verb@} what you mean.@ \etwo This will give incorrect spacing. While it does not look very bad when the italic group ends in a space, it should look like this: \ethr \verb@Sometimes, you have to {\em emphasise\/} what you mean.@ \efou The commands which turn italic on, are stored in a modifiable environment file. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \medskip \hrule \medskip Wherever `a space' is mentioned, we'll of course also detect tabs and other spacing characters recognized; you may customize this yourself. Look in the error descriptions for a better description of each error message. In addition, it will keep track of brackets characters (`\verb"{}[]()"'), and make sure that they match. Everything found is of course pumped nicely to {\tt stdout}, with line number and error position. To get a quick demonstration of \chktex' features, run it on the file `{\tt Test.tex}'. Although most of the file is nonsense in a \TeX nical manner (lots of pseudo-commands), it will show what \chktex\ has to offer. \end{comment} \end{document}