diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:45:48 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:45:48 +0000 |
commit | 5dc602d16c5be2fd035b254ca23484a90aebd6dc (patch) | |
tree | 72efb15fba318cc2096a8cc6999ed3fa0bff317d /Master/texmf-dist/doc/texsis/base/TXSintro.doc | |
parent | b4fc5f639874db951177ec539299d20908adb654 (diff) |
doc 5
git-svn-id: svn://tug.org/texlive/trunk@81 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/texsis/base/TXSintro.doc')
-rw-r--r-- | Master/texmf-dist/doc/texsis/base/TXSintro.doc | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texsis/base/TXSintro.doc b/Master/texmf-dist/doc/texsis/base/TXSintro.doc new file mode 100644 index 00000000000..6c8e1d60256 --- /dev/null +++ b/Master/texmf-dist/doc/texsis/base/TXSintro.doc @@ -0,0 +1,353 @@ +%% 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 <<< |