summaryrefslogtreecommitdiff
path: root/support/tex-it/texit.tex
blob: 0c13b51cd03212b3ad2eef4d1385c990ded9a21c (plain)
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
\documentstyle{article}
%
% If you don't have Anthony Bloesch's ``treetex.sty'' file, just remove
% that style option.  The ``right thing'' will happen when you process
% the document.

%% #!/usr/local/bin/perl
%% dependency on format file names...

\partopsep=0pt
\topsep=0pt
\parindent=0pt
\parskip=\baselineskip

\def\desctree{%
Consider a \LaTeX\footnote{There's nothing special about \LaTeX\ in this
example, it's just convienient to select the \LaTeX\ format because it has
support for bibliographies and indices built in.  Similar arguments can be
made about other formats with different arrangements of supporting files.}
document composed of a main file, \verb|main.tex|, and two included files,
\verb|chap1.tex| and \verb|chap2.tex|.  Assume that the document has a
bibliography and an index (\verb|main.bbl| and \verb|main.ind|).  The
bibliography is constructed from \verb|myrefs.bib| by Bib\TeX and the index is
constructed by MakeIndex from the \verb|main.idx| file produced by \TeX{}ing
the document.  
}

\def\maketree{%
Consider a \LaTeX\footnote{There's nothing special about \LaTeX\ in this
example, it's just convienient to select the \LaTeX\ format because it has
support for bibliographies and indices built in.  Similar arguments can be
made about other formats with different arrangements of supporting files.}
document composed of several files as shown in the diagram below.  Assume that
the bibliography (\verb|main.bbl|) is constructed from \verb|myrefs.bib| by
Bib\TeX and the index is constructed by MakeIndex from the \verb|main.idx|
file produced by \TeX{}ing the document.

\begin{center}
  \def\treefbox##1{\fbox{{\tt ##1}}}
  \begin{tree}{texittr}
    \rootnode{\treefbox{main.tex}}
    \treenode{nodeA}{root}{\treefbox{chap1.tex}}
    \treenode{nodeB}{root}{\treefbox{chap2.tex}}
    \treenode{nodeC}{root}{\treefbox{main.bbl}}
    \treenode{nodeD}{root}{\treefbox{main.ind}}
    \treenode{nodeE}{nodeC}{\treefbox{myrefs.bib}}
    \treenode{nodeF}{nodeE}{\treefbox{plain.bst}}
    \treenode{nodeG}{nodeD}{\treefbox{main.idx}}
  \end{tree}
\end{center}
}

% if you include the ``treetex'' style, you can have a nice drawing
% in your document.
\makeatletter
\@ifundefined{tree}{\let\drawdoc\desctree}{\let\drawdoc\maketree}
% something else while I've got the @ right...
\def\@listI{\leftmargin\leftmargini \parsep 4\p@ plus2\p@ minus\p@
\topsep 0\p@ plus0\p@ minus0\p@
\itemsep 4\p@ plus2\p@ minus\p@}
\makeatother

\title{TeXit \\ An intelligent script for running \TeX %
       \\ \ \\ {\small Version 1.29}}
\author{Norman Walsh \\ {\tt walsh@cs.umass.edu}}
\date{August 16, 1993}

\begin{document}

\maketitle

\section{What is TeXit?}

TeXit is a Perl script designed to automate the task of processing documents
with \TeX.  It runs \TeX\ with the correct format and tries to intelligently
determine when \TeX\ needs to be run a second, or even third, time in order
to get correctly typeset output.

