-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathChkTeX.tex.in
1842 lines (1527 loc) · 72.3 KB
/
ChkTeX.tex.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
%%
%% ChkTeX v@PACKAGE_VERSION@, 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: <[email protected]>
%%
%% 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}
%latex
\usepackage{array, tabularx, verbatim, multicol}
\usepackage[T1]{fontenc}
\nonfrenchspacing
\newcounter{errornum}
\setcounter{errornum}{1}
%endlatex
\newcommand{\jtbt}{Jens~T. Berger~Thielemann}
\newcommand{\Cmd}[1]{``\texttt{#1}''}
\newcommand{\rsrc}{``\texttt{chktexrc}''}
\newcommand{\chktex}{Chk\TeX}
%latex
\newcolumntype{Y}{>{\raggedright\arraybackslash}X}
\newcommand{\fmted}[1]{%
{\noindent\large%
\begin{tabularx}{\linewidth}{lY}%
\bf Warning \theerrornum: & \texttt{#1}%
\end{tabularx}}\stepcounter{errornum}\nopagebreak[4]}
\newenvironment{errdesc}[1]{\noindent\fmted{#1}\begin{quote}}{\end{quote}%
\pagebreak[3]}
\newenvironment{html}{\comment}{\endcomment}
\newenvironment{rawhtml}{\comment}{\endcomment}
\makeatletter
\@namedef{errdesc*}#1{\begin{errdesc}{\textit{#1}}}
\@namedef{enderrdesc*}{\end{errdesc}}
\makeatother
\newenvironment{errexam}
{
\vskip 0pt plus 5pt
\begin{center}
}
{\end{center}}
\columnseprule 0.1pt
%!\newcommand{\BS}{\verb@\@}
%!\newcommand{\chktex}{ChkTeX}
%!\newcommand{\slash}{/}
%endlatex
\title{\chktex\ v@PACKAGE_VERSION@}
\author{Jens~T. Berger~Thielemann}
\date{\today}
\begin{document}
\maketitle
%latex
\newcommand{\BS}{\char`\\}
%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:
%latex
\begin{multicols}{2}
\begin{flushleft}
%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}
%latex
\end{flushleft}
\end{multicols}
%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 \[email protected]@ 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' behaviour by
reading/editing the \rsrc\ file.
%latex
\section{Usage}
\subsection{\chktex}
\subsubsection{Synopsis}
A UNIX-compliant template format follows:
\newcommand{\Group}[1]{\mbox{[#1]}}
\begin{tabularx}{.95\linewidth}{lY}
\texttt{chktex} & \ttfamily \Group{-hiqrW} \Group{-v[0-\dots]} \Group{-l
<rcfile>} \Group{-[wemn] <[1-42]|all>} \Group{-d[0-\ldots]} \Group{-p
<pseudoname>} \Group{-o <outputfile>} \Group{-[btxgI][0|1]}
file1 file2 \dots
\end{tabularx}
\subsubsection{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 \Cmd{-v0qb0w2} is the
same as saying \Cmd{-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[\texttt{-h [-{}-help]}] Gives you a command summary.
\item[\texttt{-i [-{}-license]}] Shows distribution information.
\item[\texttt{-l [-{}-localrc]}] Reads 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 \texttt{-g}.
\item[\texttt{-r [-{}-reset]}] This will reset all settings to their
defaults. This may be useful if you use the \texttt{CMDLINE}
directive in your \rsrc\ file, and wish to do something
unusual.
\item[\texttt{-d [-{}-debug]}] Needs a numeric argument; a bitmask
telling what to output. The values below may be added in order
to output multiple debugging info.
\begin{tabularx}\linewidth{cX}
\bf Value & \bf Dumps\ldots\\
1 & All warnings available and their current status. \\
2 & Statistics for all lists in the resource file. \\
4 & The contents of all lists in the resource file. \\
8 & Misc.\ other status information. \\
16 & Run-time info (note that this isn't widely used). \\
\end{tabularx}
The info is produced after all switches and resource files have
been processed.
It is possible to install versions of \chktex\ that ignore this
flag; this means that it is not certain that this flag works.
\item[\texttt{-W [-{}-version]}] Displays version information, and exits.
\end{description}
\item[Muting warning messages:] Controls whether and in what form
error messages will appear. Usually they accept a specific warning
number (e.g.\ \Cmd{-w2}), but you may also say \Cmd{all} (e.g.\
\Cmd{-wall}) which does the operation on \emph{all} warnings.
\begin{description}
\item[\texttt{-w [-{}-warnon]}] Makes the message number passed as
parameter a warning and turns it on.
\item[\texttt{-e [-{}-erroron]}] Makes the message number passed as
parameter an error and turns it on.
\item[\texttt{-m [-{}-msgon]}] Makes the message number passed as
parameter a message and turns it on. Messages are not counted.
\item[\texttt{-n [-{}-nowarn]}] Turns the warning/error number passed
as a parameter off.
\item[\texttt{-L [-{}-nolinesupp]}] Turns off suppression of messages
on a per line basis. This is meant to be used to ensure that no new
errors have crept into a document while editing.
\end{description}
\item[Output control flags:] Determines the appearance and
destination of the error reports.
\begin{description}
\item[\texttt{-q [-{}-quiet]}] Shuts up about copyright information.
\item[\texttt{-o [-{}-output]}] Normally, all errors are piped to \texttt{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 and similar will as as
always be sent to \texttt{stderr}. If a file with the name given
already exists, it will be renamed to \Cmd{foobar.bak}
(\Cmd{foobar.\$cl} under MS-DOS), \Cmd{foobar} being the name of
the file. See also \Cmd{-b}.
\item[\texttt{-v [-{}-verbosity]}] Specifies how much and how you
wish the error reports to be displayed. This is specified in the
\rsrc\ file; we'll list the default values below. If you wish,
you may thus edit the \rsrc\ file to add or modify new formats.
The default is mode 1 (that is, the \emph{second} entry in the
\rsrc\ file), using \texttt{-v} without any parameter will give you
mode 2.
\begin{description}
\item[0] Will show the information in a way that should be
suitable for further parsing by \texttt{awk}, \texttt{sed} or
similar. The format is as follows:
\begin{verbatim}
File:Line:Column:Warning number:Warning message
\end{verbatim}
The colons may be replaced with another string; use the
\verb@-s@ switch for this.
As the program does not output all errors in quite order, this
output format is also suitable for piping through \Cmd{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 \Cmd{ChkTeX.h}
at compilation time. UNIX boxes, however, will find the
information automatically.
\item[3] Shows the information suitable for parsing by Emacs;
this is the same format as \texttt{lacheck} uses. More formally,
it is the following:
\begin{verbatim}
"File", line Line: Warning message
\end{verbatim}
To utilize this, type \verb@M-x compile RET@. Delete whatever
is written in the minibuffer, and type
\verb@chktex -v3 texfile.tex@, and you should be able to
browse through the
error messages. Use \verb@C-x `@ to parse the messages.
\item[4] More or less the same as \verb@-v3@, but also includes
information on where the error actually was found. Takes somewhat
longer time to parse, but much more informative in use.
\end{description}
\item[\texttt{-f [-{}-format]}] Specifies the format of the output.
This is done using a format similar to \Cmd{printf()}, where we
support the specifiers listed below.
\smallskip
\newcommand{\Pf}[1]{\texttt{\%#1} &}
\begin{tabularx}{\linewidth}{cX}
\bf Code & \bf Description \\
\Pf{b} String to print \textbf{b}etween fields (from \texttt{-s}
option).\\
\Pf{c} \textbf{C}olumn position of error. \\
\Pf{d} Length of error (\textbf{d}igit). \\
\Pf{f} Current \textbf{f}ilename.\\
\Pf{i} Turn on \textbf{i}nverse printing mode.\\
\Pf{I} Turn off \textbf{i}nverse printing mode.\\
\Pf{k} \textbf{k}ind of error (warning, error, message).\\
\Pf{l} \textbf{l}ine number of error.\\
\Pf{m} Warning \textbf{m}essage.\\
\Pf{n} Warning \textbf{n}umber.\\
\Pf{u} An \textbf{u}nderlining line (like the one which
appears when using \Cmd{-v1}).\\
\Pf{r} Part of line in front of error ($\mbox{`S'} -
1$).\\
\Pf{s} Part of line which contains error (\textbf{s}tring).\\
\Pf{t} Part of line after error ($\mbox{`S'} + 1$).
\end{tabularx}
\smallskip
Other characters will be passed literally; thus you can say
\Cmd{\%\%} to achieve a single percent sign in the output.
Please note that we may introduce other specifiers in the future,
so don't abuse this feature for other characters.
Also, note that we do \emph{not} support field lengths (yet).
This may come in the future, if I get the time\dots
The \texttt{-v} command is implemented by indexing into the \rsrc\
file; read that for seeing how each format is implemented. If
you find yourself using a particular format often by using the
-f switch, consider putting it in the \rsrc\ file instead.
\item[\texttt{-V [-{}-pipeverb]}] Which entry we'll use in the \rsrc\
file whenever \texttt{stdout} isn't a terminal.
The default is to use the same mode as specified with the
\texttt{-v} switch; using \texttt{-V} without any parameter will give you
mode 1.
This switch was implemented because GNU less has problems with
the escape codes \chktex\ uses for displaying inverse text.
Under UNIX, there's another way around, though, which is slightly
more elegant. Add the following line to your \Cmd{.envir} file:
\begin{verbatim}
setenv LESS -r
\end{verbatim}
\item[\texttt{-p [-{}-pseudoname]}] With this switch, you can provide
the filename which will be used when we report the errors. This
may be useful in scripts, especially when doing pipes. It is in
other words similar to C's \verb@#line@ directive.
We will only assume this name for the uppermost file; files that
this one in turn \verb@\@\verb@input@ are presented under their original
names. This seems most logical to me.
\item[\texttt{-s [-{}-splitchar]}] String to use instead of the
colons when doing \texttt{-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 \texttt{0}, the feature will
be disabled, if it is \texttt{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[\texttt{-b [-{}-backup]}] If you use the \texttt{-o} switch, and the
named outputfile exists, it will be renamed to \texttt{filename.bak}.
\item[\texttt{-I [-{}-inputfiles]}] Execute \verb@\@\verb@input@
statements; e.g.\ include the file in the input. Our input parsing
does of course nest; we use an input-stack to keep track of this.
\item[\texttt{-H [-{}-headererr]}] Show errors found in front of the
\verb@\begin{document}@ line. Some people keep \emph{lots} of
pure \TeX\ code there, which errors can't be detected reliably
(in other words, we will in most cases just produce a lot of
garbage).
\item[\texttt{-g [-{}-globalrc]}] Read in the global resource file. This
switch may be useful together with the \texttt{-l} option.
\item[\texttt{-t [-{}-tictoc]}] Display a twirling baton, to show that
we're working. \texttt{-v0} does an \texttt{-t0}, too, as it assumes
that the user then uses the program non-interactively. This is
now a no-op.
\item[\texttt{-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}
If you don't specify any input \LaTeX-files on the commandline, we'll
read from \texttt{stdin}. To abort \texttt{stdin} input, press the
following keycombinations:
\smallskip
\begin{tabular}{ll}
\bf Machine & \bf Key-combination \\
UNIX & $\fbox{\texttt{Ctrl}} + \fbox{\texttt{D}}$ \\
MS-DOS & $\fbox{\texttt{Ctrl}} + \fbox{Z}$, followed by return.
\end{tabular}
\smallskip
By default, we use GNU's \Cmd{getopt()} routine.
\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 \Cmd{POSIXLY\_CORRECT}.
\item The special argument \Cmd{-{}-} forces an end of
option-scanning.
\item Long-named options begin with \Cmd{-{}-} instead of \Cmd{-}.
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 \Cmd{=}, or else the in next argument.
\end{itemize}
\subsubsection{The \rsrc\ file}
You should also take a look at the \rsrc\ file. As it is
self-documenting, you should be able to get the meaning of each
keyword by simply reading the file. In fact, since not all options
are described in this documentation it is necessary that you read
the \rsrc\ file in order to understand them all. The method for
\emph{finding it} has grown rather complex. An outline is given below.
If \chktex\ finds multiple files when searching, each and every one
will be read in the order specified below. The \Cmd{Keyword = \{ item
item \dots \}} may thus be necessary to reset previously defined
lists.
In this list, \Cmd{\$foo} is assumed to be the environment variable
\Cmd{foo}:
\begin{enumerate}
\item First, we'll take a look at the directory which was specified as
\Cmd{DATADIR} during compilation. On UNIX boxes, this usually
evaluates to something similar to
\Cmd{/usr/local/share/chktexrc}, under MS-DOS it is set
to \Cmd{\BS{}emtex\BS{}data\BS{}chktexrc}.
\item Look in the following system directories:
\begin{tabular}{ll}
\bf Machine & \bf Directory \\
UNIX & \Cmd{\$HOME/.chktexrc} or \Cmd{\$LOGDIR/.chktexrc} \\
MSDOS & Program installation path
\end{tabular}
\item Look for it in the directory pointed to by an environment
variable, as specified in the table below:
\begin{tabularx}\linewidth{lY}
\bf Machine & \bf Directory \\
UNIX & \Cmd{\$CHKTEXRC/.chktexrc} \\
MSDOS & \Cmd{\$CHKTEXRC\BS{}chktexrc}, \Cmd{\$CHKTEX\_HOME\BS
chktexrc} or \Cmd{\$EMTEXDIR\BS{}data\BS{}chktexrc}
\end{tabularx}
\item Look for it in the current directory. On UNIX boxes,
we expect the filename to be \Cmd{.chktexrc}; on other machines
\Cmd{chktexrc}.
\end{enumerate}
If you for some reason wish to undo what the previous files may have
done, you may say \Cmd{CmdLine \{ -g0 -r \}} somewhere in the \rsrc\
file; this will reset all previous settings.
\subsubsection{Per Line and File Suppressions}
There are many cases in which \chktex{} will give a warning about a
construct which, although it usually indicates a mistake, is
intentional. In these cases it can be extremely annoying to have
this message appear everytime \chktex{} is run. For this reason you
can use \LaTeX{} comments to suppress a certain message on a single
line. This can be done by adding a (case-insensitive) comment at the
end of the line of the form
\begin{center}
\verb+% chktex ##+
\end{center}
where \verb+##+ is the number of the message to be suppressed.
For example the line
\begin{center}
\verb+$[0,\infty)$+\\*
\end{center}
will produce a warning (number 9) about mismatched \verb+]+ and \verb+)+.
However the lines
\begin{center}
\verb+$[0,\infty)$ % chktex 9+\\*
\verb+$[0,\infty)$ % ChkTeX 9+\\*
\end{center}
will not produce such a message. In this case, message number 17 will
still appear at the end, stating that the numbers of \verb+]+ and
\verb+)+ don't match for the entire file.
To suppress two different errors on the same line you will need two
instances of \verb+chktex+ in the comment. This format is a little
cumbersome, but it shouldn't be needed often, and hopefully will help
avoid accidental suppressions.
\begin{center}
\verb+Jordan--H\"older on $[0,\infty)$ % chktex 8 chktex 9+\\*
\end{center}
One problem inherent in line-by-line suppressions is that during editing
another error of the same type may creep into the same line. Therefore,
I suggest using the \texttt{-L} or \texttt{-{}-nolinesupp} option to
disallow line based suppressions once just before the document is finished.
At that point you should go back over all the warnings and decide if they
should be fixed.
In addition to line-specific suppressions, you can create a suppression which will be in effect for the remainder of the file.
This can be used, for example, to turn off warning 18 (about \verb+"+) in a file which uses a package (like \Cmd{babel}) where \verb+"+ is an active character.
The syntax is nearly the same, namely
\begin{center}
\verb+% chktex-file ##+
\end{center}
\subsubsection{Hints}
I've tried to collect some advice that may be useful --- if you have a
favourite hint, feel free to send it to me!
\begin{itemize}
\item If you use \Cmd{german.sty} or several of \Cmd{babel} languages
which use \verb+"+ as an active character; it may be wise to put \Cmd{-n18} in
the \Cmd{CmdLine} entry in the \rsrc\ file. This will probably reduce
the amount of false warnings significantly. Alternately, you can put
\verb+% chktex-file 18+ in your files which use one of these packages so
that other files will still have these checks performed.
\item Put \Cmd{-v} in the \Cmd{CmdLine} entry of the \rsrc\ file; this
makes the fancy printing the default.
\item If you're working on a large project, it may pay off to make a
local resource file which is included in addition to the global
one. In this one, add the necessary info to reduce the amount of
false warnings --- these usually don't do anything but hide the
real warnings.
\item Create a total ignore environment, which \chktex\ will ignore
completely. In here, you can place all that code which outsmarts
\chktex\ completely. For instance, add the following lines at the top
of your \LaTeX\ file:
\begin{verbatim}
% ChkTeX will ignore material within this environment
\newenvironment{ignore}{}{}
\end{verbatim}
In addition, you should add the item \Cmd{ignore} to the \Cmd{VerbEnvir}
entry in the \rsrc\ file.
\end{itemize}
\subsubsection{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 \Cmd{cover} utility I was able to make sure that
approximately 95\% of the code has actually been run successfully in the
final version. This does indeed leave some lines; most of these are
procedure terminating brackets or ``can't happen'' lines, though.
We've got some problems when isolating the arguments of a command.
Although improved, it will certainly fail in certain cases; \chktex\
can for instance not handle arguments stretching over two lines. This
also means that \Cmd{WIPEARG} entries in the \rsrc\ file will only
have the first half of their argument wiped if the argument stretches
over two lines. We will, however, take care not to wipe parenthesis
in such cases, in order to avoid false warnings.
Long lines are broken up into chunks and handled separately. The exact
length is platform dependent, though is guaranteed to be at least 256 bytes.
The first portions of the line will have line numbers that are 1 less than
they should be. Some errors can be missed and some can be added erroneously.
A warning will be issued if lines are too long.
Before submitting a bug report, please first see whether the problem can be
solved by editing the \rsrc\ file appropriately.
\subsection{ChkWEB}
This shell script is provided for checking CWEB files. The template is
as follows:
\begin{verbatim}
chkweb [options] file1 file2 ...
\end{verbatim}
As you may see from the script, it is only a trivial interface towards
\texttt{deweb} and \chktex. It does not support any individual options
on the command line --- all options found will be passed onto \chktex.
If \Cmd{-{}-} or a filename is found, the remaining parameters will be
ignored.
The only real intelligence it features is that it will try to append
\[email protected]@ to filenames it can't find.
If no filenames are given, we will read from \texttt{stdin}.
\subsection{DeWEB}
This program strips away C code and CWEB commands from CWEB sources.
It is called with the following synopsis:
\begin{verbatim}
deweb file1 file2 ...
\end{verbatim}
\texttt{deweb} filters away all C \&\ CWEB commands from a CWEB source
code. This leaves only the \LaTeX\ code. This stripped code, in turn,
may then be passed to a suitable syntax checker for \LaTeX, like
\chktex\ and \texttt{lacheck}, or spell-checkers like \texttt{ispell}.
When \texttt{deweb} strips away the C code from your CWEB source, it tries to
preserve line breaks. This means that the error reports from {\it your
favorite tool\/} will be correct regarding to line numbers. In most
cases, the column position will also be correct. This significantly
simplifies finding the errors in the \LaTeX\ source (in contrast to the
output from \texttt{cweave}, which output is truly difficult to figure
anything out from).
\texttt{deweb} accepts a list of filenames on the argument line, and will send
its output to \texttt{stdout}. If no filenames are given, it will read from
stdin, acting as a filter. No options are currently accepted.
Macho users may try to pipe the output from \texttt{deweb} directly into
\LaTeX, theoretically, this should work. This would ease the debugging of
the \LaTeX\ code significantly, as when \LaTeX\ complains about wrong
syntax, you'll be able to find the erroneous line much more easily. Don't
expect that the output looks very much like the final one, though.
\texttt{deweb} should now understand all correct \texttt{CWEB} opcodes. If it
complains about not understanding a correct opcode, please inform the
author.
\subsubsection{Bugs}
\texttt{deweb} will not even \emph{compile} under Perl versions before perl
v5. Unfortunately, this means that we can't even tell the user why we
failed; Perl will just complain about not being able to compile the
regexps.
\section{Explanation of error messages}
Below is a description of all error-messages \chktex\ outputs.
Error messages set in {\it italic type\/} are turned off by default.
Where margin paragraphs are listed in the text, they refer to the
keyword in the \rsrc\ file which controls the discussed warning.
\newcommand\Keyword[1]{\marginpar{\texttt{\hfill\\ #1}}}
\smallskip\pagebreak[2]
\Keyword{Silent}
\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.
You can also specify regular expressions to match commands which can
safely be terminated with a space. They are specified in the
\rsrc\ file in \texttt{[]}, which in some other cases is used to
indicate case-insensitive matching. This is used for example to
support the \verb+\startXXX+ macros of Con\TeX t.
\begin{errexam}
\verb@\LaTeX@\underline{\tt\ }\verb@is a typesetter.@ \\*
\LaTeX is a typesetter. \\*
\smallskip
\verb@\LaTeX\ is a typesetter.@ \\*
\LaTeX\ is a typesetter. \\*
\end{errexam}
\end{errdesc}
\Keyword{Linker}
\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{\tt\ }\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{\tt\ }\verb@[(ab)^{-1}]@\underline{\tt\ }\verb@\^{-2}$@ \\*
$[(ab)^{-1}]^{-2}$ \\*
\smallskip
\verb@${[{(ab)}^{-1}]}^{-2}$@ \\*
${[(ab)^{-1}]}^{-2}$ \\*
\end{errexam}
\end{errdesc}
\Keyword{Italic\\ItalCmd\\NonItalic}
\begin{errdesc}{Italic correction (`\BS/') 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\BS/}\verb@ example@ \\*
This is an\/ example. \\*
\smallskip
\verb@This is an example.@ \\*
This is an example. \\*
\end{errexam}
\end{errdesc}
\Keyword{Italic\\ItalCmd\\NonItalic}
\begin{errdesc}{Italic correction (`\BS/') 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\BS/}\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}
\Keyword{Italic\\ItalCmd\\NonItalic}
\begin{errdesc}{No italic correction (`\BS/') 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 \Cmd{em} option,
you may ignore this warning.
\begin{errexam}
\verb@This {\it example@\underline{\tt\ }\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}
\Keyword{IJAccent}
\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}
\Keyword{HyphDash\\NumDash\\WordDash\\DashExcpt}
\begin{errdesc}{Wrong length of dash may have been used.}
This warning suggests that a wrong number of dashes may have been
used. It does this by classifying the dash according to the the
character in front and after the dashes.
If they are of the same type, \chktex\ will determine which keyword
to use in the \rsrc\ file. If not, it will shut up and accept that
it doesn't know.
\begin{tabular}{ll}
\bf Character type & \bf Keyword in \rsrc\ file \\*
Space & \texttt{WordDash} \\*
Number & \texttt{NumDash} \\*
Alphabetic character & \texttt{HyphDash} \\*
\end{tabular}
This is more or less correct, according to my references. One
complication is that most often a hyphen (single dash) is desired
between letters, but occasionally an n-dash (double dash) is
required. This is the case for theorems named after two people