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

%% file: TXSfigs.doc - Figures and Tables - TeXsis version 2.18
%% @(#) $Id: TXSfigs.doc,v 18.2 2000/05/17 00:19:46 myers Exp $
%======================================================================*
% (C) Copyright 1989, 1992,1993,1994, 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 

% Select the Penguin shown at the end of the section 
% (the one in the middle is always the Feynman diagram).

%\def\penguin{penguin2}  % to use Larry Ewing's Linux Penguin
\def\penguin{penguin}  % to use the Feynman diagram.



\section{Figures and Tables              \label{sect.figures}}

Technical papers often include tables and/or figures.  Regardless of how
the contents of the figures or tables are created, these have a lot in
common in the way they are generally treated. \TeXsis\  makes use of
\TeX's \idx{floating insertion} capabilities (see Chapter~15 of
\TeXbook) to insert figures and tables on the current page or on a
following page.  It is also possible to have figures or tables saved and
printed at the end of the document.  Captions are easily added either
above or below the figure or table.  Both kinds of objects are
automatically assigned numbers, which are associated with internal
labels so that they may be referred to in the text without having to
know their order.  It is possible to create a list of the figures and
tables which appear in a document, much like creating a table of
contents.  Figures themselves
are generally created outside of \TeX, either by hand
or by computer graphics programs, while tables can be created using
\TeX\  commands.  The most complicated tables have vertical and
horizontal lines (called ``rules'') to guide the reader's eye and to
make the table more readable.  \TeXsis\  has some very easy to use
commands for making ruled tables.

Before discussing \TeXsis's figure and table making macros in detail we
should mention that \TeXsis\  also adds a new insertion class to those of
Plain \TeX.  In Plain \TeX\  saying \cs{topinsert}, \cs{midinsert} or
\cs{pageinsert} begins a \idx{floating insertion} (ended by
\cs{endinsert}) which will appear somewhere on the current page or a
following page.  Material entered with a \cs{topinsert} appears at the
top of the current page, if there is room for it, or at the top of the
next page where there is room.  A \cs{midinsert} attempts to insert the
text into the current page right where it is invoked, but if the
insertion won't fit it becomes a \cs{topinsert}. Saying \cs{pageinsert}
creates an insertion which takes up a whole page by itself.
%
In \TeXsis\  you can also say \cs{bottominsert} to make a \idx{floating
insertion} that will appear at the bottom of the current page, if it
will fit, or at the bottom of the next page where it will fit.
There is also \cs{heavyinsert}, which like \cs{midinsert} tries first to
insert the material into the current page right where it is called, but
in this case becomes a \cs{bottominsert} if the material wont' fit.


%==================================================*
\subsection{Figures                     \label{sect.figs}}

\TeX\  is designed for technical typesetting, but does not include a
graphics standard, so to include a figure or drawing in a document
it is necessary to
leave blank space and to either glue the drawing in later or to arrange
for the figure material to be inserted by some mechanism outside of
\TeX\  when the page is actually printed (e.g., using the \cs{special}
command or the \cs{epsfbox} command described later).

      Imagine that you wish to insert into the text a drawing of a
``\idx{penguin} diagram,'' which is about 6~cm tall.  You could create
the space for this figure at the top of a page, along with a caption,
with the following commands:\index{figures}%
\TeXexample
|smalltt\figure{Penguin}
\hrule
\vskip 2cm
\line{\hss (glue your penguin here) \hfil}
\vskip 2cm
\hrule
\Caption
Sample figure showing how easy it is to insert
numbered figures with captions in \TeXsis.
\endCaption
\endfigure
|endTeXexample
\noindent
This produces \Fig{Penguin} (we put the \cs{hrule}'s in just to show
off the empty space).  ``Penguin'' is the 
label for the figure, so to refer to the figure in the text we typed
\CS{Fig}|{Penguin}|, which produced ``\Fig{Penguin}.'' The caption can be
placed either before or after the figure: if it is to be at the top then
\CS{Caption} must be the first token after |\figure|.  As shown, the
caption text must be terminated with \CS{endCaption}.  When the caption is
printed it will automatically start with the figure number in bold type,
followed by the caption text. The caption is indented on both sides if
it is more than one line long and centered otherwise.

      \CS{caption}\arg{text} is equivalent to \CS{Caption}\meta{text}
