% malcolm,
% please note that the placement of most figures has to be
% optimized manually! furthermore, the standard \vsize is
% assumed for one or two figures. 
% good luck!
%

\input texline
\pageno6
\input flow.def
\begingroup
\let\Alisttt\tt
\let\Alistrm\rm
\def\uncatcodespecials{\def\do##1{\catcode`##1=12 }\dospecials}
\def\listing#1{\par\begingroup\setupverbatim\input#1 \endgroup}
\def\setupverbatim{
  \Alisttt\lineskip=1truept
  \lineskiplimit=1truept\topskip=0pt
  \def\par{\leavevmode\egroup\box0\endgraf}
  \obeylines \uncatcodespecials \obeyspaces
  \catcode`\`=\active \catcode`\^^I=\active
  \everypar{\startbox}}
\newdimen\w \setbox0=\hbox{\Alisttt\space} \w=8\wd0
\def\startbox{\setbox0=\hbox\bgroup}
{\catcode`\^^I=\active
  \gdef^^I{\leavevmode\egroup
    \dimen0=\wd0
    \divide\dimen0 by\w
    \multiply\dimen0 by\w
    \advance\dimen0 by\w
    \wd0=\dimen0 \box0 \startbox}}
{\obeyspaces\global\let =\ }
{\catcode`\`=\active \gdef`{\relax\lq}}

\begindoublecolumns


\fontdimen16\tensy=2.7pt
\fontdimen17\tensy=2.7pt
\fontdimen3\tenbf=4pt
\fontdimen3\tenrm=4pt

\parskip0pt



\hyphenation{Theo-re-ti-sche end-insert flow-chart flow-left-con-nect}
\hyphenation{flow-right-con-nect}

\tracingstats=2


{\vfuzz10pt
\title{\bf Flow charts with \TeX}
\section{Introduction and connection to plain \TeX}
The purpose of this contribution is to describe usage and
limitations of the macro |\flowchart| and a set of secondary
macros, which allow an easy generation of flow charts (of limited
complexity) within \TeX. The macros themselves will be described
in detail elsewhere; they are available from the Aston \TeX\ server
or directly from the author. 

The macros are designed to work in the plain
\TeX\ environment. No additional font tables are required;
instead, the printer driver, which converts the \dvi\ file into the
actual print file, {\it must\/} be able to handle rules correctly.

The command |\flowchart| generates a |vbox|. Although the typical use of this
|vbox| will be in combination with |\topinsert| and |\endinsert|,
it may be used in any other box operation. The macros are quite
economical:  |\flowchart| requires 4393 words of \TeX's memory for
macro definition; most of this memory can be released by the command
|\nomoreflowcharts|. 

The secondary macros mentioned before are intended to be used as
commands inside the argument of |\flowchart|. In most cases an
outside use will cause \TeX\ to interrupt and complain about some
undefined control sequence. If, by chance, all those control
sequences are also defined outside of |\flowchart|, an {\it
outside\/} use of the flow chart commands will cause severe
problemss by changing registers, dimensions, and boxes. By
exploiting  the grouping effect of boxes in \TeX, the outside
definitions of all control sequences will be restored upon
completion of |\flowchart|. Some additional macros are used by the
secondary macros; with the exception of |\nomoreflowcharts|, the
names of all of these macros are prefixed with `{\tt
flow}'.\looseness1 

\section{Start and stop}
The commands |\flowstart| and |\flowend| are available for use
within the argument of |\flowchart| to mark the begin and the end.
In detail, |\flowchart{\flowstart}| yields 
$$\flowchart{\flowstart}$$
and |\flowchart{\flowend}| gives
$$\hphantom.\kern1cm
\hbox to0cm{\hss\flowchart{\flowend}\hss}\kern1cm.$$

Basically |\flowchart| arranges the individual entries  vertically
and centered without an |\interlineskip| to form a linear stream
of operations; thus |\flowchart{\flowstart\flowend}| produces 
$$\hphantom.\kern1cm
\hbox to0cm{\hss\flowchart{\flowstart\flowend}\hss}\kern1cm.$$

The related commands  |\flowstartcircle| and |\flowendcircle|,
produce circles instead of triangles to mark points of
continuation. Both  require one argument, which
is placed in the centre of the circle. Since one token (digit
or letter) is sufficient to distinguish different points of
continuation, the size of the circle is independent of the length
of the argument. Continuing the previous examples,
|\flowchart{\flowstartcircle1}| and 
|\flowchart{\flowendcircle{\it The End}}| result in 
$$\hphantom.\kern1cm
\hbox to0cm{\hss\flowchart{\flowstartcircle1}\hss}
\hbox to3cm{\hfill and\hfill}
\hbox to0cm{\hss\flowchart{\flowendcircle{\it The End}}\hss}\kern1cm
\hbox{.}$$\looseness-1

\section{Basic operations}
Three commands are available to insert symbols for basic
operations: |\flowcompute|, |\flowinput|, and |\flowoutput|. Each
command requires one argument, which must consist of
`horizontal material'. The argument will be placed in a |hbox|,
or, if the width of this |hbox| would exceed |0.4\hsize|, it will
be typeset by \TeX\ as a paragraph with a maximum width of
|0.4\hsize|. This |hbox| (or paragraph) will be  surrounded by a
properly shaped symbol and placed as the next item in the flow
chart. To make the text inside the flow chart symbols look nice, it is
processed with stretchable |\leftskip| and |\rightskip| and zero
|\parfillskip|. (If this produces unwanted effects, alternate values
for the named parameters may be specified as part of the
argument.) An example is shown in %\nextabb, 
Figure~1, demonstrating that the symbols grow with the amount of text
given.\looseness-1

\section{Decisions}
%
Decisions are certainly the most important elements of flow
charts; within the argument of |\flowchart|, decisions are
generated with the command |\flowdecide| which requires
four arguments illustrated by the example 
|\flowchart{\flowdecide{A}{B}{C}{D}}|: \hskip0pt plus1em\relax
which produces the display
$$\hphantom.\kern1in\hbox to0cm{%
\hss\flowchart{\flowdecide{A}{B}{C}{D}}\hss}\kern1in.$$
}
\enddoublecolumns
\eject
\begindoublecolumns



{
\input flow.fg1
\medskip\noindent
Figure 1: The flow chart of the solution of the quadratic equation
$ax^2+bx+c=0$ was generated via 
\smallskip\begingroup\parindent0pt
\listing{flow.fg1} 
\endgroup
\medskip
\hrule}

\medskip

\noindent The first two arguments must be non-empty 
in order to generate the horizontal strokes:
|\flowchart{\flowdecide{}{B}{C}{D}}| 
yields
$$\flowchart{\flowdecide{}{B}{C}{D}}$$
\medskip\noindent
and |\flowchart{\flowdecide{~}{}{}{D}}| 
gives
$$\hphantom.\kern2cm\hbox to0cm{%
\hss\flowchart{\flowdecide{~}{}{}{D}}\hss}\kern2cm.$$

\fontdimen4\tentt=3pt
The rhombic shape generated by |\flowdecide| grows with the amount
of text passed as the fourth argument, and the text will be
typeset as a properly shaped paragraph as shown below. The rhombic
shape, however, cannot exceed a maximum horizontal size of 
|0.33\hsize|${}+{}$|1truecm|; 
the text therefore has to be cautiously limited 
to fit into the decision symbol.
\vadjust{$$\centerline{\hsize=2.75\hsize \flowchart{
\flowdecide{}{}{}{\dots\ 
and the text will be typeset as a properly shaped paragraph.}}}$$}%
(This is especially important for small values of |\hsize|
like the one used in this double column style. The above display
was generated with an enlarged |\hsize| value using the
input\hfil\break 
|$$\centerline{\hsize=2.75\hsize|\hfil\break
|\flowchart{\flowdecide{}{}{}{...}}}$$|.)

The decision branches the flow chart in a maximum of three parts,
which will be named `left', `middle', and `right' in the
following. 
$$\flowchart{\flowdecide~~~~
\flowcompute{middle}\flowendmiddlepart
\flowleftpart
\flowcompute{left}\flowendleftpart
\flowrightpart
\flowcompute{right}\flowendrightpart}$$

All items following |\flowdecide| will be placed below the
decision symbol to form the middle part until the command
|\flowendmiddlepart| is encountered. After this, the commands
|\flowleftpart|, |\flowendleftpart|, |\flowrightpart|, and
|\flowendrightpart| are available to commence and terminate the
left and the right part after the decision. Left and right part
may be specified in arbitrary sequence, except in case of
connections between these parts (see next section). 
 
If the arguments to the basic operations in the various parts are
not restricted to such short words as in the display above, the
left or right part will interfere with a middle part, since the
horizontal strokes of the decision symbol will extend |0.25\hsize|
left and right from the current stream of operations. Therefore
the use of either a left and a right part without a middle part is
recommended, or the use of a middle part in combination with
backward or forward jumps in the side parts. 

\enddoublecolumns
\eject
\begindoublecolumns

Left and right parts may be recombined by using the command
|\flowcombine| after |\flowleftpart| and |\flowrightpart|, as
shown in Figure 2.


\bigskip\hrule\medskip
\input flow.fg1
\medskip
{\catcode`\|=12 
\input flow.fg2
\medskip\noindent
Figure 2: This flow chart was generated by the input
\smallskip\begingroup\parindent0pt
\listing{flow.fg2}
\endgroup
\bigskip
\hrule}

\medskip

Additional |\flowdecide| commands may follow in any of the parts;
in such cases the commands |\flowdecide| and |\flowendmiddlepart|,
as well as |\flowleftpart| and |\flowendleftpart| (and
|\flowrightpart| and |\flowendrightpart|) act as opening and
closing operations (like brackets in mathematical equations).
Figures~3--5 make use of this feature. 


\section{Jumps}
The jump definitions are the most tricky part of |\flowchart|,
designed to make things as simple as possible for the user. Jumps
are defined with the command |\flowmark| and one of the commands
|\flowleftconnect|, |\flowrightconnect|, and |\flowconnect|. Each
of these commands requires one of the ten digits as its argument. 

The command |\flowmark|$n$ adds a vertical stroke to the last flow
chart entry and marks its end as position~$n$ ($0\le n\le9$).
Positions may be marked in any order, as long as they are defined
before they are used. 

The command |\flowrightconnect|$n$ or
|\flowleftconnect|\kern0pt$n$ is used {\rm after\/} one of the
{\it basic operations\/} to produce an arrow pointing to position
$n$. As indicated by the command name, the arrow will be drawn to
the left or to the right of the current main stream. For example, 
the input 
|\flowchart{\flowstart \flowmark1 \flowcompute~
\flowrightconnect1}| 
will produce

\centerline{$\hphantom.$\kern3cm\hbox to0cm{\hss
\flowchart{\flowstart \flowmark1 \flowcompute~
\flowrightconnect1}\hss}\kern3cm.}
\vskip\belowdisplayskip
The command |\flowconnect| is to be used in the left or the right
part after a {\it decision\/} only. If given, it must be the only
command in this specific part. |\flowconnect|$n$ will also result
in an arrow pointing to position $n$. Although the use of
|\flowconnect| appears to be rather simple, the definition of flow
charts with several decisions and jumps may require some planning.
Figure~3 gives a simple example, Figures~4 and~5 show more complicated
flow charts. 

Figure~5 also shows that repetitive |\flowmark| commands
can be used to elongate vertical strokes. This may help to avoid
overlapping entries in those cases in which a combination of a
middle part and a left or right part after a decision cannot be
avoided.\looseness-1 

\section{Size adjustment}
In some cases it will be necessary to change the {\it
horizontal\/} size of the charts generated by |\flowchart|,
because the macros work expecting a certain maximum width:
this maximum width is reached by a decision followed by a left and
a right part, both of which contain additional decisions.
Figure~5 presents an example of the assumed maximum width.\looseness-1 

Flow charts without left or right parts (or with only jumps as
left or right part) will therefore be limited to |0.5\hsize| and
may benefit from an enlarged |\hsize| value (demonstrated in
Figure~3). The opposite is true where the left
(or right) part after a decision which itself is placed in the
left (or right) part after a previous decision contains 
operations other than a jump: these will require careful reduction of
|\hsize| and proper |\kern|ing ({\it cf.{}}
Figure~5).\looseness-1 


{\vfill\hrule\medskip
\input flow.fg1
}
\goodbreak
{\input flow.fg3 
\noindent
Figure~3: This flow chart was generated by the following input, in
which the matching commands |\flowdecide| and |\flowendmiddlepart|
are connected by percent signs.
\smallskip
\parindent0pt
\listing{flow.fg3}
\medskip\hrule}

\eject



{\input flow.fg4
\goodbreak
\parindent0pt\frenchspacing 
Figure~4: This flow chart was generated by the input 
\smallskip\listing{flow.fg4}
\bigskip\hrule}%

\bigskip
Such changes of |\hsize| have to be made outside of |\flowchart|,
since a number of internal dimensions are derived from |\hsize|
before the argument of |\flowchart| is processed. The best way
certainly is to make use of \TeX's rules and limit the range of
the altered |\hsize|  value to a surrounding group. 
The following plain \TeX\ commands, which are of interest in
combination with |\flowchart|, do this automatically: 
|\centerline|, |\topinsert|\dots\hskip0pt|\endinsert|,
|\midinsert|\dots\hskip0pt|\endinsert|, 
and |\pageinsert|\dots\hskip0pt|\endinsert|.

The {\it vertical\/} dimension of the |\flowchart| output is
adjusted automatically using the following procedure. At first,
|5truemm| are used for two distances: the white space between the
text in the basic operation boxes and the surrounding box symbols,
and the distance between individual flow chart entries. If the
height of the |vbox| generated this way exceeds |\vsize|, the
chart is re-generated using distances of |4truemm| and eventually
once more with |3truemm|. 
(Figure~4 exhibits an example of such a reduced size: the initial
interentry distance of |5truemm| gave a box height of |676.3pt|;
reduction to |4truemm| diminished the box height to |577.7pt|,
which is the size actually used in Figure~4.)

\eject



{\input flow.fg5
\bigskip
\noindent
Figure~5: This flow chart shows a sequence of decisions used in a
special variant of quantum chemical MO calculations. If processed
normally, this chart would extend too far to the left. The input used
to generate the chart, which is reproduced below, takes care of this by
a |\kern|ing, which compensates the left half of the `cleanup'-box
(with a maximum width of |0.2\hsize|), and the subsequent definition of
a new |\hsize| value. This new value was calculated from the width of
the `skip'-box (which, including both strokes, is |0.5\hsize|),
the width of the left half of the `last atom'-box (which,
including the stroke, is |0.25\hsize|), the width of the left and
the right half of the `cleanup'- and the `restore'-box (which
both have a maximum value of |0.2\hsize|). This gives a maximum
total width of |1.15\hsize|, hence |\hsize| was scaled by 
$1 / 1.15 = 0.86956\ldots\,.$}
\goodbreak


