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

%% file: TXSintro.doc - Manual Intructions - TeXsis version 2.18
%% @(#) $Id: TXSintro.doc,v 18.2 2000/05/17 00:19:46 myers Exp $
%======================================================================*
% (C) Copyright 1989, 1992, 1997 by Eric Myers and Frank E. 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


\section{Introduction               \label{sect.intro}}

 \TeX\  is a computer typesetting system created by Donald
Knuth\index{Knuth, Donald} of Stanford University.
It is described succinctly in his book, \TeXbook.\reference{Knuth}
D.E.~Knuth, 
\booktitle{The \TeX book} (Addison-Wesley, 1986)
\endreference
\TeX\  is especially well suited for typesetting technical material
containing mathematical symbols and equations.
As a result, \TeX\  in one form or another is now used by almost all
mathematicians and most physicists for writing scientific papers and
related documents.
The journals of the American Mathematical Society are typeset with
\TeX, and the journals of the American Physical Society now accept
manuscripts written in \TeX.
A large number of physicists also distribute preprint
(pre-publication) versions of their papers, known as ``e-prints,'' via
an archive server based at the Los Alamos National Laboratory.
\TeX\  in some form is the {\it de facto} standard for such papers.

There are actually several different ``flavors'' of \TeX.
One of the reasons that \TeX\  is so useful is that it has a powerful
macro capability --- to the point that \TeX\  can actually be
considered to be a computer ``language.''
As a result, there now exist a number of macro packages, or
``formats,'' which either extend or replace the basic \TeX\  language
of \TeXbook\  (which is commonly known as ``plain'' \index{plain TeX@{plain
\TeX}}\TeX) by adding more advanced features or commands appropriate
to more specialized types of documents.
\TeXsis\  is one such macro package, designed specifically (but not
exclusively) for physicists.
\TeXsis\  provides the author with many useful commands with are either
not available or not easily implemented by the casual user of plain
\TeX.
Among these are the ability to automatically number equations,
references, figures and tables, and to refer to these ``numbered''
objects easily by symbolic names which are independent of the values
assigned to them when the document is processed.
\TeXsis\  makes it easy to change the type style or size, and to
control other aspects of the formatting.
\TeXsis\  also includes special macros for printing in double columns
and for constructing ruled tables.
It is easy with \TeXsis\  to produce more specialized documents, such
as letters, referee reports, and memoranda, or even a thesis or a book.

Many physicists are now familiar, at least by name, with another
\TeX-based format, the REVTEX package from the American Physical
Society.
REVTEX is in turn based on a more general format, known as
\LaTeX.\reference{LaTeX}
L. Lamport, 
\booktitle{\LaTeX, A Document Preparation System}, 
(Addison-Wesley, 1985)
\endreference
\index{latex@{\LaTeX}}
Unfortunately, \LaTeX\  differs from plain \TeX\  in several subtle but
important ways, so that documents created using plain \TeX\  cannot be
used with \LaTeX.
In contrast, \TeXsis\  is functionally a superset of plain TeX, so that
everything described in \TeXbook\  will also work in \TeXsis\  (even
though the internal workings of some of the plain \TeX\  macros have
actually been modified).
This means that \TeXsis\  documents can also make use of just about any
of the many smaller macro packages designed for use with plain \TeX,
or an author can make use of the methods and tricks described in
\TeXbook.
Unfortunately, it also means that REVTEX and \TeXsis\  are mutually
incompatible.

\bigskip

This manual explains how to use \TeXsis.
Since it is a user's guide, it makes no attempt to describe how the
various macros work; for that one should consult the source code,
which is extensively commented.
However, we do assume that the reader is already familiar with
\idx{plain} \TeX.
If you don't already know plain \TeX, a good way to learn is to read
and work through the exercises in 
\booktitle{A Gentle Introduction to \TeX} by Michael~Doob.\reference{Doob}
M.~Doob, 
\booktitle{A Gentle Introduction to \TeX\  (A Manual for Self-Study)},
(\TeX\  User's Group, Providence).
Also available as a plain \TeX\  file from CTAN or at\n
\URL{ftp://ftp.texsis.org/pub/tex/gentle.tex}
\endreference
The source file for this (called {\tt gentle.tex}) is available on the
\TeXsis\  ftp server, or on CTAN.
You can also start by reading the \TeXbook, paying special attention
to chapters~1-10 and 16-19.
The manual by Spivak\reference{Spivak}
M.~Spivak, 
\booktitle{PC\TeX\  User's Guide.}
(Documentation distributed with PC\TeX)
\endreference
which accompanies PC\TeX\  (which is an implementation of \TeX\  for the
IBM~PC) is also recommended.


%==================================================*
\subsection{Overview of this Manual}

The main topics covered in the several sections of this manual
\linkname{page.itemize}{are}:\tag{page.itemize}{\folio}
\itemize \clump
\itm \Sect{intro} --
An introduction to \TeXsis\  and the philosophy behind the macros, and
instructions on how to begin using \TeXsis.

\itm \Sect{fonts} -- 
Selecting sizes and fonts of type, choosing single, double, or triple
spacing, and automatically handling quotation marks.
      
\itm \Sect{eqns} -- 
Automatic numbering of equations, automatic sizing of parentheses and
brackets, and special symbols for physics equations.

\itm \Sect{refs} -- 
Defining new references, for which numbers are assigned automatically,
citing references already so defined, and making a list of references.

\itm \Sect{labels} --
Labeling things like section numbers, figures, items in an outline, or
page numbers, and referring to them in other parts of the document.

\itm \Sect{papers} -- 
Producing a complete paper, including the title page, chapters,
sections, subsections, and appendices, a table of contents, running
headlines, and an index.
How to use the "master file" concept to split a long document into
several files.

\itm \Sect{figures} -- 
Producing automatically numbered tables and figures and producing
ruled tables.

\itm \Sect{envmt} -- 
Displaying text in special ways using "environments," including those
for centered lines, lists of things, listings of computer programs, and
\TeX\  examples.

\itm \Sect{fmts} -- 
Using specialized layouts for journals and conference proceedings, and
creating new ones.

\itm \Sect{letr} --
Typing letters, form letters, memos and referee reports.

\itm \Sect{dcol} --
Producing double column output.

\itm \Sect{misc} --            
Miscellaneous macros for ignoring text and doing various other useful
things, and a checkpoint/restart feature for printing very long documents.

\enditemize                             

Several appendices are also included to deal with more technical
matters. 
%
Appendix~A explains how to install \TeXsis\  on Unix computers, on a
VAX/VMS system, and on an IBM~PC.  It also explains how to customize
\TeXsis\  for your own installation.  Appendix~B lists changes that have
been made to \TeXsis\  in recent revisions.   Appendix~C lists the fonts
usually available with \TeXsis.

Two examples of \TeXsis\  documents are included in the standard
distribution.  The first, in the file |Example.tex|, is a short
(3~pages) example of a physics paper typeset with \TeXsis.  The second
is this manual itself, which was also created with \TeXsis.  If you
would like to look at the files used to create the Manual, the master
file is called |TXSdoc.doc|, and the various sections of the document
are in files with names of the form |TXS|$xxxx$|.doc|.  For those who
are comfortable programming in \TeX\  it is possible to extract specific
macros from the \TeXsis\  source code or to modify or even rewrite these
macros.  The source code is contained in files with names of the form
|TXS|$xxxx$|.tex|.  We have tried wherever possible to include 
at least somewhat
illuminating comments in the source code.

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

\subsection{Getting Started                \label{sect.start}}

  Assuming that \TeXsis\  has been properly installed on your computer,
using \TeXsis\  is as simple as using \TeX\  or \LaTeX.
To run \TeX\  with the \TeXsis\  format to process a manuscript file
called |myfile.tex| you simply give the command:
\index{running@{running \TeXsis}} 
\def\HeadText{Getting Started}
\TeXexample
texsis myfile 
|endTeXexample 
As with any version of \TeX, the output from \TeX\  is put in the file
|myfile.dvi|, which you may view on your computer terminal or print on
a laser printer or other output device. 

   Since \TeXsis\  is a superset of plain \TeX, any file that you
process with plain \TeX\  can be processed with \TeXsis, and you will
get the same results.
In particular, plain \TeX\  defaults to 10~pt.\  type and single spacing
between lines, and so does \TeXsis\  unless you initialize its special
features.
But since you are probably using
\TeXsis\  because of these special features, you should begin your
manuscript file with the initialization command
\TeXexample                                          
\texsis                                          
|endTeXexample 
\noindent
One of the things this command does is switch the output to 12~pt.\  
type, double spaced, which generally looks better on a small laser
printer.  Commands that allow you to change the type size or line
spacing yourself are described in \Sect{fonts}.  More
specialized initialization commands may be used in place of (or
in addition to) the |\texsis| command when you are using a
pre-defined document layout.  These are described in
\Sect{fmts}.
                                                     
   Note also that just as in plain \TeX\  there is a difference
between uppercase and lowercase letters in control word names.
Thus if you say \cs{TeXsis} instead of \cs{texsis} you won't
initialize any special features but you will print out
``\TeXsis.''


%==================================================*
\newpage
\subsection{Some Philosophy               \label{sect.philosophy}}

In designing the \TeXsis\  macros we have tried to follow some basic
guidelines which we feel make \TeXsis\  a more useful tool.
It may help you while learning about \TeXsis\  to know what these
guidelines are, especially if you are already familiar with other
\TeX\  macro packages.
However, you can skip this section without missing anything important
to a first time user.

The guidelines we have followed are:  \index{philosophy}

\itemize
\itm
\TeXsis\  is a superset of plain \TeX, so that anything
you can't do in \TeXsis\  (and even those that you can) can be done
with plain \TeX\  instead. \index{compatibility!with@{with plain \TeX}}
This also means that \TeXsis\  is compatible with most plain
\TeX\  macro packages, such as |epsf.tex| and |index.tex|, or other
specialized macro sets.\Footnote\dag{We cannot completely guarantee this
because other macro packages might define macros with the same names as
used by \TeXsis, although we have taken several steps to prevent this
kind of conflict.} Even if some of the plain macros are actually
redefined in \TeXsis, they are required to still behave as described in
\TeXbook.

\itm
When a \TeXsis\  macro is similar to a plain \TeX\  macro it should, when
possible, have a similar name and syntax.  \index{macros!syntax} Thus
\cs{Footnote} in \TeXsis\  is used exactly like \cs{footnote} in plain
\TeX, and in ruled tables ``|&|'' and ``|\cr|'' can be used exactly as
they are in an |\halign|.

\itm
Macro names\index{macros!names} will be short and simple, but
descriptive.
Almost all plain \TeX\  macro names are in lower case for ease of
typing, so macros with names containing uppercase letters can
immediately be recognized as being a part of
\TeXsis\  (instead of plain \TeX).  As a general rule though we try
to use lowercase for frequently used macro names for ease of typing.

\itm
There are two different ways in which arguments may be passed to
macros, depending on the length of the argument.
Short arguments are simply enclosed in curly brackets, the way \TeX\
usually handles macro arguments.
For example, the title of a section is created by the
\cs{section}\index{macros!arguments} command with,
\TeXexample
\section{The nonlinear $\sigma$-model}
|endTeXexample
Longer amounts of text (many lines), and text which is considered to be
in a special environment, is enclosed between commands of the
form ``|\thing|'' and ``|\endthing|.''  An abstract, for example, is
typed as,
\TeXexample
|smalltt\abstract
A mechanism for total confinement of quarks, similar to that 
of Schwinger, is defined which requires the existence of 
Abelian or non-Abelian gauge fields.  It is shown how ...
\endabstract
|endTeXexample
This is similar to the |\begin{thing}| {\ttdots} |\end{thing}|
construction in \LaTeX\  \index{latex@{\LaTeX}} but is slightly easier
to type.\Footnote*{And, more importantly, is compatible with plain
\TeX---|\end| signals the end of a document in plain \TeX,
and shouldn't be used for anything else.  However, if you really want
to type |\begin{thing}| and |\end{thing}| you can do so, and \TeXsis\
will understand it to mean |\thing| and |\endthing|.}
The reason for preferring this way of delimiting text or arguments is
that for very long pieces of material it is much easier to look for
something like |\thing| and |\endthing| than it is to count curly brackets.

\itm
The fundamental purpose of \TeXsis\  is to typeset printed words and
\hbox{equations} on a physical piece of paper.
In other ``document mark-up'' languages, including SMGL, HTML, and
\LaTeX, the primary goal is to create in the computer an abstract
representation of a document which is independent of the way the
document is printed.
It can be useful to treat a document this way, and so we sometimes use
similar ideas in \TeXsis, but this approach can also conflict with the
goal of typesetting the document the way an author or editor would
choose.
Whenever there is such a conflict we will err on the side of
``typesetting'' rather than on the ``abstract representation'' of the
document.

\itm
The source code defining the macros should be available to the users,
so that those who want to see how something is done can do so, and
those who want to make their own modifications can do so.
The macro definitions should include sufficient comments that
(usually) someone with only a little bit of experience with \TeX\  can
understand what is going on.
Also, macros which perform similar functions and work together should
be kept in a single file, but separate parts of the whole package
should be kept in separate files.
When possible these individual files should be usable on their own
with plain \TeX.
For example, it is possible to use just the double column macros of
\TeXsis\  by saying |\input TXSdcol.tex|, and the ruled table macros
can be used in plain
\TeX\  by saying |\input TXSruled.tex|.

\enditemize



\newpage

% >>> EOF TXSintro.doc <<<