`Out of the box', TeXit is configured to recognize \LaTeX, Plain \TeX, and
Texinfo files, but it can easily be extended to other formats.  One of the
nice features of TeXit is that you can provide document-specific ``rules'' to
determine how many times \TeX\ needs to be run.

By the way, I tried to make a ``minimal'' TeXit and decided it wasn't worth
it.  The difference in startup speed was too small to justify the expense
of maintaining two versions.  Honest.

This document describes TeXit, but you should also look at the
``\verb|texit.pl|'' file.  I tried to put informative comments next to all of
the variables that you might want to change.  If you do want to change them,
{\em do it in an initialization file} (see Section~\ref{sec:init}).  {\bf Don't
change the script!}

\section{Legal Mumbo-Jumbo}

TeXit is distributed under the terms of the GNU General Public License,
version 2 or later.

Use at your own risk.  I take no responsibility for {\it any\/} problems
you have, whether or not they are caused by TeXit.  On the other hand,
if you do have problems, I'll be as helpful as I can ;-)

\section{What Does It Do?}

\drawdoc

Such a document forms a tree-like graph\footnote{It's tree-like because you
can't have a cycle in the ``main branches'' (i.e. the included files) but it's
also a graph because there can be cross references between any two nodes.}.

In the worst case, getting this document to print correctly requires 
{\em eight\/} steps!

\begin{enumerate}
  \item Run \LaTeX\ (this generates \verb|main.idx| and \verb|main.aux|).
  \item Run \LaTeX\ again to satisfy any cross references.
  \item Run Bib\TeX\ (this generates \verb|main.bbl|).
  \item Run MakeIndex (this generates \verb|main.ind|).
  \item Run \LaTeX\ (this builds the ``final document'').  Except that
        the bibliography citations have changed a page break so the references
        are wrong.
  \item Run \LaTeX\ again to satisfy any cross references.
  \item Run MakeIndex since the index may be wrong.
  \item Run \LaTeX\ to build the final document.
\end{enumerate}

As if that weren't enough to warrant the aid of a script to do the dirty
work, you might also like to setup \TeX\ as a compiler from within your
editor, but you want to run \LaTeX\ on ``\verb|main.tex|'' even if you
happen to be editing ``\verb|chap02.tex|''.

TeXit can handle all of these problems.

\subsection{Finding the Right File}

When TeXit processes a file, the first thing it looks for is some indication
that the file it was given is part of some larger document.  If it discovers
that this is the case, it abandons the current file in favor of the ``master''
file.

There are two ways that you can indicate that a file is part of a larger
document:

\begin{itemize}
  \item Place ``\verb|% master: main.tex|'' on a line by itself near the
        top of your document.  This identifies ``\verb|main.tex|'' as
        the master file.
  \item Include ``\verb|% TeX-master: main.tex|'' in an Emacs ``Local
        Variables'' section at the bottom of your file.  If you don't
        use Emacs, don't worry about this.
\end{itemize}

\subsection{Finding the Right Format}

Next, TeXit needs to determine what format to use.  You can force TeXit
to select a particular mode with the ``\verb|-|{\em format\/}'' command-line
switch, or by inserting a command in your document:

\begin{itemize}
  \item Place ``\verb|% mode: latex|'' or ``\verb|% format: latex|'' on a 
        line by itself near the top of your document.  This identifies
        ``\verb|latex|'' as the format to use.  TeXit figures out the
        actual format file name, you just tell it in English.  Running TeXit
        without any arguments will give you a list of formats.
  \item Include \verb|% mode: latex| in an Emacs ``Local
        Variables'' section at the bottom of your file.  If you don't
        use Emacs, don't worry about this.
\end{itemize}

If you don't specify a format, TeXit assumes that the document is Plain \TeX\
unless it finds one of the following:

\begin{itemize}
\item ``\verb|\documentstyle[|{\em any options\/}\verb|]{slides}|''
    indicates Sli\TeX.

\item ``\verb|\documentstyle[|{\em any options\/}\verb|]{foils}|''
    indicates Foil\TeX.

\item ``\verb|\documentsytle|''
    indicates \LaTeX.

\item ``\verb|\document |{\em something\/}''
    indicates AMS\TeX.

\item ``\verb|\Define|{\em xxx\/}\verb|:|{\em yyy\/}''
    indicates Lollipop.

\item ``\verb|@node|'' or ``\verb|@ifinfo|'' or ``\verb|input texinfo|'' 
    indicates Texinfo.
\end{itemize}

TeXit only searches the first \verb|$TEXHEADERSIZE| lines for these commands.
With the exception of ``\verb|input texinfo|'', they must occur at the
very beginning of a line to be recognized.

After processing your document, TeXit looks at the log file and re-runs \TeX\
if the references have changed or the citations have changed.  TeXit provides
support for \LaTeX\ and Texinfo logs at the moment.  Other formats will be
added upon request.

\section{More Power!\protect\footnote{grunt, Grunt, GRUNT! ;-)  This is a
poor joke.  It'll only make sense if you're familiar with the television 
sit-com {\em Home Improvement}.}}

You can extend TeXit by adding ``rules'' to your documents.  Rules tell
TeXit how the various pieces of your document are related.  It is similar
to ``make'' in many regards, but it is a little better than make for \TeX\
documents since it can examine the contents as well as the time-stamp
of a file.

Rules are added by placing a ``rules'' section in your main document file.
For example, this document has the following rules:

% hackery here so that the first line isn't noticed by TeXit...
\verb|  % Start TeXit |\verb|rules:|
\vskip-\baselineskip\vskip-\parskip
\begin{verbatim}
  % &cleanup_files ('texittr.tli','texittr.tlo');
  %
  % # it doesn't really have this rule, I just wanted to make the
  % # example more interesting
  % &bibtex('texit') if &newer('myrefs.bib') 
  %                     || &missing('texit.bbl');
  %
  % &run(treetex texittr'), 
  %   &waitfor('texittr.tli') if &changed('texittr.tlo') 
  %   || &missing('texittr.tli');
  %
  % &dependson('texittr.tli');
  % End TeXit rules:
\end{verbatim}

The ``\verb|Start TeXit rules:|'' and ``\verb|End TeXit rules:|'' lines are
markers.  They are required.  Leading ``\%'' signs and whitespace are ignored.
Note: if you are using a \TeX\ format that uses some other comment character,
you'll have to protect the rules in some other way.  You can't simply use any
comment character that you want.

The catch is that your rules have to be valid Perl statements.  I've
tried to make most of the common things easy to add by hiding them in
functions.  If you use the syntax shown, everything will be ok.

TeXit rules can extend over over multiple lines, but some care must be taken.
When TeXit is parsing the rules, it assumes that any line that {\em ends\/}
with a semi-colon ends the rule.  Trailing Perl comments (unescaped ``\#''
marks) are trimmed off.  This allows you to build up a compound statement like
this:

\begin{verbatim}
  % if ($some_conditional) {
  %  do_this ;  # use perl comment to hide the semicolon
  %  and_this ; # (make sure you hide each one)
  % } ;       
\end{verbatim}

Rules can ``do anything'' since they're written in Perl.  Use care: don't
change any of TeXit's variables!  The rules for a document are evaluated
{\em every\/} time the document is processed.  If you want some rules to
be evaluated only once, you can test against ``\verb|$first_time|''.  This
variable will only be true once, right before the document is processed
for the first time.

The following variables are defined before the rules are executed:

\begin{itemize}
  \item \verb|$TEXFILEPATH| 
      
        The pathname of the master file (it always ends in a slash and
        is equal to ``./'' if the file has no other path).

  \item \verb|$TEXFILENAME|
    
        The base name of the master file (no path, no extension).

  \item \verb|$TEXFILEEXT|

        The extension of the master file.

  \item \verb|$TEXFORMAT|

        The english name of the format that TeXit decided to use.
\end{itemize}

\section{A Short Lesson in Rules}

If you aren't a Perl aficionado, the following guidelines will help you write
right rules.  But be warned, not every statement in this section is the whole
truth.

Most rules have the form:

\begin{center}
  \verb|&|{\it command}\verb|(|{\it arguments}\verb|) if |%
  {\it predicates}\verb|;|
\end{center}

The following commands are available:

\begin{itemize}
  \item \verb|&bibtex('|{\it arguments}\verb|')|

        Runs the BibTeX program with the arguments specified.

  \item \verb|&tex('|{\it arguments}\verb|')|

        Runs the \TeX\ program with the arguments specified.

  \item \verb|&makeindex('|{\it arguments}\verb|')|

        Runs the MakeIndex program with the arguments specified.

  \item \verb|&run('|{\it command arguments}\verb|')|

        The most general form, this command runs whatever you pass
        it, just as if you typed it at the shell prompt.

  \item \verb|&waitfor('|{\it file1}\verb|', '|%
                           {\it file2}\verb|',|\ldots\verb|)|

         Waits until all the files specified exist.  Use care, this can
         cause TeXit to ``hang'' forever.  I added this condition so that
         I could run commands asynchronously on another machine and make
         TeXit pause until they were done. 

  \item \verb|&auxfile("ext")|

        Returns the name of the auxilliary file with the extension
        ``ext''.  This allows you to test for files, like the DVI file:

        For example, the test ``\verb|-r &auxfile("dvi")|'' returns true
        if the DVI file is readable.

  \item \verb|&cleanup_files('|{\it file1}\verb|', '|%
                           {\it file2}\verb|',| \ldots\verb|)|

        This command adds ``{\it file1\/}'', ``{\it file2}'', etc., to the
        list of files that should be deleted by the cleanup choice.

\end{itemize}

The following predicates are available:

\begin{itemize}
  \item \verb|$first_time|

        TeXit runs all of your rules once before running \TeX\ for the
        first time.  During that one run, the \verb|&first_run| predicate
        will be true.  All of the other predicates return false during
        the first run.
  
  \item \verb|&dependson('|{\it file1}\verb|', '|%
                           {\it file2}\verb|',| \ldots\verb|)|

        Tells TeXit that the DVI file for your document depends on
        all of the files listed.  If any of these files are newer than
        the DVI file, \TeX\ will be run again.

        TeXit evaluates your rules in the order they are written.  Make
        sure that all of your \verb|&dependson| rules occur last.  

  \item \verb|&missing('|{\it file1}\verb|', '|%
                         {\it file2}\verb|',| \ldots\verb|)|

        Returns true if any of the files specified are missing (i.e.
        unreadable by your effective userid).

  \item \verb|&changed('|{\it file1}\verb|', '|%
                         {\it file2}\verb|',| \ldots\verb|)|

        Returns true if any of the files specified have changed since the
        last time \TeX\ was run.  TeXit saves a checksum of each file across
        runs of \TeX\ and compares the checksums.

  \item \verb|&newer('|{\it nfile1, nfile2, \ldots}\verb|', '|%
                       {\it ofile1, ofile2, \ldots}\verb|')|

        Returns true if any of the ``{\it nfiles}'' are newer than any
        of the ``{\it ofiles}'' or if any of the ``{\it ofiles}'' don't
        exist.

        Note the different calling sequence for this predicate.  You must
        pass only two elements to this function: {\em put the list of files
        in quotes!}  This is different than all the other predicates, I know.
        Sorry about that.
\end{itemize}

\section{Built in Commands}

When TeXit finishes processing your document, it presents the ``Again?''
prompt.  You should respond to the ``Again?'' prompt with the letter(s) in
square brackets for the command that you want to issue.  For example, to run
the ``\verb|[p]rint|'' command, reply ``p''.  You can insert a space and
additional options.  For example ``p -Pdept1'' runs the print command with the
additional options ``-Pdept1''.  How (or if) that argument is interpreted
depends on the command.

By default, TeXit is configured to supply the following commands:

\begin{itemize}
  \item \verb|[b]ibtex|, \verb|[g]hostview|, \verb|[t]ex|, \verb|[v]iew|

    Runs BibTeX, Ghostview, \TeX, or your previewer, respectively.

  \item \verb|[p]rint|

    Runs a printer.  You {\em must\/} specify the name of the printer 
    queue as an option.  Use ``p ?'' to get a list of queues.  Additional
    options, after the queue name, are passed to either the DVI driver
    or the print command: options before a ``\verb+|+'' go to the DVI
    driver, options after go the print command.

    For example, the following command ``\verb+p dept1 -p1 -l1|-K2+''
    prints your job to the ``dept1'' printer queue.  The DVI driver
    sees the options ``-p1 -l1'' and the printer command sees the
    options ``-K2''.

  \item \verb|[c]leanup|

    Deletes auxilliary files (log, aux, etc.).  This can be configured
    in document rules and/or \verb|.texitrc| files.

  \item \verb|e[x]it|

    Exits TeXit.
\end{itemize}

Section~\ref{sec:examples} illustrates how you can add your own commands.

\section{Other Initialization}
\label{sec:init}

The first thing TeXit does after parsing your command line arguments and
finding out what document you want to process is load initialization files.
These files typically set variables like \verb|$TEXRETRIES| and
\verb|$TEXHEADERSIZE|.  If they exist, the following scripts are loaded (in
this order):

\begin{itemize}
  \item Some global configuration file

    Support for this option requires editing the script.  I don't expect it
    to be done very often.

  \item \verb|~/.texitrc|

    The script file found in your home directory.  TeXit finds your home
    directory by looking for the ``\verb|TEXIT|'' environment
    variable and the ``\verb|HOME|'' environment variable.  It uses whichever
    it finds first.

    You really should set one or the other.  If neither is set, your
    home directory effectively becomes the current directory.  Probably
    not what you had in mind. 

  \item \verb|$TEXFILEPATH/.texitrc|

    The script file in the same directory as your \TeX\ master document
    file.
 
  \item \verb|-initfile |{\it ifile}

    Finally, any init files that you specify as options are loaded.  If you
    specify more than one, they are loaded in the order specified.
\end{itemize}

\section{Some Examples}
\label{sec:examples}

This section demonstrates some customizations performed in ``\verb|.texitrc|''
files.  These examples should help you figure out how to do some of the 
customizations you're likely to want.  You can alway send me email if you
want help with a particular customization.

\subsection{Adding a new command}

Let's add the \verb|dvitty| program as a new command.  First, define
the program name and the command.  These could be combined, but it's
better not to for reasons that will become clear in a moment.

\begin{verbatim}
  $DVITTY    = "/usr/local/bin/dvi2tty";
  $DVITTYCMD = "$DVITTY %o %d";
\end{verbatim}

Table~\ref{tab:percentsubst} shows all of the \%-substitutions that
you can include in the command.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|}
      \hline
      \verb|%F| & The format file name \\
      \verb|%s| & The base name of the \TeX\ master file \\
      \verb|%t| & The \TeX\ master file with its extension \\
      \verb|%d| & The DVI file\\
      \verb|%o| & Any options added to the command by the user\\
      \verb|%D| & The DVI file with ``/'' translated to ``$\backslash$''. \\
      \verb|%S| & The base name with ``/'' translated to ``$\backslash$''. \\
      \verb|%T| & The master file with its extension and with ``/'' translated to ``$\backslash$''. \\
      \hline
    \end{tabular}
    \caption{Percent substitutions performed by TeXit.}
    \label{tab:percentsubst}
  \end{center}
\end{table}

The next thing that you need to do is tell TeXit to present this as an option
to the user.  In order to do this, you must define two more commands:
\verb|$CMDPROMPT{|{\it cmd-name}\verb|}| and \verb|$CMDTEST{|{\it
cmd-name}\verb|}|.  The ``{\it cmd-name}'' is the prompt-string that
will be displayed to the user.  Some portion of that string must be in square
brackets.  That portion is what the user must enter to run the choice.  The
\verb|$CMDPROMPT| is the Perl string that is evaluated if the user
selects that command and the \verb|$CMDTEST| string is evaluated before the
prompt is displayed to see if that command is allowed now.  Both of these
strings should be defined in {\em single quotes\/} so that  Perl doesn't
do any interpolation when it's defining the command.  The \verb|$CMDPROMPT|
string should end with either ``\verb|$RETEX|'' or ``\verb|$REASK|'' depending
on whether you want to re-run \TeX\ or redisplay the prompt.

Here's how \verb|dvitty| is defined:

\begin{verbatim}
  $CMDPROMPT{"dvi2[tty]"} = '&run($DVITTYCMD, "$opts"); $REASK;';
  $CMDTEST{"dvi2[tty]"}   
     = '"$DVITTY" && -x "$DVITTY" && -r &auxfile("dvi")';
\end{verbatim}

These commands indicate that:

\begin{itemize}
  \item TeXit should add ``\verb|dvi2[tty]|'' to the prompt.
  \item The user must respond ``\verb|tty|'' to select this option.
  \item The option is only available if \verb|$DVITTY| is defined and
        executable and the DVI file exists.
  \item If selected, TeXit should run the \verb|$DVITTYCMD| with any
        options the user specified (always stored in ``\verb|$opts|'')
        and then redisplay the prompt.
\end{itemize}

Another example: adding a printer queue command.  This one's done
a bit sloppily, but it works.

\begin{verbatim}
  $CMDPROMPT{"[q]uery printer"} 
    = '&run("lpq -P%o", "$opts"); $REASK;';
  $CMDTEST{"[q]uery printer"} = '';
\end{verbatim}

\subsection{Adding a New Printer}

Assuming that the program ``\verb|dvi2bam|'' translates DVI files into output
for the Bambleweenie 2000 printer (translating ``file.dvi'' to ``file.bbw''),
the following commands add the ``\verb|neato|'' printer to TeXit.

\begin{verbatim}
  $DVIBAM = "/usr/local/bin/dvi2bam";
  $DVIBAMCMD = "$DVIBAM %o %d";

  $PRQUEUE{"neato"} = "bamble";
  $PRINTCMD{"neato"} = "lpr %o %s.bbw";
  $PRINTOPT{"neato"} = "-Pneato";

  $DVICMD{"bamble"} = $DVIBAMCMD;
  $DVIOPT{"bamble"} = "";
\end{verbatim}

Adding a new printer, ``\verb|myprinter|'', of the same type is a simple
matter:

\begin{verbatim}
  $PRQUEUE{"myprinter"} = "bamble";
  $PRINTCMD{"myprinter"} = "lpr %o %s.bbw";
  $PRINTOPT{"myprinter"} = "-Pmyprinter";
\end{verbatim}

\subsection{Removing a Command}

To remove a command, undefine one of the things that its ``\verb|$CMDTEST|''
string tests.  For example, to remove Ghostview:

\begin{verbatim}
  undef($GSVIEW);
\end{verbatim}

This is why you should always put a simple command-defined type test in
your ``\verb|$CMDTEST|'' strings.

To completely remove a command, delete its entries in the \verb|$CMDTEST|
{\em and\/} \verb|$CMDPROMPT| arrays.  If you only delete its entry
in the \verb|$CMDTEST| array, the command will always be available (a
null test is true by default).  If you only delete its entry in the
\verb|$CMDPROMPT| array, you will get a runtime error (this is intentional,
it helps catch typos in the array definitions).

\begin{verbatim}
  delete $CMDPROMPT{"[b]ibtex"};
  delete $CMDTEST{"[b]ibtex"};
\end{verbatim}

\subsection{Removing a Printer}

To remove a printer, delete its ``\verb|$PRQUEUE|'' entry.  For example,
the following command removes the ``Local'' printer:

\begin{verbatim}
  delete $PRQUEUE{"Local"};
\end{verbatim}

\subsection{Other Examples}

Look in the \verb|.texitrc| files supplied with TeXit for more ideas
and examples.

\section{Running under OS/2}

The following file, ``\verb|texit.cmd|'' demonstrates how \verb|texit.pl|
can be run under OS/2.  This sort of hackery might not be necessary if you
put \verb|texit.pl| in the Perl library path, but I don't because
the compiled-in path is \verb|c:\perl\lib| which I'm unwilling to use.
I could recompile Perl, I suppose, but on my 386SX box that'd probably
take about a year and a half.  Not to mention all the disk space I don't
have.  Actually, there's a  bug in this port that I would like
to fix, but I won't be able to do that for a while.

The tricks are: 

\begin{itemize}
  \item You have to get the whole pathname to Perl and OS/2 only
        passes the path of the command you typed (so if it's on your PATH, it
        only gets ``\verb|texit|''.

  \item Having put the pathname on the ``extproc'' line, you have to do
        a ``shift'' to get rid of the name that OS/2 put on the command line.

  \item In order for Perl to find the file ``\verb|require|''d,
        it must be on the \verb|@INC| path.  (You see, it begins with a
        drive letter (not a ``/'') so Perl thinks it has to look
        for the file.  The bug.  Sigh.) 
\end{itemize}

\begin{verbatim}
  extproc perl -x e:/emtex/texit.cmd
  #! perl 
  shift; # get rid of TEXIT.CMD shoved on by OS/2
  push (@INC, "e:/emtex");    # add emtex to search path
  push (@INC, "e:/Perl/lib"); # perl path
  require "texit.pl"
\end{verbatim}

\section{Questions, Suggestions, or Flames?}

I know this documentation is incomplete (and badly written).  I'll try to
answer any questions that you ask and entertain any suggestions that you might
have (no matter {\em how\/} entertaining I think they are ;-).

In my own defense, I {\em did\/} put lots of comments in the script.  It
shouldn't be too inscrutable.

\end{document}


% Start TeXit rules:
% &cleanup_files ('texittr.tli','texittr.tlo');
%
%# &run('treetex texittr'), &waitfor('texittr.tli')
%#   if &changed('texittr.tlo') || &missing('texittr.tli');
%
% &dependson('texittr.tli');
% End TeXit rules: