%% mpicp-posfigs.tex
%% mathsPIC manual

\documentclass[mathsPICmanual.tex]{subfiles}
\begin{document}
%%=============================


%%-------------------------------------------
\chapter{Positioning the figures}
\label{chap:posfig}



%%============================================================
\section{Generating PS, EPS, PDF, JPEG files.}
\label{sec:epsandjpg}


Once a diagram or figure has been finished it can be easily
placed in a document using  either an EPS (DVI document) or PDF (\LaTeX\ document). 
Being able to generate a  JPEG version is also useful since, unlike EPS or PDF files,  this can be readily manipulated and converted to other image formats using the GIMP.\footnote{Peck A (2008). \textit{Beginning GIMP}. 2nd ed. (Apress); \url{http://www.apress.com/}.}



%-------------------------
\subsection*{PS, EPS, PDF}

If only a PDF version is required, then this is easily done via \textsc{pdf}\LaTeX. For example, if the \mathsPIC\ file is, say, \verb!picture.m!, then the commands would be as follows:


\begin{verbatim}
mathspic picture.m
pdflatex  picture.mt
\end{verbatim}

However, the process of trimming excess white space can be most conveniently done via \texttt{dvips}.
The process of editing and viewing can be conveniently automated using a BASH script, such as the following, which  runs \mathsPIC, trims the image to the bounding box (BBox) and generates  the associated  PS, EPS and PDF files.
\begin{verbatim}
## makefigs.sh
## use:  bash makefigs.sh  filename [no filename extension]
mathspic $1.m
latex  $1.mt
dvips $1.dvi -o $1.ps
dvips -E $1.dvi -o $1.eps  ## determines the BBox -->eps
epstopdf $1.eps
echo  ... end of run
\end{verbatim}
For example, to process the \mathsPIC\  file \texttt{myfile.m}, one would type the command
\begin{verbatim}
$ bash makefigs.sh  myfile
\end{verbatim}
remembering  \textit{not} to include the filename extension  here (since the script needs to  append different filename extensions for the different processes).


%-------------------
\subsection*{JPEG}


In order to make a JPEG file  we make use of (a)~the Perl program \texttt{fitps12.pl}  (originally made by S.\ Rahtz (1996) and modified slightly\footnote{The original version required that there was exactly one space between each of the BBox values. This was a problem, since if you manually adjusted the BBox values, then the spacing could easily end up being  slightly different, and the program would then fail. The new version is more flexible, and tolerates  any number of spaces.} by Apostolos Syropoulos (2006) as version~1.2), and then (b)~GhostScript, as follows:
\begin{verbatim}
## makefigs.sh
## use:  bash makefigs.sh  filename [no filename extension]
mathspic $1.m
latex  $1.mt
dvips $1.dvi -o $1.ps
dvips -E $1.dvi -o $1.eps        ## determines the BBox -->eps
perl fitps12.pl  $1.eps  $1.EPS  ## outputs a modified EPS file
gs -sDEVICE=jpeg -r400 -sOutputFile=$1.jpg  $1.EPS
echo  ... end of run
\end{verbatim}
Note that in the above example, the GhostScript command (\texttt{gs}) inputs the modified EPS file, and generates a JPEG file with resolution 400~dpi. See the GS help file for details (type \texttt{gs --help}). Resolutions 300 or 400 are generally fine for most purposes.
See the Ghostscript man page and also 
\begin{verbatim}
/usr/share/doc/HOWTO/HTML/en/Printing/ghostscript.html
\end{verbatim}




%------------------
\section{Using the \texttt{figure} environment}



A \mathsPIC\ diagram or figure can  also be 
placed in a document  by including the {\PiCTeX} code
directly in the main document within the  \verb!\begin{figure}...\end{figure}!
environment, or by \verb!\input!ting the code as a separate
file.
Note, also, the various extension packages  available for facilitating the placement of pictures and images (e.g.,~the \textit{subfigure} package).

For example, if the {\mathsPIC} file was called \verb!mypic.m!
and this generated the output-file \verb!mypic.mt!, then one would
comment-out the \LaTeX\ headers and footers from the \verb!.mt!
file, keeping just the part of the file within the
\verb!\beginpicture!\ldots\verb!\endpicture! environment (renaming
it, say, \verb!mypic.pic!) as follows.


\begin{verbatim}
%% this is file mypic.pic
\beginpicture
...
...
\endpicture
\end{verbatim}

The  \verb!mypic.pic! file can then be \verb!\input! into
a document as a centered Figure as follows.
Always use the \verb!\centering! command as this avoids the additional vertical space added by the \verb!\begin{center}...\end{center}! environment.


\begin{verbatim}
\begin{figure}[hbt]
\centering
   \strut\input{mypic.pic}
   \caption{...}
   \label{...}
\end{figure}
\end{verbatim}



It is often useful when adjusting
the position of a Figure on the page
to initially place the Figure  inside a frame
in order to see the exact extent of the Figure. To do this just replace the
\verb!\input! line above with the following:


\begin{verbatim}
\strut\framebox{\input{mypic.pic}}
\end{verbatim}


Sometimes more flexibility is needed regarding positioning
the \verb!\caption!, in which case  a \verb!\parbox! or a \verb!minipage! is useful, as follows:

\begin{verbatim}
\begin{figure}[hbt]
\centering
   \strut\input{mypic.pic}
   \begin{minipage}{8cm}
      \caption{\label{}......}
   \end{minipage}
\end{figure}
\end{verbatim}

Note that the general convention is that Tables have the caption at the top while
Figures have the caption underneath the Figure.

Getting the vertical position  and horizontal width of the caption just right can be awkward. However, using a minipage gives a lot more flexibility as in the following example, which defines the \verb!\captionwidth! in terms of the \verb!\textwidth!.
Note also that here the \verb!\caption{}! is empty---it is here just to trigger the Figure counter---we place the actual caption in the minipage.

%-----------------

\begin{Verbatim}
\newcommand{\captionwidth}{0.8\textwidth}
%%
\begin{figure}[hbt]
\centering
   %\framebox{
   \strut \input{mypic.pic}
    %}
            [empty line]
   \vspace\baselineskip
   \begin{minipage}{\captionwidth}
      \caption{\label{fig:fcubic}}%
      {blah blah...}
    \end{minipage}
\end{figure}
\end{Verbatim}
%------------------------------


When typesetting text and a figure side-by-side the following
format for using two adjacent minipages works quite well.

\begin{verbatim}
\begin{figure}[hbt]
\noindent
\begin{minipage}{4cm}
%% put some text or a figure here
...
...
\end{minipage}
%%-----------
\hspace{3cm}   %% controls the horizontal space between Figures
%%-----------
\begin{minipage}{4cm}
  \vspace{3mm}
  \strut\hspace*{...}\input{circle.pic}
  \vspace{...}  % adjusts vertical position of caption
  \caption{\label{}...}
\end{minipage}
%-----
\hfill
\end{figure}
\end{verbatim}


Finally, it is often necessary to have two figures side-by-side,
each with separate sub-captions, in which case the following
rather similar format is useful---this was the
construction used  for displaying the two figures of Figure~8.
Note the commented-out \verb!\framebox{}! commands; these are
very useful for revealing the full extent of any white-space
surrounding the separate figures, since such unwanted white-space is
probably the most common cause of difficulty when trying to
position and center figures in a document.
Note that while the \verb!\centering! command can be used inside a Figure, the \verb!\begin{center}...\end{center}! environment has to be used within a minipage.


\begin{verbatim}
\begin{figure}[hbt]
\centering
    %-------
    \noindent %\framebox{
    \begin{minipage}{3cm}
       \begin{center}
       %\vspace{...}  %% controls space above picture
       \input{mpicm08a.pic}
       %\vspace{...}  %% controls space between picture and caption
       a. Circular arrows
       \end{center}
    \end{minipage}
    %} %end of framebox
    %-----------------------
    \hspace{12mm} %% controls horiz space between figs
    % \bigskip\bigskip  %% use this to adjust vertical space
    %----------------------
    %\framebox{
    \begin{minipage}{5cm}
       \begin{center}
       %\vspace{...}  %% controls space between picture and caption
       \input{mpicm08b.pic}
       %\vspace{...}  %% controls space between pict and caption
       b. Straight arrows
       \end{center}
    \end{minipage}
    %} %end of framebox
    %---------
    \caption{\label{}....}
\end{figure}
\end{verbatim}



%------------------
\section[Using the PiCTeX code]{Using the \PiCTeX\ code}
\label{sec:pictexfigs}

A \mathsPIC\ diagram or figure can  also be 
placed in a document  by including the {\PiCTeX} code
directly in the main document within the 
\verb!\beginpicture!\ldots\verb!\endpicture!
environment, or by \verb!\input!ting  the code as a separate
file.
For example, if the {\mathsPIC} file was called \verb!mypic.m!
and this generated the output-file \verb!mypic.mt!, then one would
comment-out everything except the 
picture environment itself, and renaming
it, say, \verb!mypic.pic!,  as follows.


\begin{verbatim}
%% this is file mypic.pic
\beginpicture
...
...
\endpicture
\end{verbatim}

The  \verb!mypic.pic! file can then be \verb!\input! into
a document as a centered Figure as follows.


\begin{Verbatim}
\documentclass[a4paper]{article}
\usepackage{mathspic}
...
...
\begin{figure}[hbt]
\centering
   \strut\input{mypic.pic}
   \caption{...}
   \label{...}
\end{figure}
\end{Verbatim}

Finally, it is important to note that if this approach is used, then it would be necessary to comment out from the \texttt{mathspic.sty} file the \LaTeX\ command \verb!\thispagestyle{empty}! in order to enable page numbering on the first page of the document.


\end{document}
