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

%% file: TXSfmts.doc - Formats and Style Files - TeXsis version 2.18
%% @(#) $Id: TXSfmts.doc,v 18.3 2001/04/06 21:52:07 myers Exp $ 
%======================================================================*
% (C) copyright 1994-2000 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\bs \texsis\input TXSdocM.doc\input Manual.aux\fi

\section{Style Files and Specialized Formats      \label{sect.fmts}}

Section~\use{sect.papers} described the basic layout of a \TeXsis\
document and the |\paper|, |\preprint|, |\Manuscript| and |\book| macros
for typesetting simple documents.  It is often necessary to modify the
details of the layouts for such documents, particularly when submitting
camera ready manuscripts for conference proceedings.  Since \TeXsis\  is
built on plain \TeX, you can of course use the full power of \TeX\  to
format a document as you please.  However, \TeXsis\  contains macros to
produce documents in several of the common formats used in the physics
community.  These and other specialized formats are described in this
section.

It would be very inefficient for \TeXsis\  to load the definitions of all
of the possible document styles listed below when at most only one of
them will be used.  \TeXsis\  therefore puts these specialized
definitions in files known as ``style'' files (which generally have
filename extensions of ``|.txs|'') and only loads the particular style
file when it is needed.  Besides saving space this also allows for quite
a bit of flexibility, because it is easy to modify style files or to
create new ones.  For example, if the proceedings of a conference must
be typeset in a particular way (as is often the case) then the commands
to set-up a document in exactly the right way can be put in a style file
and e-mailed to all conference participants.  Another use of specialized
style files is to define a \cs{thesis} format which conforms to the
rules and regulations of a particular university.


%=========================*
\subsection{Specialized Document Styles         \label{sect.styles}}

The following styles for various conference proceeding formats,
journals, and thesis formats are distributed with \TeXsis~\fmtversion.
Use these in place of |\paper| or |\preprint|.  The name of the style
file from which the definitions are loaded is shown in brackets.
%
\description{XNorthHollandTwo\quad}\clump
%
\itm{\CS{AIPproceedings}}
Similar to |\paper|, but specialized to the American Institute of
\hbox{Physics} (AIP) format. [AIP.txs]
%
\itm{\CS{IEEEproceedings}}
An IEEE format using oversized double column paper. See \Sect{dcol}.
[IEEE.txs] 
%
\itm{\CS{IEEEreduced}}
An IEEE format reduced to 75\% of full size and printed with 9~pt.\
type for $8\frac{1}{2}\,{\rm in} \times 11\,{\rm in}$ paper.  [IEEE.txs]
%
\itm{\CS{NorthHolland} }
Format for producing camera-ready copy for proceedings published by
North-Holland/Elsevier.  This is a single column format with titles
and authors left justified and in eleven point type. [Elsevier.txs]
%
\itm{\CS{NorthHollandTwo}}
The North-Holland double column format for oversized paper.
[Elsevier.txs]
%
\itm{\CS{nuclproc}}
The ``NUCLPROC'' style for Nuclear Physics Proceedings. [nuclproc.txs]
%
\itm{\CS{WorldScientific}}
Similar to |\paper|, but specialized to the World Scientific
proceedings format.  [WorldSci.txs]
%
\itm{\CS{PhysRev}}
Emulates the page layout and appearance of the {\sl Physical Review}.
[PhysRev.txs] 
%
\itm{\CS{PhysRevManuscript}}
Similar to |\Manuscript| but customized for papers submitted to the
{\sl Physical Review}. [PhysRev.txs]
%
\itm{\CS{thesis}}
Similar to \cs{book}, but for printing a thesis.  The default
|\thesis| format conforms to the requirements of the Yale
Graduate School, but it can (and probably should) be modified for
your own installation.  [thesis.txs]
%
\enddescription
Other even more specialized styles are available, and some of them
can be found on the \TeXsis\  anonymous ftp server, in the directory
|/pub/texsis/styles|. 

\bigskip

The IEEE and North Holland double column formats in the list above use
the double column macros described in Sect.~\use{sect.dcol}.  For
example, \cs{NorthHollandTwo} sets up a document with an overall width
of 21.3~cm, a page length of 27.1~cm and a column width of 10.0~cm.
(Note that this is just about as wide or a little wider than most
small laser printers can print, so provisions have been made for
shifting the printed page horizontally to print one column at a time
if necessary.)  A document printed with this format might have the
following basic structure:
\TeXexample
|smalltt\texsis
\NorthHollandTwo   % set up double columns
\titlepage         % but still single column mode

    |<title page material>

\endtitlepage      % ends the title material
\doublecolumns     % now start double column mode
   
    |<text of paper>

\enddoublecolumns  % balance the final columns
\bye
|endTeXexample
\noindent 
Saying \cs{NorthHollandTwo} only defines the double column layout; it
does not turn on double column mode.  The title material is printed in
single column format across the full page width, then the main body is
printed in double column format once \cs{doublecolumns} appears.  It is
important to say \cs{enddoublecolumns} at the end of the document to
balance the columns on the last page.  Formatting text in balanced
double columns can be quite tricky, so you should read \Sect{dcol}
carefully before trying to use any of the double column macros.

%==============================*
\subsubsection{Physical Review Formats}

The \CS{PhysRevManuscript} style is similar to \cs{Manuscript} but is
customized to satisfy the requirements for manuscripts submitted to
the {\sl Physical Review}.  It uses true double
spacing, and it places the tables and figure captions at the end of
the document. By simply switching from this to \cs{preprint} you should
be able to produce a version suitable for distribution as a preprint
from the same manuscript file.

The \CS{PhysRev} and \CS{PhysRevLett} styles are not intended for
submission but rather emulate the page layouts in the {\sl Physical
Review} and {\sl Physical Review Letters} respectively.  We have
attempted to reproduce accurately the double column layout, headlines,
footlines, reference style, etc., used in the actual journals.  This
is still work in progress, but it may be useful both to see how a
paper would look in print and as an example for constructing other
styles.  Setting up the headlines and page numbering requires calling
a few extra macros:
%
\example
|\texsis| \n
|\PhysRev| \n
|\TitleBanner{|\meta{Running Title Headline}|}| \n
|\AuthorBanner{|\meta{Running Author Headline}|}| \n
|\VolumeBanner{|\meta{series}|}{|\meta{vol}|}{|\meta{issue}%
|}{|\meta{page}|}| \n
|\titlepage| \n
...
\endexample
%
In |\VolumeBanner| the \meta{series} should be one of A, B, C, D, E,
for the {\sl Physical Review} or L for {\sl Physical Review Letters};
the volume, issue, and starting page arguments are self-explanatory.
Both \CS{PhysRev} and \CS{PhysRevLett} typeset the document in double
columns, so to make full use of these layouts you will need to read
about the double column macros described in \Sect{dcol}. 
In particular, you should be aware of the following: in both the
\CS{PhysRev} and \CS{PhysRevLett} styles, double column mode is begun
automatically at the end of the title material (\cs{endtitlepage}).
Since any double column material is inside a group, any definitions made
at that point will only be defined inside that group.  If you want to
define macros for use in the rest of your paper, you should do so before
the title material (or use \cs{gdef}).


%=========================*
\subsubsection{Thesis or Dissertation Format}

The style file {\tt \idx{thesis.txs}} contains two alternative
definitions of \CS{thesis}, one for Yale University (called
|\YaleThesis|) and the other for the University of Texas at Austin
(called |\UTthesis|).  The default is that saying \CS{thesis} gives you
|\YaleThesis|, but this is easily changed by saying |\let\thesis=\UTthesis|.

If you are not at Yale or UT you will need to change the
macros in |thesis.txs| to create your own version of the \CS{thesis}
macro.  Every university has different requirements for how a thesis is
typed or typeset, and these requirements often conflict.  Perhaps the
first thing you should do if you want to write a thesis using \TeXsis\
is find out if someone else at your university has already done so, and
then copy their definition of \CS{thesis}.  If you end up creating a
new style file for your university then we hope that you will make it
available for other students to use.  We would also be willing to help,
by putting such style files on the \TeXsis\  anonymous ftp server.
If you have such a file (or other macros) you would like to contribute,
send us e-mail at {\tt texsis@texsis.org}.


%=========================*
\subsection{Creating New Styles}

It is very easy to create a new document style and style file.
By convention, \TeXsis\  style files end with the filename extension
``|.txs|,'' so all you need to do is put the definitions and macros
defining this new document style into such a file, and then read that
file in when beginning the document.  For example, suppose you create a
style file called |mine.txs| which contains a document style called
|\mystyle|, which is a slightly altered version of \cs{paper}:
\TeXexample
\def\mystyle{\paper
   \hsize=|<dimen>
   \vsize=|<dimen>
   \showsectIDfalse
   ...
   }
|endTeXexample
\noindent
You could then simply read in this file at the beginning of the document,
with \cs{input}, and then invoke |\mystyle|, like so,
\TeXexample
\input mine.txs
\mystyle
|endTeXexample

However, you may have noticed that none of the special document styles
mentioned in \Sect{styles} were actually loaded with \cs{input},
although they are in fact read from a style file.  This was done using
the \CS{autoload} command.  Saying 
\TeXexample
\autoload\AIPproceeings{AIP.txs}
|endTeXexample
defines |\AIPproceeings| to be a simpler instruction which, if invoked,
automatically loads the style file |AIP.txs|, which contains the real
definition of |\AIPproceedings|.  After the style file has been loaded
this real |\AIPproceedings| is automatically called.  It then appears as
if the definition of the macro was in \TeXsis's memory all the time,
though it really was only loaded from the file when called for.

As a practical example of using \CS{autoload}, suppose that you are a
student at Excited State University and you want to create a customized
\cs{thesis} macro which will load automatically from a style file called
|ESUthesis.txs|.   You could copy the macros in the file |thesis.txs|
to this new file, and then edit them as needed.  Then, to make the
new definition load automatically you would say
\TeXexample
\autoload\thesis{ESUthesis.txs}
|endTeXexample
\noindent
To make this new definition of \cs{thesis} available to
anyone using \TeXsis\  on your machine you would want to put this
\CS{autoload} command in the file |TXSsite.tex| before building the
\TeXsis\  format.  This is described in more detail in Appendix~\use{install}.
To make the new definition automatically available just to you in your
thesis directory you could put the command in a file called
|TXSmods.tex| in that directory.

Important note: many \TeXsis\  style files and source files use the ``|@|''
character in the names of macros which are to be ``hidden'' from the
casual user.  Since ``|@|'' is not a letter these macros can't normally
be used.  If you are writing a style file which needs to use these
hidden macros you should say \CS{ATunlock} first, to make ``|@|'' a
letter, and then  \CS{ATlock} when you are done to turn ``|@|'' back
into a non-letter.




\Ignore  % The stuff below is maybe way too technical?

You may also need to make changes in some of more complicated macros.
This is most easily made by copying the original definition from one
of the |TXSxxxx.tex| files into |mine.txs| and editing it.  For
example, if you want the abstract to be in 9~pt.\  type, copy the
definition of |\abstract| from |TXStitle.tex| and add |\ninepoint| to
it:
%
\TeXexample
|smalltt\def\abstract{% begin abstract of a paper or treatise
   \endmode                    % end any previous field
   \bigskip\bigskip            % some space above
   \centerline{ABSTRACT}%      % ``ABSTRACT''
   \medskip                    % space below that
   \bgroup                     % begin \abstract group
   \let\endmode=\endabstract   % \endmode ends \abstract
   \narrower\narrower          % bring in margins
   \ninepoint                  % NEW FOR \mystyle STYLE
   \singlespaced}              % single spaced
|endTeXexample

While some of the macros you need to change may be complicated, the
changes \hbox{you} will actually need to make will probably still be fairly
simple.  For example, in the definition of |\section| in |TXSsects.tex|
you probably want to change only the part that actually prints the
section heading.  This is a small part of the whole and is reasonably
well commented.  The default is to print the section head left
justified, ragged right, with a hanging indentation whose width is set
by the section number:
%
\TeXexample
|smalltt%
%  Print the Section title:
%
   \ifx\tbf\undefined\def\tbf{\bf}\fi      % default \tbf is \bf
   \vbox{%                                 % keep heading in \vbox
     {\raggedright                         % 
     \pretolerance=2000\hyphenpenalty=2000 % no hyphenation
     \setbox0=\hbox{\noindent\tbf\@fullID}%% find width of ID
     \hangindent=\wd0 \hangafter=1         % for hanging indent
     \noindent\unhbox0{\tbf{#1}}\relax     % number and title
     \medskip}}%                           %
   \nobreak                                %
|endTeXexample
%
If instead you want the section headings to be centered with two
spaces (|\  \  |) after the number, you can replace this part of the
|\section| macro 
%
\TeXexample
|smalltt%
%  Print the Section title:
%
   \ifx\tbf\undefined\def\tbf{\bf}\fi      % default \tbf is \bf
   \vbox{%                                 % keep heading in \vbox
     {\raggedcenter                        % USE RAGGED CENTER
     \tbf\@fullID\  \  #1                    % ID AND TITLE
     \endraggedcenter                      % END RAGGED CENTER
     \medskip}}%                           %
   \nobreak                                %
|endTeXexample
%
\noindent 
You can leave the rest of the \cs{section} macro alone and it will work
as before.

\endIgnore



%==================================================* 
\subsection{Overhead Transparencies (Slides)}

\TeXsis\  contains a simple \CS{slides} format for making overhead
transparencies or similar material.
While \TeX\  is not a convenient language for graphical page layout, it
is sometimes useful to be able to convert a paper to transparencies or
visa versa.\Footnote*{However, until recently one of the
authors of \TeXsis\  preferred to make neatly lettered transparencies by
hand, using colored pens, rather than using a printer that could only
print in black and white.
He's changed his mind now that it is possible to produce text
in color.}
If you want to use |\slides|, simply begin your manuscript file with 
%
\TeXexample
\slides
|endTeXexample
instead of (or in addition to) |\texsis|.
%
This will produce
%% NOT ANYMORE  $8\frac{1}{2}\,{\rm in} \times 10\frac{1}{2}\,{\rm in}$ 
pages with $1\,{\rm in}$ margins in
the ``portrait'' orientation with 24~pt.\  type, with a ragged right
margin and lots of incentive to suppress hyphenation.
%% NOT ANYMORE and bottom margins.  
\CS{slides} also defines \CS{bl} to insert a blank line and
\CS{np} to create a new page, since these are often useful for slides.
Since the \CS{slides} format is very simple, it is not loaded from a
style file.

%==================================================* 
\subsection{Color PostScript Output             \label{sect.color}}

Now that color printers are fairly common, it is useful to have some
way to produce text that is printed in different colors.
The simplest use of this is for producing overhead transparencies, as
with the \CS{slides} format.
\TeXsis\  has a simple set of macros, in the style file {\tt
color.txs}, which lets you change the colors of text printed using
PostScript.
This only works for PostScript output produced by\index{Rokicki,
Tomas} Tom Rokicki's {\tt dvips} program,\cite{Rokicki} using the
profile file {\tt color.pro} that is usually included with {\tt
dvips}.

To use these macros, you must first input the definitions,
\TeXexample
\input color.txs
|endTeXexample 
To change the color of all text which follows, use the command \CS{SetColor},
as in 
\TeXexample
\SetColor{Green} 
|endTeXexample 
Keep in mind that this will change \undertext{all}
text, including page numbers and headlines and footlines.  To print a
small portion of text in some other color, use
\CS{colorit},
as in 
\TeXexample
\colorit{Red}{The text inside these brackets is colored Red}
|endTeXexample
You can change the color of the background using \CS{background},
as in 
\TeXexample
\background{Yellow}  
|endTeXexample

\bigskip
\pagecheck{2in}

The 12 basic colors available are
\example
\settabs 4\columns
\+&     Black     &        White     &      Gray   \cr
\+&     Red       &        Green     &      Blue   \cr         
\+&     Cyan      &        Magenta   &      Yellow \cr         
\+&     Purple    &        Orange    &      Brown  \cr
\endexample
Note that the case is important---the names must begin with an initial
capital letter.

For the basic colors listed above some shortcuts are also defined.
Specifically, you can simply use the color name as a command, with the
text to be colored as a single argument, as in
\TeXexample
\Red{This text is colored Red}
|endTeXexample
or you can say |\text|\meta{Color} to change the text color,
as in 
\TeXexample
\textGreen
|endTeXexample
You can add shortcuts for other colors besides the basics
with the \CS{addColor} command.  Saying
\TeXexample
\addColor{Salmon}    
|endTeXexample
will define |\Salmon| and |\textSalmon| as shortcuts
for |\colorit{Salmon}{|\meta{text}|}| and |\setColor{Salmon}|.

Although the basic colors listed above should be enough for most
simple applications, there are actually a whole host of other colors
available.  In fact, all of the colors found in a box of 64 Crayola
Crayons are defined in {\tt color.pro} for |dvips|.  You can define
short-cuts for all of these simply by saying \CS{Crayolas}.
You can produce a list of all of the colors, with each printed in its
own color, by saying \CS{ListColors}.

The commands so far have just about the same syntax as those in the
macro package called {\tt COLORDVI.TEX}, by Jim
Hafner\reference{colordvi} Hafner, Jim, the {\tt COLORDVI.TEX} macros
are included in the {\tt dvips} distribution. See \Ref{Rokicki}
\endreference\space
(although the internal workings are slightly different).
Any plain \TeX\  file which uses {\tt COLORDVI.TEX} should also work
using {\tt color.txs}.
But the {\tt color.txs} macros also include commands to specifically
manipulate the PostScript color stack.
To change the color temporarily by pushing it onto the stack, and then
revert to the previous color by popping the stack, use \CS{PushColor}
and \CS{PopColor}, as in
\TeXexample
This text is in some color, probably black.
\PushColor{Purple}   
This text will be purple.
\PopColor
This text will be back in the previous color.
|endTeXexample 

Be aware that the color changes have nothing to do with TeX's grouping
mechanism (\ie\  curly brackets), but are based only on the PostScript
color stack.
If you really want the color to change back when a \TeX\ group ends
(whenever that might happen), you can use
\cs{aftergroup}, as in 
\TeXexample
\begingroup\PushColor{Red}\aftergroup\PopColor
|endTeXexample
Then later when the group is ended, the \CS{PopColor} is automatically
executed and the color reverts to its previous value.
One nice way this can be used is to color all displayed equations,
by putting this all in \cs{everydisplay}, like so
\TeXexample
\everydisplay={\PushColor{BurntOrange}\aftergroup\PopColor}
|endTeXexample
A displayed equation is always constructed within a new group, and
when it ends the \CS{PopColor} on the \cs{aftergroup} stack is invoked
automatically and the text reverts to the previous color.

\bigskip


If the 64 colors listed by \CS{ListColors} are not enough for your
purposes, you can also define your own, using \CS{SetCmykColor} or
\CS{PushCmykColor}.
Colors are specified as a quadruple of intensity values between 0.0 and 1.0
(CMYK means Cyan, Magenta, Yellow, and blacK).  For example:
\TeXexample
\SetCmykColor{.2 .3 .4 .1}   
|endTeXexample
will give you a nice tan,  while 
\TeXexample
\PushCmykColor{.5 .5 .1 .2}  Old Blue Eyes  \PopColor
|endTeXexample 
will print the text in the shade of blue specified by that particular
CMYK quadruple.


%==================================================* 
\subsection{Twin Page Output}

It is sometimes desirable to produce preprints or other documents in a
compact format with two pages on each physical page in landscape
orientation. While this can be done with \cs{SetDoubleColumns}, a much
simpler approach is sufficient. \TeXsis\  contains a macro called
\CS{twinout} which redefines the output routine to produce two pages
per page, without attempting to balance columns or allowing spanned
equations, tables, etc. (thus avoiding many of the possible problems
with the more powerful double column macros). \CS{twinout} can be used
with any of the standard formats described in \Sect{papers} or
\Sect{fmts} or even with Plain \TeX.  Since \CS{twinout} does not
select fonts, the user must do so:\index{twin page output}
%
\TeXexample
\texsis
\tenpoint
\def\Tbf{\twelvebf}
\def\tbf{\tenbf}
\twinout
 |<text>
|endTeXexample
Alternatively, the \CS{twinformat} command can be used to produce any
\TeXsis\  format in \CS{twinout} layout with 10~pt fonts. Thus the above
commands can be replaced by 
\TeXexample
\texsis
\twinformat
 |<text>
|endTeXexample
Here \CS{twinformat} automatically sets up 10~pt fonts and appropriate
values for the title bold face fonts, just as in the previous example.
\CS{twinout} use the following dimensions:
%
\description{Xnormhsize\qquad}\clump
%
\itm{\CS{twinhsize}} 
Total width for twin column output.
%
\itm{\CS{twinvsize}} 
Column height for twin column output.
%
\itm{\CS{twincsize}} 
Column width for twin column output.
%
\itm{\CS{normhsize}} 
Normal value of \cs{hsize} in portrait mode.
%
\itm{\CS{normvsize}} 
Normal value of \cs{vsize} in portrait mode.
%
\enddescription
All of these have sensible default values for $8.5\,{\rm in} \times
11\,{\rm in}$ paper but can be reset before \CS{twinout} is called. The
"normal" sizes should print properly with the default device driver
and printer. Appropriate default values for all these dimensions can
be set in |TXSsite.tex|.

   \CS{twinout} puts \cs{LandscapeSpecial} on each page. This is null by
default but can be redefined to be an appropriate \cs{special} command
to produce landscape output with your device driver and printer. For
example, with |dvips|\cite{Rokicki}\index{dvips}\index{Rokicki, Tomas}
and a PostScript printer, use 
\TeXexample
\def\LandscapeSpecial{\special{papersize=11in,8.5in}}
|endTeXexample
A default value can be set in |TXSsite.tex|.

   \CS{twinprint} is a substitute for \cs{preprint} which sets the
title, author, and other titlepage material full size in landscape mode
and then switches to \CS{twinout} twin column output with 10~pt type for
the text of the paper. A typical preprint might read:
\TeXexample
\twinprint
\titlepage
\title
 |<paper title>
\endtitle
\author
 |<author's name and address>
\endauthor
\abstract
 |<text of abstract>
\endabstract
\endtitlepage
 |<text of paper>
\bye
|endTeXexample
\nobreak\noindent
This produces a nice, compact format for preprints. 

%>>> EOF TXSfmts.doc <<<