path: root/support/tex-it/texit.tex

\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: