%% 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 <<<