\CS{endCaption} and may be more convenient for short captions.
It should be avoided for very long captions to keep from overflowing \TeX's
internal memory.

\figure{Penguin}
\hrule
\vskip 2cm
\line{\hss (glue your \idx{penguin} here) \hfil}
\vskip 2cm
\hrule
\Caption
Sample figure showing how easy it is to insert 
numbered figures with captions in \TeXsis.
\endCaption
\infiglist{Sample figure showing how easy it is
to insert numbered figures with captions in \TeXsis.}
\endfigure

  There are commands to create figures for each of the \idx{insertion
classes} of Plain \TeX  (that is,  \cs{midinsert}, \cs{topinsert} and
\cs{pageinsert}) along with the new insertion class
added by \TeXsis\  (\cs{bottominsert}) .
In addition, there are special commands for creating wide or full page
figures while in double column mode (which is described later in
Section~\use{sect.dcol}):
\index{figures!placement}%
\singlelinetrue
\description{XfullFigureXXXXXX}\clump
%
\itm{\CS{figure}\arg{label\/}}
Inserts a figure at the top of the current page, if there is enough room for
it, or at the top of the next available page.
%
\itm{\CS{midfigure}\arg{label\/}}
Inserts a figure at the current position, if there is enough room for it, or at
the top of the next page if there is not.
%
\itm{\CS{fullfigure}\arg{label\/}}
Inserts a figure on a separate page. The body of the figure should
normally contain a \cs{vfill} to allow the figure to stretch to fill the
whole page.
%
\itm{\CS{bottomfigure}\arg{label\/}}
Inserts the figure at the bottom of the current page, if there is room
for it, or on the bottom of the next page where there is room.
%
\itm{\CS{heavyfigure}\arg{label\/}}
Inserts a figure at the current position, if there is room for it on the
page, or at the bottom of the page following if there is not.  This is
therefore like \CS{midfigure}, except that if the figure can't be fit on
the page it ends up on the bottom of a following page, not the top.
%
\itm{\cs{widetopfigure}\arg{label\/}}
Inserts a figure at the top of a page across both columns in
double column format. Equivalent to \CS{figure} in single column
format.  \cs{widefigure} is a synonym. 
%
\itm{\cs{widefullfigure}\arg{label\/}}
Inserts a full page figure across both columns in double column
format.  Equivalent to \CS{fullfigure} in single column format.
%
\itm{\CS{endfigure}}
Ends any of the figure insertions described above.
%
\enddescription
\noindent
In all cases \meta{label\/} is an internal label which is assigned to
the figure number. The figure number will include the chapter and
section numbers in the format ``$cc.ss.nn$'' if \cs{showchaptIDtrue} and
\cs{showsectIDtrue} have been selected.
\index{figures!placement}%

      The body of the figure can include any vertical mode
commands, as in the example above.   When you are simply leaving
space for a figure to be glued in later a convenient way to specify the
amount of space to leave is to \cs{vskip} by some amount proportional to
the width of the current column or page.  The dimension \cs{colwidth} is
the width of the page (the \cs{hsize}) in single column mode and the width
of the current column in double column mode.  So for example, if you
have a figure which was half again as tall as it is wide you could say
\index{figures!size}%
\example
\cs{vskip} |1.5|\cs{colwidth}
\endexample
Another way to standardize the space reserved for figures is to define
your own dimension, such as |\myfigsize|, to use in the \cs{vskip}
above.  For example,
\TeXexample
\newdim\myfigsize
\myfigsize= 1.5\colwidth
|endTeXexample
\noindent
and then |\vskip\myfigsize|.  This has the same effect as the previous
example, but |\myfigsize| can be changed to any valid dimension.
\index{figures!size}%


%==================================================*
\subsection{Encapsulated PostScript Graphics}

