path: root/Master/texmf-dist/doc/texsis/base/TXSinstl.doc

% file: TXSinstl.doc - Installation Instructions - TeXsis version 2.18
%% @(#) $Id: TXSinstl.doc,v 18.2 2000/05/17 00:19:46 myers Exp $
%======================================================================*
% Copyright (c) 1990, 1992, 1995, 1997 by Eric Myers and Frank Paige.
% This file is a part of TeXsis.  Distribution and/or modifications
% are allowed under the terms of the LaTeX Project Public License (LPPL).
% See the file COPYING or ftp://ftp.texsis.org/texsis/LPPL
%======================================================================*
\ifx\undefined\meta \texsis\input TXSdocM.doc\input Manual.aux\draft\fi


\appendix{A}{Customization and Installation of \TeXsis \label{install}}

\centerline{(\TeX sis version \fmtversion, as of \revdate)}

\noindent
This appendix contains information about how to install \TeXsis\ on
several types of computer systems, and how to customize \TeXsis\ for a
particular installation.  The discussion below on ``Local
Modifications'' may be of interest to any user, but the rest of this
Appendix is probably only of interest to someone who is responsible for
installing or maintaining \TeXsis.


\subsection{Customization}

      There are three different mechanisms for making modifications to
the basic \TeXsis\ macro package. It is better to use one of these
mechanisms rather than modifying the original code.

\subsubsection{Local Modifications}

      \TeXsis\ will read the file {\tt TXSmods.tex}, if it exists, from
the current directory or search path every time you run \TeXsis.  This
lets you make your own \idx{custom modifications} or additions to
\TeXsis. For example, say you have a directory specifically for a
particular project you are working on and you are writing several
different papers or other documents related to this project.  You could
add a file called {\tt TXSmods.tex} to this directory to contain extra
macro definitions that are used in all of these documents, and these
will be loaded automatically whenever you run \TeXsis\ in this
directory.  If you run \TeXsis\ from another directory these macros will
not be loaded.

\subsubsection{Site Modifications}

      If a file called {\tt TXSsite.tex} exits in the current directory
at the time the \TeXsis\ format file is created (see below) then it is
automatically read in at this time.  The purpose of this file is to
allow you to add definitions and macros that are local to your computer
installation.  For example, in this file you would define the control
word \cs{ORGANIZATION} to give the name of your organization or
institution.  \cs{ORGANIZATION} is used at the top of memos and at the
top of the title page of a \cs{preprint}.  You might also put a
customized \cs{letterhead} macro in this file, and you may well want to
change the definition of \CS{LandscapeSpecial}, which controls how your
laser printer is put into landscape mode.  Note that the file {\tt
TXSsite.tex} is only read {\sl once}, when the \TeXsis\ format file is
created, not every time \TeXsis\ is run.
A prototype site file, called |TXSsite.000|, is included in the standard
distribution of \TeXsis.


\subsubsection{Patches}

      \TeXsis\ will also automatically read in a file called
{\tt TXSpatch.tex} from the standard input path, if it exists, 
every time \TeXsis\ is run.
This file should contain additions or corrections (``patches'') to
\TeXsis.  This patch file lets you correct minor problems or make minor
changes to \TeXsis\ without having to rebuild the format file.

Whenever we find a problem with \TeXsis\ we try to correct it as soon
as possible.
To make the correction available to users before the next version of
\TeXsis\ is released we issue patch files containing the corrections.
The most current patch file should always be available at
\URL{ftp://ftp.texsis.org/texsis}, or in {\tt
macros/texsis} on any CTAN server.



%==================================================*

\subsection{Installation of \TeXsis}

To use \TeXsis\ or any large macro package effectively you should run
the |initex| program to create a pre-compiled format. The general method
of doing this is machine independent, but the specific commands depend
on the operating system on your computer.  This appendix gives the
appropriate commands for running |initex| and installing \TeXsis\ on a
computer running UNIX, a VAX or Alpha running VMS, and for an IBM PC running
PC\TeX\ under \idx{MS-DOS}. We assume that you are familiar with the
operating system and that \TeX\ and the Plain format have already been
installed.
Notes on how to install \TeXsis\ on other kinds of machines (such as
Atari or Apple computers, or on Linux) are available on the \TeXsis\
ftp server   (\URL{ftp://ftp.texsis.org/texsis}). 

VMS users should note that \TeXsis\ is also available with the latest
release of DECUS \TeX, and much of the installation work has already
been done or can be done almost automatically.  You may want to get this
version from CTAN rather than the ``raw'' distribution from the TeXsis
ftp site.
If you are installing from the DECUS distribution you should read the
file |INSTALL.VMS| with that distribution.


\subsubsection{Quick Install for Unix and \TeX~3.x}

The current version for \TeX\ as of 1997 is 3.14159.  If you have
anything earlier than version 3.x then it is strongly recommended that
you first upgrade your \TeX\ installation.  Assuming that you have a
current \TeX\ installation on a Unix computer, you can build and
install \TeXsis\ by simply doing the following:


\EnvRightskip=\parindent
\enumerate\enumpoints
\itm\llap{\square\qquad}%
Edit the file |Makefile| and change parameters and paths as
appropriate, following the directions given in the comments.
The TEXDIR variable should point to the top-level \TeX\ directory
on your system.  The default directories under TEXDIR are those
recommended by the TeX Directory Structure (TDS) working group of the
\TeX\ Users Group.

\itm\llap{\square\qquad}%
(Optional) Copy the file |TXSsite.000| to |TXSsite.tex| and edit
this file to contain appropriate site dependent information, such as
definitions for the name of your |\ORGANIZATION|, or your
\cs{letterhead}, or change \cs{LandscapeSpecial}.
If you already have a |TXSsite.tex| file then copy it to the current
directory so that it will be included when building the format file.

\itm\llap{\square\qquad}%
Give the command `|make|' to  build the format file and the manual.

\itm\llap{\square\qquad}%
Give the command `|make install|' to install the files on the system.
\endenumerate
 

\pagecheck{0.20\vsize}
\subsubsection{Detailed Installation}

To install \TeXsis\ follow the steps below or their equivalents for
your computer and operating system.  If you are installing a system-wide
version of \TeXsis\ then you may want to review the appropriate
documentation on  how \TeX\ itself is installed on your system.
\enumpoints
\enumerate
\itm\llap{\square\qquad}%
Create a separate directory to hold the \TeXsis\ files.  This is not
strictly necessary, but it is strongly recommended, since there are
more than 70~files for the source code and 
documentation.  On a Unix machine we recommend using
|/usr/local/share/texmf/tex/texsis| or |/usr/local/lib/tex/texsis|, depending on
where your other \TeX\ files are kept.  For a VMS system,
you should use a subdirectory of the main \TeX\ directory, whatever that
happens to be.  On an IBM PC
it is best to use a top-level directory |C:\TEXSIS| on your hard disk,
rather than a subdirectory of |C:\PCTEX|, to simplify backing up your
files.

\itm\llap{\square\qquad}%
Copy all of the \TeXsis\ files into this directory.  The \TeXsis\ source
files all have names of the form |TXS|$xxx$|.tex|, and 
most of the documentation
files have names |TXS|$xxx$|.doc|.  \TeXsis\ style files end with
the extension |.txs|.  There will also be several other files in your
distribution of \TeXsis, such as |texsis.tex| and |Manual.tex|. 
A complete list of the files can be found in a file called |MANIFEST|.


\itm\llap{\square\qquad}%
Make any necessary changes in the source code. You will probably want to
copy the file |TXSsite.000| to |TXSsite.tex| and edit this file, 
changing the definition of \cs{ORGANIZATION}, \cs{LandscapeSpecial},
and the letterhead macros. 

On VMS systems you may (or may not) want to define |\TeXsisLib| to be
the \TeXsis\ directory and |\TXSpatches| to be the patch file in that
directory.

If you have problems with missing fonts, look at the documentation
in the file |TXSfonts.tex|.


\itm\llap{\square\qquad}%
Create the format file |texsis.fmt| by running |initex|. \index{initex}
On a Unix machine the command is:
\example
|% initex \&plain texsis '\dump'|
\endexample
You must remember the ``|\|'' to escape the ``|&|.''

On a VMS system replace the |initex| command with |TEX/INIT|. You must
also tell \TeX\ where to find the input files for both \TeXsis\ and
Plain \TeX.  The commands are:
\example\obeylines\advance\rightskip by -1cm
|$ DEFINE/USER  TEXIN  | \meta{texsis}  \meta{plain}
|$ TEX/INIT/NOFORMAT/TEXINPUTS=TEXIN: "&plain texsis \dump"|
\endexample
where \meta{texsis} is the specification for the device, directory, and
subdirectories of \TeXsis, and \meta{plain} is the specifiation for
the standard files like |PLAIN.TEX|.

For an IBM PC with PC\TeX\ give the command,
\example
|TEX TEXSIS /I|
\endexample
and reply to the |*| prompt with ``\cs{dump}.''  (In some versions of
PC\TeX\ the |TEX| command is replaced with |TEX386| or |TEX386b|.  Check
your manual to be sure.)  \TeXsis\ will also work with |emtex| or any
other version of ``big'' \TeX\ for the PC, but you will have to check
the documentation for that particular implementation of \TeX\ for
specific instructions for creating a preloaded format.

In any case |initex| will load the Plain \TeX\ format and then the
various pieces of \TeXsis, displaying a message for each piece. 
Finally it will spew out a list of fonts used and other information.
This should contain near the end the statement ``No pages of output
produced.'' (If it does not, something may be wrong with your distribution,
although it is probably a minor problem.  Check your editing of the
|TXSsite.tex| file.)  The preloaded format will be
written to the file |texsis.fmt|.

\itm\llap{\square\qquad}%
Copy or move various files to where they need to be:
\enumerate
\itm
Copy the format file to the place where your version of \TeX\ looks for
pre-loaded formats.  On Unix systems this is usually
\example
|/usr/local/share/texmf/tex/formats|.  
\endexample
or some variation of this.
For VMS machines make sure the file is in the directory named by
|$TEX_FORMATS|.
With PC-\TeX\ the file goes into |\PCTEX\TEXFMTS|.

\itm
Copy the \TeXsis\ style files (which end with the extension |.txs|) to
the place your version of \TeX\ usually looks for input.  Under Unix
this should be
\example\obeylines
|/usr/local/lib/tex/inputs|
(or sometimes |/usr/local/lib/tex/macros|).
\endexample
For VMS machines make sure these files are in the directory included
in the path defined by the |TEX_INPUTS| logical. For PC-\TeX\ the
proper place is |\PCTEX\TEXINPUT|.

\itm
If you have any run-time patches to add to \TeXsis\ copy the 
file |TXSpatch.tex| to the same \TeX\ inputs directory.
If there is a |TXSpatch.tex| from a previous release of \TeXsis\ you
should be sure to remove the old file if it is not being replaced.

\endenumerate

\itm\llap{\square\qquad}%
Having created the format file, you need to make a command |texsis| to
run \TeX\ using it. The way to do this is very dependent on the
operating system.

\enumerate

\itm
On a Unix system running \TeX~3.0 or higher you need only to make a link
to the executable |virtex|\index{virtex} with the same name as the
format you want to load.  |Virtex| probably lives in |/usr/local/bin| or
some similar place.  The command to make the link is something like:
\example
|ln /usr/local/bin/virtex /usr/local/bin/texsis|
\endexample

For \TeX\ versions 2.9x you can build an ``undumped'' version of
\TeXsis.  You will have to see the \TeX\ distribution notes for a
description of |undump|. \index{undump} However, this is now a very old
version of \TeX\ (as of this writing \TeX\ is up to version~3.1415), so
you should seriously consider upgrading to a newer version of \TeX.


If you are going to create a ``private'' version of \TeXsis\ rather than
installing it for the whole system then you need to add your \TeXsis\
directory to the environment variables |TEXFORMATS| and |TEXINPUTS| and
define the command |texsis| as follows.  For the C-shell, put in your
|.cshrc| file:
\example\obeylines
|alias texsis virtex \\\&texsis|
|setenv TEXSIS_LIB $HOME/texsis/|
|setenv TEXFORMATS ".:$TEXSIS_LIB:$TEXFORMATS"|
|setenv TEXINPUTS  ".:$TEXSIS_LIB:$TEXINPUTS"|
\endexample
(This assumes that |TEXFORMATS| and |TEXINPUTS| are already properly
defined.  If not, insert the proper directories.)  

\itm
Under VMS, place in your |login.com| file the commands
\example\obeylines
|$ DEFINE TEXSIS_LIB| \meta{disk}|:[|\meta{directory}|]|
|$ TEXSIS :== $TEX$:TEX.EXE &TEXSIS_LIB:TEXSIS|
\endexample
where |TEX$| is the logical name for the main \TeX\ directory. You can
also put these commands in a \TeX\ initialization |.COM| file.



\itm
For PC\TeX\index{PCTeX@{PC\TeX}} you should find in the distribution a file
|TEXSIS.BAT|. If you don't, you can create it.  The file should contain:
\example\obeylines
|ECHO OFF|
|\PCTEX\TEX  &TEXSIS %1 /F 25000|
\endexample
(Replace the |TEX| command with |TEX386| or |TEX386b| if appropriate for
your machine.  For PC-\TeX\ versions 3.14 and greater the |/F 25000| is
no longer needed.)
Either put this file
in a directory in your command path or add the directory it is in 
to your |PATH| statement. 
If you want to be able to load a patch file then you should also
include a line such as 
\example
|\def\TXSpatches{C:/TEXSIS/TXSpatch}|
\endexample
in the |TXSsite.tex| file.  Because \TeX\ and MS-DOS both use
backslashes for their own purposes the path is specified with {\sl
forward} slashes; 
DOS understands them to be the same as a backslash.

\endenumerate
\endenumerate

\bigskip\goodbreak

      After these steps have been carried out, \TeXsis\ should be
installed and available to you, and to other users if installed
system-wide. The command
\example
|texsis| {\sl name}
\endexample
should run \TeXsis\ on the file {\sl name}|.tex| and produce the file
{\sl name}|.dvi|, which can be printed like any |.dvi| file.
A good test is to go to the \TeXsis\ source directory (or the
documentation directory, if the documentation files |TXS|$xxx$|.doc|
have been put in a separate directory) and say
\example
|texsis Manual|
\endexample
On the first try this will produce several warning messages coming from
undefined tags for forward references. These will be defined later in
the document and saved in the file |Manual.aux|; Running \TeXsis\ a
second time should produce the \TeXsis\ manual with no errors.

%>>> EOF TXSinstl.doc <<<