{\parindent0pt\frenchspacing
\listing{flow.fg5} 
\medskip\hrule}

\section{Acknowledgement}
The author is grateful to the students Michaela Flock and Ulrike
Seebacher for testing the macro package in the course of writing
up their diploma works.
\author{Michael Ramek} 

\enddoublecolumns
\endgroup
\endinput


\bigskip

\smallskip
Institut f\"ur Physikalische und Theoretische Chemie,
Technische Universit\"at Graz, \hbox{A--8010} Graz, Austria}


\endinput
\def\kap#1 {\advance\kapno1\goodbreak%
\vskip 3\bigskipamount\vbox{\bf \setbox0\hbox{\the\kapno. }%
\parindent\wd0\item{\the\kapno.}#1\bigskip}\nobreak\noindent}

\newcount\abbno\abbno0
\def\abb{\global\advance\abbno1\noindent Fig.~\the\abbno\thinspace: }
\def\thisabb{Fig.~\the\abbno}
\def\nextabb{{\advance\abbno1Fig.~\the\abbno}}
\def\nextnextabb{{\advance\abbno2Fig.~\the\abbno}}
\def\nextnextnextabb{{\advance\abbno3Fig.~\the\abbno}}
\def\nextthreeabb{{\advance\abbno1Figs.~\the\abbno%
                   \advance\abbno2--\the\abbno}}
\def\nexttwoabb{{\advance\abbno1Figs.~\the\abbno\advance\abbno1\ %
                  and \the\abbno}}