Instead of simply gluing figures into a paper by hand it is possible to
have computer generated graphs and drawings automatically inserted into
a document.  Unfortunately, the method can vary from
computer to computer and printer to printer.  Recall that \TeX\
produces as output a \idx{DVI file}, which contains device independent
instructions for typesetting the document. To actually print the
document the \idx{DVI file} must be translated into instructions for
the specific printer being used by a suitable device driver.  It is at
this stage, when the device driver is converting the \idx{DVI file} to
printer instructions, that graphs and drawings may be inserted.
However, since different printers may require different kinds of
instructions, there are many different device drivers, each having its
own way of including drawings in the document.

In recent years some standardization has become possible, because many
printer manufacturers have chosen \idx{PostScript} as the ``language''
for giving instructions to their printers.  PostScript contains
commands both for drawing and for typesetting text.  Still, there are 
some problems, because there are many different device drivers for
converting \idx{DVI file}s to \idx{PostScript}, and they all treat the
inclusion of figures slightly differently.  Also, while all of these filters
require that the drawings to be included are themselves already in
PostScript, there are several variations of \idx{PostScript}, leading to
further problems of incompatibility.

Until there is some standardization for inserting drawings into \TeX\
documents (and perhaps to encourage it) we recommend using the scheme
which (a) seems to be the easiest to use and the most well thought
out, and (b) is potentially available to the widest group of users.
Our choice is, first, to use a specific variation of PostScript known
as ``Encapsulated'' \idx{PostScript} (EPS). 
\index{Encapsulated PostScript|see{PostScript}} Most newer computer
programs which produce graphics output, including Mathematica, |xfig|,
and |paw|, can produce EPS output files.  To include these in the text
we have chosen to rely on the program |dvips| \index{dvips} by Tomas
Rokicki,\reference{Rokicki} Tomas Rokicki, \booktitle{{\tt dvips}
User's Manual}.
The source code for {\tt dvips} is available from CTAN
in the directory  {\tt dviware/dvips}
\endreference 
\index{Rokicki, Tomas} along with his \TeX\  macros for including EPS
graphics, called |epsf.tex|.  Be warned that there are other programs
called ``dvips,'' but as far as we know only Rokicki's version will
work with |epsf.tex|.  We expect that when including drawings in \TeX\
is standardized, it will be based on Rokicki's scheme or something
close to it.

\bigskip

To include EPS graphics in a document using the |epsf.tex| macros you
must first input the macros. Somewhere early in your manuscript file you
should put: 
\TeXexample
\input epsf.tex
|endTeXexample
You can have the macros report the size of a figure when it is
included by saying:
\TeXexample
\epsfverbosetrue
|endTeXexample
At the point where you want a graph or drawing included 
you simply say:
\example
\CS{epsfbox}|{foo.ps}|
\endexample
This will include the drawing from the file called `|foo.ps|,' which must
already exist in the current directory.  \TeX\  will leave enough room
for the figure (by creating a box of the correct size) and will use a
\cs{special} command to insert instructions into the DVI file telling
the DVI to PS translator to read in the \idx{EPS file} |foo.ps|.

Once the document has been processed by \TeXsis\  and the DVI file has
been produced you will convert it to a PS file with the ``\idx{dvips}''
program.  If your DVI file is called |myfile.dvi| then the command is
simply:
\TeXexample
dvips myfile
|endTeXexample
This will convert |myfile.dvi| to PostScript, 
and depending on how dvips is set up at your installation it will either
put the output in the file |myfile.ps| or it will send it directly to
the default printer (see the man pages for dvips on how to change this
behavior, or try a short example to see how it is set up on your computer).
Note that the EPS files to be included must be in the same directory as
|myfile.dvi| when you run dvips, so that they can be merged into the final
output file (or you can specify the full path filename in the
\CS{epsfbox} command). 

On Unix systems you may not be able to use the |lpr -d|
command if you have included EPS files in the document.  This command
runs the DVI file through dvips (or some other DVI to PS filter) in a
different directory, and the EPS files will therefore not be included
unless you have used a full path name for the file.


If you use the latest version of 
the |xdvi| program to preview DVI files on your workstation
you will find that it automatically includes EPS graphics in the
display, but some other previewing programs (such as |texsun|, or older
versions of |xdvi|) will not.  Even if the previewer does not know how
to deal with the \cs{special} commands in the DVI file, you will
see that \TeX\  has left room for the figure.  Once you have converted
your DVI and \idx{EPS file}s into a PS file you can preview that file
if you have a PostScript previewer, such as GhostScript. Then your
graphs and drawings will appear just as they would if you had printed
the PS file.
 
\bigskip

Sometimes you will find that more room has been left for the figure than
is really needed.  The way \CS{epsfbox} decides how much room to leave is
by reading the first part of the \idx{EPS file} to find a line 
which looks like:
\TeXexample
%%BoundingBox: 67 176 544 616
|endTeXexample 
\noindent
The two pairs of numbers are the coordinates of the lower left and upper
right corners of the figure, respectively.  They are measured in
printer's points (1/72${}{\hbox{nd}}$ of an inch).  If you don't like
the positioning of the figure given by the original bounding box in the
PostScript file you can override it by specifying a new bounding box
like so:
\TeXexample
\epsfbox[0 180 540 700]{file.ps}         
|endTeXexample
\noindent
You may have to experiment with positioning the BoundingBox for the best
effect, and it may help to look at the \idx{PostScript} file to see what the 
default BoundingBox is and adjust things using that coordinate system.

\bigskip

You can also control the size of the included graphic using
\CS{epsfxsize} or \CS{epsfysize} before you call \CS{epsfbox}. The
figure will be enlarged or reduced to fit the dimension you specify.
Saying 
\example
\CS{epsfxsize}|=|\meta{dimen} \CS{epsfbox}|{figure.ps}|
\endexample
will scale the drawing in the file |figure.ps| so that its {\sl width\/}
is \meta{dimen}, with the height scaled accordingly, while saying
\example
\CS{epsfysize}|=|\meta{dimen} \CS{epsfbox}|{graph.ps}|
\endexample
will scale the drawing in the file |graph.ps| so that its {\sl height\/} is
\meta{dimen}, with the width scaled accordingly.  You can only specify
the width or height, but not both at the same time.  Whatever change of
size you specify will only be applied to the \CS{epsfbox} command which
immediately follows.  After that, subsequent included graphics will
revert to their natural sizes unless you also specify a particular size
for them.

The \CS{epsfbox} command creates a box of the proper size, into which
the figure is later drawn.
That is all.
If you want the figure to be centered across the page then you will
have to do so yourself, using \cs{centerline} or something similar.
The advantage of this is that since figures are simply treated as
boxes, you can stack them or arrange them in a row, or do whatever
else you would with boxes.
This gives you much more flexibility to construct complicated figures
from several EPS files.

\figure{Penguin2}
\centerline{\epsfysize=4cm\epsfbox{penguin.eps}}
\Caption
Example of including EPS graphics in a figure.
\endCaption
\endfigure

So now consider the earlier example of including a 4~cm tall 
\idx{penguin} diagram in a figure, but now assuming that the drawing
exists as an EPS graphic in the file |penguin.eps|.
Assume also that we need to override the default bounding box in that
file.
The commands to do this are:
\TeXexample
\figure{Penguin2}
\centerline{\epsfysize=4cm \epsfbox{penguin.eps}}
\Caption
Example of including EPS graphics in a figure.
\endCaption
\endfigure
|endTeXexample
\relax
The results are shown in \Fig{Penguin2}.
The drawing was created with Bill Dimm's {\sl FeynDiagram}
package,\reference{FeynDiagram}
Dimm, Bill,
\booktitle{FeynDiagram Tutorial},
available at \URL{ftp://ftp.hepth.cornell.edu}
\endreference
which is a set of C++ objects which make it fairly easy to create EPS
\idx{Feynman Diagrams} by writing short C++ programs. It was converted
from a |.ps| to a |.eps| file using |ps2epsi|.

%==================================================*
\subsection{Simple Tables               \label{sect.tbls}}

 Simple tables\index{tables!simple} (without ruled lines) are constructed
in \TeX\  with \idx{alignment tabs} or with \cs{halign}.  The reader who
is not familiar with these should look at Chapter~22 in \TeXbook.  In
\TeXsis\  simple tables with table numbers and captions are
treated much the same as figures.  For example, saying
\TeXexample
|smalltt\midtable{table example}
\caption{Charged leptons.}
\centerline{\vbox{\halign{#\  \hfil & #\  \hfil & #\hfil \cr
Name     & Mass     & Lifetime \cr
$e^-$    & .511 MeV & $>2 \times 10^{22}$ yr. \cr
$\mu^-$  & 105 MeV  & $2.197 \times 10^{-6}$ sec. \cr
$\tau^-$ & 1784 MeV & $3.3 \times 10^{-13}$ sec. \cr}}}
\endtable
|endTeXexample
\noindent
produces the following table, in the middle of the page:
\vskip 0pt
\midtable{table example}
\caption{Charged leptons.}
\centerline{\vbox{\halign{#\  \hfil & #\  \hfil & #\hfil \cr
Name     & Mass     & Lifetime \cr
$e^-$    & .511 MeV & $>2 \times 10^{22}$ yr. \cr
$\mu^-$  & 105 MeV  & $2.197 \times 10^{-6}$ sec. \cr
$\tau^-$ & 1784 MeV & $3.3 \times 10^{-13}$ sec. \cr}}}
\intablelist{Charged leptons.}
\endtable
\noindent
Note the use of \cs{centerline} and a \cs{vbox} to center the table. The
reference to this table in the text was produced by typing ``|\Tbl{table
example}|.''  Note also that we used \cs{caption} followed by the text in
brackets as an alternative method of defining the caption; 
However \cs{caption}
should only be used when the caption is short.  Table captions are
traditionally placed above the table, so \cs{Caption} or \cs{caption} should
be the first token after \CS{table}\arg{label\/} and its siblings.

There are a number of different kinds of table insertions, and they
match closely the different kinds of insertions used for figures:
\description{xwidefullTablexx\qquad}\clump
%
\itm{\CS{table}\arg{label\/}}
Inserts a table at the top of next available page.
%
\itm{\CS{midtable}\arg{label\/}}
Inserts a table at the current position if there is room or at
the top of a page if necessary.
%
\itm{\CS{fulltable}\arg{label\/}}
Inserts a table on a separate page. The body of the table
should normally contain a \cs{vfill}.
%
\itm{\CS{bottomtable}\arg{label\/}}
Inserts the table at the bottom of the current page, if there is room
for it, or on the bottom of the next page where there is room.
%
\itm{\CS{heavytable}\arg{label\/}}
Inserts a table at the current position, if there is room for it on the
page, or at the bottom of the page following if there is not.  This is
therefore like \CS{midtable}, except that if the table can't be fit on
the page it ends up on the bottom of a following page, not the top.
%
\itm{\cs{widetoptable}\arg{label\/}}
Inserts a table at the top of a page across both columns in
double column format. Equivalent to \CS{table} in single column
format.
%
\itm{\cs{widefulltable}\arg{label\/}}
Inserts a full page table in double column format. Equivalent to
\CS{fulltable} in single column format.
%
\itm{\CS{endtable}}
Ends any of the tables above.
%
\enddescription
Again, in these macros \meta{label\/} is an internal label which is assigned to
the table number.  The table number will include the chapter and section
numbers in the format ``$cc.ss.nn$'' if |\showchaptIDtrue| and
|\showsectIDtrue| have been selected.  The table can then be referred to
in the text by saying \cs{Tbl}\arg{label\/}.

%==================================================*
% RULED TABLES:

\subsection{Ruled Tables                \label{sect.ruled}}
\input TXSruled.doc

%==================================================*
\subsection{Lists of Figures and Tables}

In large technical documents it is often desirable to have a list of the
figures and/or tables which appear in the document, along with a brief
caption and the number of the page on which the figure or table appears.
This is similar to
a table of contents, but is separate from it.  In \TeXsis\  you can add a
figure or table to a list of figures or tables by using \CS{infiglist}
after \cs{figure} or \CS{intablelist} after \cs{table}, similar to the
way you would use \cs{caption}.  The syntax is \CS{infiglist}\arg{text}.
The text is the text of the (possibly abbreviated) caption which is to
appear in the list of figures.  Remember though, if a table has a
caption it should 
appear above the table body, so the \cs{caption} must still be the first
thing after \cs{table};  the \CS{infiglist} can come later.  
\index{lists!of figures}\index{lists!of tables}%

As an example, consider the ``penguin diagram'' already discussed.
To add an entry for this figure in the list of figures it 
would be entered as follows:
\TeXexample
\figure{Penguin}
\centerline{\epsfbox{/home/fermi/qcd/penguin.eps}}
\caption{Example of including EPS graphics in a figure.}
\infiglist{Example of including a figure in the list of figures.}
\endfigure
|endTeXexample
\relax
The \cs{caption} text is what is put under the figure in the body of the
paper, while the \CS{infiglist} text is what shows up in the list of
figures, and these do not have to be the same.

   To produce the list of figures at the end of the document you say
\CS{ListFigures}, and similarly to produce the list of tables say
\CS{ListTables}.  Even if the list is to appear at the front of the
document, along with the table of contents, you should print it at the
end and move the list to the front afterwards.  This is because until
the document is actually processed \TeX\  does not know on which page the
figure or table appears.

   One word of caution: figures and tables are produced by putting them
in ``floating inserts'', which \TeX\  saves up and prints when there is
room.  The entry into the list of figures or tables is not made until
the item actually makes its way into the output DVI file.  If you ask
for the list of figures or tables before one of these items is output it
will not be in the list, and in fact that entry for the figure or table
list will later end up spewing out on your terminal.  To be sure that
all floating insertions have been output you should say \cs{supereject}
before you print the list of figures or tables.

%==================================================*
\subsection{Listing Figure and Table Captions}

When a manuscript is submitted to some journals, like the Physical
Review, one is supposed to include a separate list of the captions of all
figures and tables.  This is similar to the lists created by
\CS{ListFigures} and \CS{ListTables}, but the page numbers are not
supposed to be included.  It is very easy to use the caption information
stored by \CS{infiglist} and \CS{intablelist} to make just a list of
captions, without including the page numbers.  The command to make a
list of all the figure captions is \CS{ListFigureCaptions}, and
similarly all the table captions can be listed with
\CS{ListTableCaptions}.  Just as with \CS{ListFigures} and
\CS{ListTables} these should appear at the end of the job, so that all
of the caption information will have already been stored.

It should be said that this method of making a list of captions assumes
that you have put the same captions under the figures, with \cs{Caption}
or \cs{caption}, as the caption in the list of figures entered with
\CS{infiglist}.

   It may help to know a little bit more about how the macros
\CS{ListFigures} and \CS{ListFigureCaptions} work.  The \CS{infiglist}
command writes the figure caption information you provide to a file
which has the same name as your manuscript file but with the extension
|.fgl|, meaning ``figure list'' (for tables the file name extension is
|.tbl|).  The page number on which the figure appears is also recorded
in this file.  When the whole document has been processed all of the
figure captions will have been saved in this file, and \CS{ListFigures}
and \CS{ListFigureCaptions} simply read this file back in.  One of them
uses the page numbers to construct a table of contents for the figures,
while the other just prints out the figure captions by themselves.  In
either case, it is important that all the caption information be in the
file when the list is to be made, which is why a \cs{supereject} may be
necessary to flush all floating insertions to the output.

%==================================================*
\subsection{Printing Figures and Tables at the End of a Document}

When working on a paper to be sent for publication it is sometimes
necessary to print all of the figures at the end of the document.  To cause
this to be done you simply have to say
\example
\cs{FiguresLast}
\endexample
at some point before you call \cs{figure} and its relatives, and then put
\example
\cs{PrintFigures}
\endexample 
\index{figures!at end of document}%
\index{tables!at end of document}%
\noindent
at the end of the document.  \cs{FiguresLast} causes \cs{figure} to save the
definition of your figure in an auxiliary file instead of immediately
creating the figure, and \cs{PrintFigures} reads the material back in from
that file.  If you say \cs{PrintFigures} without first saying
\cs{FiguresLast} nothing will happen.  You can return to having the
figures printed where they are defined by saying \cs{FiguresNow}.
In that case \cs{PrintFigures} does nothing; you have to have said
\cs{FiguresLast} for \cs{PrintFigures} to read any stored figures back in.

Tables can also be saved until the end of the document by saying
\cs{TablesLast} and then \cs{PrintTables}.  \cs{TablesNow} is the
opposite of \cs{TablesLast}.   

\pagecheck{4cm}

One important note: Since the figure or table material is copied to the
file in which it is held one line at a time it is important to use
\cs{Caption} and \CS{endCaption} for long captions instead of \cs{caption}.
If you use \cs{caption} \TeX\  will try to read the whole caption at once,
which may result in the error message 
``{\tt TeX capacity exceeded, sorry.}''\index{TeX capacity
exceeded@{\tt TeX capacity exceeded, sorry}} 


%==================================================*
\subsection{Nonstandard Figure and Table Placement}

On rare occasions you may need to have a figure or table from one
section of your document appear in another section of the document.  For 
example, if the introductory section is very short but has a figure,
that figure might end up at the top of the first page when you really
want it to appear at the top of the second page.  You can cause the
figure to come out later by moving it farther back in the manuscript
file, but if it is moved into the next section it will then have the
wrong figure number.
\index{figures!nonstandard placement}%
\index{tables!nonstandard placement}%

The solution to this problem is to have a way to override or modify the
way figure and table numbers are assigned.  Since the first part of the
figure or table number is the chapter or section number you need to change
this by saying
\example
\cs{setSectionID}\arg{something-else} 
\endexample
This changes the section number part of the figure and table numbers to
whatever you put as \meta{something-else}.  It will also effect equation
numbers, so it is best to have this inside of a group, so that the
change goes away at the end of the group.  Next you have to change the
figure or table number.  \TeXsis\  keeps count of tables and figures in
global variables, and increments these counters globally when a new
figure or table is created.  Thus just changing the counter inside a
group won't work, because the counter outside of the group would still
be modified.  To temporarily change the value of such a counter you use
\example
\cs{setcnt}\arg{counter}\arg{value}
\endexample
where \meta{value} is the temporary value to assign to the counter
\meta{counter}.  This should be done inside of a group, and when the
group ends the counter will go back to its previous global value.  You
should only use \cs{setcnt} once within a given group!

An example will make this procedure clear.
Suppose that Figure~\use{Fg.intro.17} is a part of
Section~\use{sect.intro}, but we wanted to show it much later in this
Manual (such as right about now).
It can be created in this section by saying:
\TeXexample
\begingroup       % changes are temporary
\setSectionID{1}  % changes the section ID
\setcnt\fignum{16}% figure counter is 1 less than we want
\midfigure{intro.17}               
\centerline{\epsfysize=4cm\epsfbox{|penguin.eps}}
\caption{A bizarrely placed figure for Section~\use{sect.intro}}
\infiglist{A bizarrely placed figure for Section~\use{sect.intro}}
\endfigure
\endgroup         % everything goes back the way it was
|endTeXexample

\begingroup                     % changes are temporary
\setSectionID{1}                % changes the section ID
\setcnt\fignum{16}              % figure number is 1 less than we want
\midfigure{intro.17}
\centerline{\epsfysize=4cm\epsfbox{\penguin.eps}}
\caption{A bizarrely placed figure for Section~\use{sect.intro}}
\infiglist{A bizarrely placed figure for Section~\use{sect.intro}}
\endfigure
\endgroup                       % everything goes back the way it was

In this case the figure number in the counter \cs{fignum} is set to one
less than the value we want, so that it comes out correctly when
\cs{bottomfigure} increments the count.  You can use \cs{setcnt} to
modify any of \TeXsis's global counters.  The complete list is given in
Section~\use{sect.labels} (where the use of \cs{use} is also described).

% If we are using Larry Ewing's penguin2.eps then we need to
% acknowlege it:

\def\tmp{penguin2}
\ifx\penguin\tmp
   The drawing in \Fig{intro.17}, which is the official \idx{Linux}
   Penguin, was created by \idx{Larry Ewing} of Texas A\&M University
   and turned into a scalable vector based postcript file by \idx{Neal
   Tucker}.
\fi


By the way, you should never move a figure out of a {\sl Chapter},
unless you move it to the end of the document, and the appropriate way
to do that is with \cs{FiguresLast}.

%>>> EOF TXSfigs.doc <<<