NAME
     tex, initex, virtex  - text formatting and typesetting

SYNOPSIS
     tex [ first line ]

     initex [ first line ]

     virtex [ first line ]

DESCRIPTION
     TeX formats the interspersed text and commands contained  in
     the  named  files  and outputs a typesetter independent file
     (called DVI which is short  for  DeVice  Independent).   TeX
     capabilities  and  language  are described in The TeXbook by
     Donald E. Knuth, published by Addison-Wesley.

     TeX is normally used with a large body of  precompiled  mac-
     ros, and there are several specific formatting systems, such
     as LaTeX, which require the support of several macro  files.
     The basic programs as compiled are called initex and virtex,
     and are distinguished by the fact that initex can be used to
     precompile macros into a .fmt file, which is used by virtex.
     On the other hand, virtex starts more quickly and can read a
     precompiled  .fmt file, but it cannot create one.  It is the
     version of TeX which is usually invoked  in  production,  as
     opposed to installation.

     Any arguments given on the command line to the TeX  programs
     are  passed  to  them  as  the first input line.  (But it is
     often easier to type extended arguments as the  first  input
     line,  since  shells tend to gobble up or misinterpret TeX's
     favorite symbols, like backslashes, unless you quote  them.)
     As  described  in  The TeXbook, that first line should begin
     with a file name or a \controlsequence.  The normal usage is
     to say ``tex paper'' to start processing paper.tex. The name
     ``paper'' will be the ``jobname'', and is  used  in  forming
     output  file  names.   If TeX doesn't get a file name in the
     first line, the jobname is ``texput''.  The  default  exten-
     sion,  .tex,  can  be  overridden by specifying an extension
     explicitly.

     If there is no paper.tex in the current directory, TeX  will
     look  look  through  a  search path of directories to try to
     find it.  If ``paper'' is the ``jobname''  a  log  of  error
     messages,  with  rather more detail than normally appears on
     the screen, will appear in paper.log, and  the  output  file
     will     be     in    paper.dvi.    The    system    library
     /usr/local/lib/tex/inputs contains the basic  macro  package
     plain.tex, described in The TeXbook, as well as several oth-
     ers.  Except when .fmt files are being prepared it is hardly
     ever  necessary  to \input plain, since almost all instances
     of TeX begin by loading plain.fmt.  This means that  all  of
     the  control  sequences  discussed  in The TeXbook are known
     when you invoke tex.  For a discussion of  .fmt  files,  see
     below.

     Several environment variables can be used to set  up  direc-
     tory  paths  to search when TeX opens a file for input.  For
     example, the csh command
         setenv                                         TEXINPUTS
         .:/usr/me/mylib:/usr/local/lib/tex/inputs
     or the sh command sequence
         TEXINPUTS=.:/usr/me/mylib:/usr/local/lib/tex/inputs
         export TEXINPUTS
     would cause all invocations of TeX and  its  derivatives  to
     look  for  \input files first in the current directory, then
     in a hypothetical user's ``mylib'', and finally in the  sys-
     tem library.  Normally, you would place the variable assign-
     ment which sets up the  TEXINPUTS  environment  variable  in
     your  .login  or  .profile  file.  The environment variables
     section below lists the relevant environment variables,  and
     their defaults.

     The e response to  TeX's  error  prompt  causes  the  system
     default  editor  to  start  up  at  the  current line of the
     current file.  There is an  environment  variable,  TEXEDIT,
     that  can be used to change the editor used.  It should con-
     tain a string with "%s" indicating where the  filename  goes
     and  "%d"  indicating  where the decimal linenumber (if any)
     goes.  For example, a TEXEDIT string for vi can be set  with
     the csh command
         setenv TEXEDIT "/usr/ucb/vi +%d %s"

     A convenient file in the  library  is  null.tex,  containing
     nothing.   When  TeX can't find a file it thinks you want to
     input, it keeps asking you for another file name;   respond-
     ing  `null'  gets  you  out of the loop if you don't want to
     input anything.  You can also type your EOF character  (usu-
     ally control-D).

     The initex and virtex programs can be used to  create  fast-
     loading  versions  of  TeX based on macro source files.  The
     initex program is used to create a format (.fmt)  file  that
     permits  fast  loading  of  fonts and macro packages.  After
     processing the fonts and definitions desired, a  \dump  com-
     mand  will  create the format file.  The format file is used
     by virtex. It needs to be given a format file  name  as  the
     first  thing it reads.  A format file name is preceded by an
     &, which needs to be escaped with \ to prevent  misinterpre-
     tation by your shell if given on the command line.

     Fortunately, it is no  longer  necessary  to  make  explicit
     references  to the format file.  The present version of TeX,
     when compiled from this distribution, looks at its own  com-
     mand  line  to  determine what name it was called under.  It
     then uses that name, with the ``.fmt'' suffix  appended,  to
     search  for  the  appropriate format file.  During installa-
     tion,  one format file with the name tex.fmt, with only  the
     plain.tex  macros  defined,  should have been created.  This
     will be your format file when you  invoke  virtex  with  the
     name  tex.   You can also create a file mytex.fmt using ini-
     tex, so that this will be loaded when you invoke virtex with
     the  name mytex.  To make the whole thing work, it is neces-
     sary to link virtex to all the names of  format  files  that
     you  have  prepared.   Hard  links  will  do for system-wide
     equivalences and Unix systems  which  do  not  use  symbolic
     links.  Symbolic links can be used for access to formats for
     individual projects.  For example: virtex can be hard linked
     to  tex  in the general system directory for executable pro-
     grams, but an individual version of TeX will more likely  be
     linked by a symbolic link in a privately maintained path
         ln -s /usr/local/bin/virtex mytex
     in a directory such as /home/me/bin.

     Another approach is to set up a alias  using,  for  example,
     the C shell:
         alias mytex virtex \&myfmt
     Besides being more cumbersome, however, this approach is not
     available  to systems which do not accept aliases.  Finally,
     there is the system known  as  ``undump''  which  takes  the
     headers from an a.out file (e.g. virtex) and applies them to
     a core image which has been dumped by the Unix QUIT  signal.
     This  is very system-dependent, and produces extremely large
     files when used with a large-memory version  of  TeX.   This
     can  produce  executables which load faster, but the execut-
     ables also consume enormous amounts of disk space.

ENVIRONMENT VARIABLES
     The defaults for all environment variables are  set  at  the
     time of compilation in a file named site.h in the web2c dis-
     tribution.  All paths are colon-separated.  If  you  set  an
     environment  variable  to  a value that has a leading colon,
     the system default shown here is prepended.  Likewise for  a
     trailing colon.  For example, if you say
         setenv TEXFONTS /u/karl/myfonts:
     TeX will search
         /u/karl/myfonts:.:/usr/local/lib/tex/inputs Furthermore,
     the person who installed TeX at your site may have chosen to
     allow one level of subdirectories to be  searched  automati-
     cally  (by  defining  the  symbol  SEARCH_SUBDIRECTORIES  in
     site.h).  In that case, subdirectories of directories in the
     environment  variable  TEXFONTS_SUBDIR are also searched for
     fonts, and subdirectories of directories in the  environment
     variable TEXINPUTS_SUBDIR are also searched for input files.
     All the programs in the base TeX distribution use this  same
     search method.

     Normally, TeX puts its output files in  the  current  direc-
     tory.   If  any output file cannot be opened there, it tries
     to open it in the directory  specified  in  the  environment
     variable  TEXMFOUTPUT.  There  is  no default value for that
     variable.  For example, if you say texpaper and the  current
     directory  is  not  writable,  and TEXMFOUTPUT has the value
     /tmp,   TeX   attempts   to   create   /tmp/paper.log   (and
     /tmp/paper.dvi, if any output is produced.)

     TEXINPUTS
          Search path for \input and \openin files.  This  should
          probably      start      with      ``.''.      Default:
          .:/usr/local/lib/tex/inputs.

     TEXINPUTS_SUBDIR
          Search path  for  directories  with  subdirectories  of
          input files.  Default:

     TEXFONTS
          Search path for font  metric  (.tfm)  files.   Default:
          .:/usr/local/lib/tex/fonts/tfm.

     TEXFONTS_SUBDIR
          Search path  for  directories  with  subdirectories  of
          fonts.  Default:

     TEXFORMATS
          Search    path    for    format    files.      Default:
          .:/usr/local/lib/tex/formats.

     TEXPOOL
          Search path  for  INITEX  internal  strings.   Default:
          .:/usr/local/lib/tex.

     TEXEDIT
          Command template for  switching  to  editor.   Default:
          /usr/ucb/vi +%d %s.

FILES
     /usr/local/lib/tex  TeX's library areas

     /usr/local/lib/tex/tex.pool
                         Encoded text of TeX's messages.

     /usr/local/lib/tex/fonts/tfm/*.tfm
                         Metric files for TeX's fonts.

     /usr/local/lib/tex/fonts/tfm/*nnn{gf,pk}
                         Bitmaps  for  various  devices.    These
                         files are not used by TeX.
     /*.fmt              TeX .fmt files.

     /usr/local/lib/tex/inputs/plain.tex
                         The ``default'' macro package.

SEE ALSO
     Donald E. Knuth, The TeXbook
     Leslie Lamport, The LaTeX Document Preparation System
     Michael Spivak, The Joy of TeX
     TUGBOAT (the publication of the TeX Users Group)

TRIVIA
     TeX, pronounced properly, rhymes  with  ``blecchhh.''   Note
     that the proper spelling in typewriter-like media is ``TeX''
     and not ``TEX'' or ``tex.''

AUTHORS
     TeX was designed by Donald  E.  Knuth,  who  implemented  it
     using  his WEB system for Pascal programs.  It was ported to
     Unix at Stanford by Howard Trickey, and at Cornell by  Pavel
     Curtis.  The version now offered with the Unix TeX distribu-
     tion is that generated by the WEB to C  system,  written  by
     Tomas Rokicki and Tim Morgan.
-----
