⟦748a72519⟧

TextFile

% Master File: manual.tex
% Document Type: LaTeX
%
\input{setup12.tex}
\input{transfig}
%
\newcommand{\version}{2.1.1}
%
%\lfoot{\small\it \today}
\lfoot{\small 1 Sept 1990}
\cfoot{\small Version \version}
\rfoot{\small\rm page\ \thepage}
%
\newcommand{\DVI}{{\sc dvi}}
\newcommand{\EPIC}{{\sc epic}}
\newcommand{\EEPIC}{{\sc eepic}}
\newcommand{\FTP}{{\tt FTP}}
\newcommand{\PIC}{{\sc pic}}
\newcommand{\PS}{{\sc ps}}
\newcommand{\psfig}{{\bf psfig}}
\newcommand{\PicTeX}{{PiC\TeX}}
\newcommand{\TFX}{{\sc tfx}}
\newcommand{\tpic}{{\tt tpic}}
\newcommand{\textyl}{{\TeX{tyl}}}
%
\begin{document}

\begin{center}

\Large	\bf	TransFig: Portable Figures for \LaTeX\ \\
	\rm	Version \version \\[0.15in]

\large	\it	Micah Beck
			\footnotetext{The author's Internet mail address is
			{\tt beck@cs.cornell.edu}} \\

\rm		Department of Computer Science \\
		Upson Hall, Cornell University \\
		Ithaca, New York  14853 \\[0.15in]
\end{center}

TransFig is a mechanism for integrating figures into \LaTeX\ documents.
Several ``graphics languages'' exist which achieve such integration,
	but none is widely enough used to be called a standard.
TransFig's goal is to maintain the portability of \LaTeX\ documents across
	printers and operating environments.
The central mechanism in TransFig is Fig code,
	the graphics description format of the Fig interactive graphics editor.
TransFig provides an automatic and uniform way to
	{\it Trans}\,late {\it Fig} code into various graphics languages and
	to integrate that code into a \LaTeX\ document.

\section{TransFig}
The TransFig package consists of the {\tt fig2dev} program,
	which translates between Fig code and other graphics languages,
	and the {\tt transfig} command which can be used to invoke it.
The available translations are illustrated in Figure~\ref{f:intro-trans}
	(which was included using TransFig).
{\tt Fig2dev} can be used directly to translate from Fig code to
	the various graphics languages.
However each graphics language requires the user to load a particular set of
	TeX macros and use particular commands to include the figure.
TransFig allows these differences to be hidden.

When the graphics language is specified to the {\tt transfig} command,
	it creates a macro file and a makefile.
The macro file loads any appropriate TeX macros,
	and the makefile specifies the appropriate commands to create
	\LaTeX\ files which load the figures.
The user simply {\verb|\input|} the macro file and the names of the files
	for loading the figures.
To switch graphics languages,
	it is necessary only to rerun {\tt transfig}, and then {\tt make}.
{\tt Make} can also be used to keep the translated code up to date when
	figures change.

\begin{figure}
	\hrule
	\vspace{2pt}
	\begin{center}
		\input{trans}
	\end{center}
	\hrule
	\caption{Fig Code Translations}
	\label{f:intro-trans}
\end{figure}
\vspace{2pt}

\vfill
\subsection{File Name Conventions}

Suppose that a document is to include a set of figures which are stored in Fig
	code form.
These should be in files with the name suffix {\tt .fig}, for instance
	{\tt figure1.fig, figure2.fig,\ldots figuren.fig}.
TransFig will create files {\tt figure1.tex, figure2.tex,\ldots figuren.tex}
	for {\verb|\input|} to the \LaTeX\ document,
	and in some cases will create files with other suffixes.
Additionally, TransFig creates a file named {\tt transfig.tex} which
	must be {\verb|\input|} at the start of the document.

\vfill
\subsection{Transfig \LaTeX\ Documents}

\begin{figure}
	\hrule
	\vspace{2pt}
	\small
	\begin{center}
		\[ \begin{array}{lr}
%
			\verb|\documentstyle{article}|	& \\
			\verb|\input{transfig}|		&
					 ~~~\mbox{TransFig macro file}\\
			\verb|\begin{document}|		& \\
			\hfill \vdots \hfill		& \\
%
			\verb|\begin{figure}|		& \\
			~~~\verb|\begin{center}|	& \\
			~~~\verb|\input{figurei}|	&
					\mbox{i'th  TransFig figure}\\
%
			~~~\verb|  \end{center}|		& \\
			\verb|\end{figure}|		& \\
			\hfill \vdots \hfill		& \\
%
		\end{array} \]
	\end{center}
	\hrule
	\caption{Layout of a TransFig \LaTeX\ Document}
	\label{f:tex-format}
\end{figure}
\vspace{2pt}

In order to use TransFig, a \LaTeX\ file must follow the format shown in
	Figure~\ref{f:tex-format}.
The the file {\tt transfig.tex}  must be {\verb|\input|} before any
	TransFig figure is encountered.
At the point where the $i$th figure {\tt figurei} is to be inserted,
	the file {\tt figurei.tex} is {\verb|\input|}.

\vfill
\pagebreak
\subsection{Using TransFig}

The {\tt transfig} command has the form
%
\begin{center}
	{\tt transfig}	[{\it option}~]\ldots
			~[~[{\it control}~]\ldots ~{\it filename}~]\ldots
\end{center}
%
Where {\it option} is one of the following:
%
\begin{quote}
\begin{description}
\item[-L \it language]
	to translate into the specified {\it language}
	(default {\tt pictex}).
\item[-M \it makefile]
	to name the output makefile {\it makefile}
	(default {\tt Makefile}).
\item[-T \it texfile]
	to name the output \LaTeX\ macro file {\it texfile}
	(default {\tt transfig.tex}).
\end{description}
\end{quote}
%
The {\it language} specifiers
	{\tt epic, eepic, eepicemu, latex, pictex, ps,
	\linebreak psfig, pstex, textyl} and {tpic},
	indicate translation into
	{\sc (e)}\EPIC\ macros, \LaTeX\ picture environment,
	\PicTeX\ macros, PostScript,
	\textyl specials, or \tpic\ specials.
See section~\ref{s:languages} for further details about these languages.
The special {\it language} specifier {\tt box} causes the figures to be
	replaced by empty boxes of the appropriate size.

A {\it control} specifier sets a parameter which governs the translation
	of all files to its left in the argument list, until it is
	overridden.
A {\it control} specifier must be one of the following:
%
\begin{quote}
\begin{description}
\item[-m \it magnification]
	to scale figures by {\it magnification} (default 1.0).
\item[-f \it font]
	to set the default font family (default {\tt cmr}).
\item[-s \it size]
	to set the default font size (default $12*\mbox{\it magnification}$).
\end{description}
\end{quote}

Each file name specifies a Fig file, either with or without the {\tt .fig}
	suffix.
TransFig creates a file called {\tt Makefile} to apply {\tt fig2dev} with
	the appropriate arguments to the named files,
	and creates an appropriate {\tt transfig.tex} file.
Thus, to create a {\tt Makefile} which will translate all figures in a
	directory to \LaTeX\ picture environment, with Computer Modern Bold as
	the default font family, the command would be
%
\begin{center}
	{\tt transfig -L latex -f cmb *.fig}
\end{center}

After running {\tt transfig}, simply run {\tt make} to create the 
	appropriate \LaTeX\ files.
{\tt Make} should be rerun whenever a Fig file is changed to recreate
	the corresponding \LaTeX\ file.
To change between graphics languages, simply run {\tt make clean} to
	remove the files created by {\tt transfig}, and then rerun
	{\tt transfig}.

The {\tt transfig} command can also be used to include figures described in
	Brian Kernighan's \PIC\ graphics language or in PostScript.
These graphics formats are distinguished by the file name suffix
	{\tt .pic} and {\tt .ps} respectively.
Translation from \PIC\ is accomplished by invoking {\tt pic2fig} program
	(see section \ref{s:pic2fig}).

\subsection{Text in Figures and Portability}
\label{s:portability}

In order to be translatable into different graphics languages, Fig code
	in TransFig documents should use only those features which
	are supported by all of them.
In particular, some graphics languages support more sophisticated processing
	of text which is part of the figure than others.
\PicTeX, for example, allows full use of \LaTeX\ commands in text strings,
	while PostScript does not.

The standard way to use text in TransFig figures is to use only
	straight text with no \LaTeX\ commands.
However, if a text object is flagged as ``special,'' 
	then it is understood to include formatting commands which are
	interpreted by the graphics language.
A document with special text will not be portable to all output languages.

The standard font specifiers are a small set of generic font types.
However, if a text object is flagged as ``PS Font,'' then its font field
	specifies a specific PostScript font.
When translating such text into PostScript, the named font is used.
However, translations into other graphics languages will use some
	approximation to the PS font
This approximation may be quite different from the named font.

\vfill
\pagebreak
\section{Fig Code and Graphics Languages}
\label{s:languages}

TransFig's goal is to provide a framework for including graphics which
	maintains the portability of \LaTeX\ documents across
	printers and operating environments.
The central mechanism in TransFig is Fig code, a graphics description
	format which is produced by the Fig interactive graphics editor.
If this code is widely used as an intermediate form for figures,
	the builders of other graphics tools may be attracted
	to produce compatible output.
The reference guide in appendix~\ref{s:guide} describes Fig code in more
	detail.

\subsection{Translations From Fig}
TransFig currently translates Fig code into these graphics languages:
	{\sc (e)}\EPIC, \LaTeX\  picture environment, \PicTeX, PostScript, 
	\PIC, and \textyl specials.
The program which accomplishes these translations is {\tt fig2dev},
	which replaces the now-obsolete programs
	{\tt fig2tex}, {\tt fig2ps}, {\tt fig2latex}, and
	\linebreak {\tt fig2epic}.
The {\tt transfig} command supports the translation of Fig code into
	\tpic\ specials (see below) using \tpic,
	which is not part of the TransFig package.
Each language may be appropriate in different operating environments
	or for different applications.
A short description of each language is given below:
%
\begin{quote}
\begin{description}
\item[\PicTeX]
	is a set of \TeX\ macros which implement simple
		graphics objects directly in \TeX.
	\PicTeX\ makes no use of pre- or post-processors; the \DVI\ files it
		generates are completely standard, and can be printed or
		previewed in any environment where \TeX\ is used.
	This result is achieved by using \TeX\ integer arithmetic to
		do all plotting calculations, and by drawing the figure
		using the period character as a ``brush''.
	As a result \PicTeX\ is quite slow and requires a large internal
		\TeX\ memory.

\item[PostScript]
	(\PS)\, is a powerful graphics language which is gaining
		acceptance as a standard.
	In an environment where \DVI\ code is translated into \PS\ before
		being printed, it is usually possible to insert a
		separately generated PostScript file into a 
		document, using the \TeX\ {\verb|\special|} command.
	However, the resulting \PS\ file can only be previewed using a
		\PS\ previewer, and must be printed on a \PS\ printer,
		such as the Apple LaserWriter.

	Various options are available for integration of \PS\ with \LaTeX.
	The \psfig\ macro automatically scans the \PS\ file for bounding box
		information and generates appropriate TeX spacing and inclusion
		commands.
	One limitation of \PS\ output is the lack of \LaTeX\ formatting for
		special objects.
	The {\bf pstex} language specifier to the {\tt transfig} command
		uses special {\tt fig2dev} output drivers which separate
		the figure in text and non-text portions, rendering the
		former in \PS\ and the latter in \LaTeX.
	The {\bf pstex} option uses \psfig\ to generate the \PS\ inclusion
		commands.

\item[\LaTeX]
	picture environment is a restricted graphics facility implemented
		within \LaTeX.
	It is a standard part of every version of \LaTeX, is processed
		quickly, and does not require a large internal \TeX\ memory.
	However, not every graphics object which can be described with
		 Fig code can be drawn using the \LaTeX\ picture environment.
	Restrictions include a limited set of slopes at which lines can be
		drawn, and no ability to drawn splines.

\item[\EPIC]
	is an enhanced version of the \LaTeX\ picture environment which
		removes many restrictions.
	It uses no facilities outside 	of those needed for the
		\LaTeX\ picture environment.

\item[\EEPIC]
	is a further enhancement of \EPIC\ which uses \tpic\ specials
		to implement general graphics objects.
	It is subject to the same software requirements as \tpic.

\item[\textyl]
	specials are a set of \verb|\special| commands which 
		produce graphics instructions in the \DVI\ file
		produced by \TeX.
The resulting \DVI\ file must be postprocessed using the \textyl\ program,
	which transforms it into a standard \DVI\ file which uses its own 
	line drawing fonts.
	
\item[\tpic]
	specials are a set of \verb|\special| commands which 
		produce graphics instructions in the \DVI\ file
		produced by \TeX.
	However, the graphics in the resulting \DVI\ file can only be
		previewed or printed using software which understands
		these commands.

\end{description}
\end{quote}
%
When \LaTeX\ processes the file {\tt transfig.tex}, it will print the message
	 \linebreak ``{\verb|TransFig: figures in |}{\it language}''
	indicating which graphics language is in use.

\subsection{The Fig Graphics Editor}
\label{s:fig}
The interpretation of Fig code was originally defined by 
	the Fig graphics editor and the program {\tt f2p},
	which translates Fig code into the \PIC\ graphics language. 
The most recent version is V2.1; it is implemented by Version 2.1 of the
	Fig graphics editor, which runs under SunView.

Previous versions of Fig code which have been widely used are \TFX,
	and V2.0.
\TFX, which was defined by the TransFig package, was a compatible extension to
	the Fig code V1.4, as defined by the last official version of Fig.
V2.0 was implemented by XFig, 
	which runs under Version 11 of the X Windowing System.
The definition of V2.0 was incompatible with \TFX, and had features
	which made translation into output forms other than PostScript
	difficult.
XFig also supports \TFX compatibility as a compile-time option.

TransFig supports \TFX, and supports translation of V2.0 to PostScript.
In order to unify the various versions of Fig code, V2.1 supports
	the PS-specific features of V2.0 {\em as an option}.
Thus, V2.1 can describe figure in a manner which is either highly
	portable, as with \TFX, or in a way which makes use of PostScript's
	powerful features.
A future release of XFig may implement V2.1.

\subsection{Other Fig Compatible Programs}
\label{s:pic2fig}

The following programs use Fig code as a graphics description format,
	and thus are compatible with TransFig:
%
\begin{itemize}

\item The numerical plotting program {\tt gnuplot} can optionally produce 
	output in Fig code format.

\item The \PIC-to-Fig translator {\tt pic2fig} translates \PIC,
	the language of Brian Kernighan's graphics preprocessor for Troff,
	into Fig code.
This allows users to create figures without employing a	graphics editor.

\item The Plot-to-Fig translator {\tt plot2fig} translates the Unix 
	plot file format to Fig code.

\item The XApGraph graphics editor is an experimental X-Windows application
	which can create and edit figures described in Fig code	or in ApGraph,
	a new application level graphics language.

\end{itemize}
%
The Fig code produced by these programs can be viewed and edited 
	using the Fig graphics editor.

\vfill
\pagebreak
\section{Related Software}
\label{s:software}

Software availability is subject to change, and this list may not be
	completely up to date.

\begin{description}

\item[\EPIC]
	is an enhancement of the \LaTeX\ picture environment which
	removes many restrictions.
It uses only the facilities which implement the \LaTeX\ picture environment.
\EPIC\ was developed by Sunil Podar at the State University of New York
	at Stonybrook, and is available via anonymous
	\FTP\ from {\tt SUN.SOE.CLARKSON.EDU}.

\item[\EEPIC]
	is a further enhancement of \EPIC\ which uses \tpic\ specials
	(see below) to implement general graphics objects.
It is subject to the same software requirements as \tpic,
	although there is an ``emulation package'' which will
	implement most of \EEPIC\ using the same facilities as \EPIC.
\EEPIC\ was developed by Conrad Kwok at the University of California at Davis,
	and is available via anonymous \FTP\  from {\tt SUN.SOE.CLARKSON.EDU}

\item[Fig]
	is an interactive graphics editor in the style of MacDraw
	which runs under the Suntools/SunView windowing system.
It produces intermediate code which can be translated into
	a variety of graphics languages, including \PIC, Postscript,
	and \PicTeX.

Fig was developed by Supoj Sutanthavibul at the University of Texas at Austin,
	({\tt supoj@SALLY.UTEXAS.EDU}), and is available via anonymous
	\FTP\  from {\tt SALLY}.

\item[Fig 2.1]
	is a version of Fig which implements various
	enhancements to the user interface, and uses Fig code V2.1
Fig 2.1 was developed by various contributors, and is supported by Micah Beck
	at Cornell University ({\tt beck@CS.CORNELL.EDU}).
It is available via anonymous \FTP\ from {\tt SVAX.CS.CORNELL.EDU}.

\item[Fig2dev]
	translates  from Fig code to \PicTeX\ macros, Postscript,
	\LaTeX\ picture environment commands, {\sc (e)}\EPIC\ macros, \textyl,
	and the \PIC\ graphics language.
It is part of the TransFig package, and supports Fig code V2.1.

\item[Fig2tex, Fig2ps, Fig2latex, Fig2epic, Fig2pic]
	are Fig code translation programs which were distributed as
	part of earlier versions of the TransFig package.
They have been replaced by fig2dev (see above).

\item[F2p, F2ps]
	are the original Fig code translation programs.
These programs are out of date and have been subsumed by fig2dev (see above).

\item[GnuPlot]
	is a numerical plotting program which can optionally produce output
	in Fig code format.
GnuPlot was developed by a group of people, including
	Thomas Williams and Colin Kelly of Pixar Corp.
	({\tt pixar@INFO-GNUPLOT@SUN.COM}),
	and David F. Kotz of Duke University ({\tt dfk@DUKE.CS.DUKE.EDU}).
Gnuplot is available via anonymous \FTP\ from {\tt DUKE}.

\item[\LaTeX]
	is a standard macro package used for describing documents in \TeX.
Part of this package is the \LaTeX\ picture environment, a restricted
	graphics facility.
The capabilities of this facility are described in section~5.5 of 
	{\em \LaTeX, A Document Preparation System} by Leslie Lamport.

\item[Pic2fig]
	is a version of Brian Kernighan's \PIC\ graphics preprocessor
	for Troff.
Pic2fig, which is a modified form of \tpic\ (see below), has been altered
	to produce Fig code.
For Pic2fig distribution information, contact Micah Beck of
	Cornell University ({\tt beck@CS.CORNELL.EDU}).

	
\item[\PicTeX]
	is a set of macros for describing graphics in \TeX\ documents.
	\PicTeX\ is implemented entirely within standard \TeX, and requires no
	pre- or post processing programs or special fonts.
The main problem in using \PicTeX\ is its slow operation (all calculations
	are done using \TeX's integer arithmetic) and large memory
	requirements.
Many \PicTeX\ users have turned to C implementations of \TeX\ in order
	to obtain memory sizes larger than are possible using the standard
	Web/Pascal version.

\PicTeX\ was developed by Michael Wichura at the University of
	Chicago ({\tt wichura@GALTON.UCHICAGO.EDU}), and is available via
	anonymous \FTP\  from {\tt A.CS.UIUC.EDU}.
It is also included as contributed software with the Unix \TeX\ distribution.

\item [Plot2fig]
	translates figures from the Unix plot file format to Fig code.
Plot2fig was developed by Richard Murphy of Rice University
	({\tt rich@RICE.EDU}),
	and is available via anonymous \FTP\ from {\tt QED.RICE.EDU}.

\item[\textyl]
	is a \DVI\ file postprocessor which translates {\verb|\special|}
commands into its own set of drawing fonts.
	The result of this postprocessing is a standard \DVI file which
can be printed using any \DVI\ driver, as long as its drawing fonts
	are available.
\textyl is available via anonymous \FTP\ from {\tt VENUS.YCC.YALE.EDU}.

\item[\tpic]
	is a version of Brian Kernighan's \PIC\ graphics preprocessor
	for Troff.
\tpic\ has been altered to produce \TeX\ {\verb|\special|} commands which
	are understood by some \DVI\ print drivers and previewers.
For information about distribution of \tpic, contact Tim Morgan of
	the University of California at Irvine ({\tt morgan@ICS.UCI.EDU}).

\item[TransFig]
	was developed by Micah Beck at Cornell University
	\linebreak ({\tt beck@CS.CORNELL.EDU}), with major contributions
	by Frank Schmuck, now of IBM, and Conrad Kwok of UC Davis.
	It is available via anonymous \FTP\ from {\tt SVAX.CS.CORNELL.EDU}.

\item[Xfig]
	is a version of the Fig graphics editor which can be compiled for
	either the Suntools or X Windows Version 11 windowing systems.
Xfig is part of the contributed software distributed with the X Windowing
	System, and can be obtained by anonymous FTP from 
	{\tt EXPO.LCS.MIT.EDU}.

\item[XApGraph]
	is an experimental X-Windows graphics editor which can create and
	edit figures described in Fig code or in ApGraph,
	a new application level graphics language.
XApGraph is being developed by Alex Siegel at Cornell University	
	({\tt siegel@CS.CORNELL.EDU}), but is not currently available.

\item[Xpic]
	is a graphical editor similar to Fig which runs under X Windows
	Version 11.
Xpic was developed by Mark Moraes at the University of Toronto
	({\tt moraes@csri.toronto.edu}) and is available via anonymous
	\FTP\ from {\tt ai.toronto.edu}.

\end{description}

\raggedbottom
\pagebreak

\appendix

\section{Fig Code Reference Guide}
\label{s:guide}
This guide describes Fig code Version \version,
	an extension of the intermediate code produced by version 1.4
	of the Fig graphics editor.
This format is not compatible with the code produced by Fig version 1.3.
A Fig \version code file has the following structure:
%
\begin{quote}
\begin{tabbing}
\verb|#FIG 2.1|			\\
\it global parameters	  	\\
\it object description	 	\\
\it object \= \it description 	\\
\> $\vdots$
\end{tabbing}
\end{quote}
%
\subsection{Comment Lines}
The very first line is a comment line containing the version
	of the Fig format.
Programs which interpret Fig code verify compatibility by checking
	the first line for this comment.
All other lines which contain the character \verb|#| in the first column
	are treated as comments and are ignored.

\subsection{Global Parameters}
The first non-comment line consists of two global parameters:
%
\begin{quote}
\tt
fig\_resolution coordinate\_system
\end{quote}
%
Fields in a line of a Fig file are separated by blanks or tabs;
	newlines terminate object descriptions.
The fields of lines in Fig files are described throughout this
	guide by tables like the one below.
The fields must appear in the order given in the table.
%
\vspace{2pt}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Type 	& Field				& Units (values)		\\
\hline
\hline
int 	& {\tt fig\_resolution}		& pixels/inch			\\
	&				& Fig value: 80			\\
\hline
int	& {\tt coordinate\_system}	& 1: origin at lower left corner\\
	&				& 2: origin at upper left corner\\
	&				& Fig value: 2			\\ 
\hline
\end{tabular}
\end{center}
\vspace{2pt}

The {\em Type} column specifies the type of the field,
	and is either int(eger), float, or string.
The notation + following the type indicates that the values 0 or -1
	 are interpreted as {\em default} values in this field.
The rightmost column of this table either defines the units in which
	the field is expressed, or lists the possible values which
	the field can take.
The notation {\tt DEFAULT} in this column indicates that no value other
	than the default values are allowed.
It is intended that future versions of Fig will define other values for
	these fields, but that the default values will remain legal,
	thus providing backward compatibility.

The basic unit of position in Fig files is the pixel.
While figures in a Fig file are described at this resolution,
	the figure can be drawn at a higher or lower resolution.
Pixels are square, and so \verb|fig_resolution| represents position
	resolution in both the x and y dimensions.

Some values are expressed as symbols and their numerical values are also listed.
These symbols are defined in the header file {\tt object.h}.

\subsection{Object Descriptions}
The rest of the file contains objects descriptions,
	having one of six types:

\begin{enumerate}
\item Ellipse.
\item Polyline, including Polygons and Boxes.
\item Spline, including Closed/Open Control/Interpolated Splines.
\item Text.
\item Circular Arc.
\item Compound object which is composed of one or more objects.
\end{enumerate}

The following group of common fields appear in several object
	descriptions, and so the are described here, and later are
	simply referred to by the indicator {\it common fields}.
%
\vspace{2pt}
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)	&	\\ \hline
\hline
int	& {\tt line\_style}	& {\tt SOLID\_LINE}	& 0	\\
	&			& {\tt DASH\_LINE}	& 1	\\
	&			& {\tt DOTTED\_LINE}	& 2	\\ \hline
%
int	& {\tt line\_thickness}	& pixels		&	\\ \hline
%
int +	& {\tt color}		& {\tt DEFAULT}		&	\\ \hline
%
int  	& {\tt depth}		& no units		&	\\ \hline
%
int +	& {\tt pen}		& {\tt DEFAULT}		&	\\ \hline
%
int +	& {\tt area\_fill}	& {\tt DEFAULT}		& 	\\
	&			& {\tt WHITE\_FILL}	&   1	\\
	&			& {\tt BLACK\_FILL}	&   21	\\ \hline
%
float	& {\tt style\_val}	& pixels		&	\\ \hline
\end{tabular}
\end{center}
\vspace{4pt}
%
For the dashed line style, the {\tt style\_val}	specifies the length of a dash.
For dotted lines it indicates the gap between consecutive dots. 
Depth determines which filled objects will obscure other objects,
	with the objects of greater depth being obscured.
The values between {\tt WHITE\_FILL} and {\tt BLACK\_FILL} define a gray scale;
	many graphics languages cannot fully implement area fill.

Arrow lines are used to describe optional arrows at the ends of
	Arc, Polyline, and Spline objects.
If an object has a forward arrow, then an arrow line describing it
	follows the object description.
If an object has a backward arrow, then an arrow line describing it
	follows the object description and the forward arrow description,
	if there is one.

An arrow line consists of the following fields
%
\vspace{4pt}
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)	&	\\ \hline
\hline
%
int +	& {\tt arrow\_type}	& {\tt DEFAULT}		&	\\ \hline
%
int +	& {\tt arrow\_style}	& {\tt DEFAULT}		&	\\ \hline
%
float +	& {\tt arrow\_thickness}& {\tt DEFAULT}		&	\\ \hline
%
float	& {\tt arrow\_width}	& pixels		&	\\ \hline
%
float	& {\tt arrow\_height}	& pixels		&	\\ \hline
\end{tabular}
\end{center}
\vspace{2pt}

The pen and color fields can only take the value DEFAULT.
It is intended that future extensions to Fig code will define
	other values for these fields.
Their intended use is discussed below:
\begin{quote}
\begin{description}

\item[\tt pen]		This will define the shape of
			pen used in drawing objects.  It also includes
			the the stipple pattern for line filling.
			The default pen is a circular pen with black
			filling.

\item[\tt color]	The color used to draw an object and its area fill.

\end{description}
\end{quote}

\subsubsection{Ellipse Objects}
%
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline

Type	& Field			& Units (values)	&	\\ \hline
\hline
%
int	& {\tt object\_code} 	& {\tt O\_ELLIPSE}	&     1	\\ \hline
%
int	& {\tt sub\_type}	& {\tt T\_ELLIPSE\_BY\_RAD} & 1	\\
	&			& {\tt T\_ELLIPSE\_BY\_DIA} & 2	\\
	&			& {\tt T\_CIRCLE\_BY\_RAD} &  3	\\
	&			& {\tt T\_CIRCLE\_BY\_DIA} &  4	\\ \hline
%
\multicolumn{4}{c}{\it common fields}				\\ \hline
%
int	& {\tt direction}	& 1			&	\\ \hline
%
float	& {\tt angle}		& radians		&	\\ \hline
%
int	& {\tt center\_x},
	  {\tt center\_y}	& pixels		&	\\ \hline
%
int	& {\tt radius\_x},
	  {\tt radius\_y}	& pixels		&	\\ \hline
%
int	& {\tt start\_x},
	  {\tt start\_y}	& pixels		&	\\ \hline
%
int	& {\tt end\_x},
	  {\tt end\_y}		& pixels		&	\\ \hline
\end{tabular}
\end{center}
%
The Ellipse object describes an ellipse (or circle) centered at the point
	\linebreak ({\tt center\_x}, {\tt center\_y})
	with radii {\tt radius\_x} and {\tt radius\_y}, and whose x-axis
	is rotated by {\tt angle} from the horizontal.
If the object describes a circle, then {\tt radius\_x} and {\tt radius\_y}
	must be equal.

The fields {\tt start\_x, start\_y, end\_x and end\_y} are used only by
	Fig, and are not used in drawing the object.
If the ellipse is specified by radius, then $({\tt start\_x}, {\tt start\_y})$
	is $({\tt center\_x}, {\tt center\_y})$,
	and $({\tt end\_x}, {\tt end\_y})$ is a corner of a box which
	bounds the ellipse.
If the ellipse is specified by diameter, then $({\tt start\_x}, {\tt start\_y})$
	and $({\tt end\_x}, {\tt end\_y})$ are the two corners of the box
	which bound the ellipse.

\subsubsection{Polyline Objects}
%
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)	&	\\ \hline
\hline
%
int	& {\tt object\_code} 	& {\tt O\_POLYLINE}	& 2	 \\ \hline
%
int	& {\tt sub\_type}	& {\tt T\_POLYLINE}	& 1	\\
	&			& {\tt T\_BOX}		& 2	\\
	&			& {\tt T\_POLYGON}	& 3	\\
	&                       & {\tt T\_ARC\_BOX}   	& 4	\\ \hline
%
\multicolumn{4}{c}{\it common fields}				\\ \hline
%
int	& {\tt radius}		& no units		& 	\\
int	& {\tt forward\_arrow},	& 0: no arrow		&	\\
	& {\tt backward\_arrow}	& 1: arrow		&	\\ \hline
\end{tabular}
\end{center}
%
The Polyline object description has an addition {\em points line} following
	any arrow lines.
The line consists of a sequence of coordinate pairs followed by the
	pair 9999 9999 which marks the end of the line.
%
\begin{quote}
$
	 {\tt x}_1 ~{\tt y}_1 ~{\tt x}_2 ~{\tt y}_2 \ldots
	~{\tt x}_n ~{\tt y}_n ~9999 ~9999
$
\end{quote}
%
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)	&	\\ \hline
\hline
%
int	& ${\tt x}_i, {\tt y}_i$& pixels		&	\\ \hline
\end{tabular}
\end{center}

The Polyline object describes a piecewise linear curve starting at
	the point $({\tt x}_1, {\tt y}_1)$ and passing through 
	each point ${(\tt x}_i, {\tt y}_i)$ for $i = 2 \ldots n$.
If {\tt sub\_type} is {\tt T\_BOX} or {\tt T\_POLYGON} then 
	$({\tt x}_1, {\tt y}_1)$ and $({\tt x}_n, {\tt y}_n)$ must
	be identical.
If {\tt sub\_type} is {\tt T\_BOX}, then the line segments must all be
	a vertically oriented rectangle.
If {\tt sub\_type} is {\tt T\_ARC\_BOX}, then the corners of the box are
	drawn with circular arcs, the size of which are determined by
	the {\tt radius} field.
Many output modes draw {\tt T\_ARC\_BOX} object as simple boxes.

\subsubsection{Spline Objects}
%
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)		&	\\ \hline
\hline
%
int	& {\tt object\_code}	& {\tt O\_SPLINE}		& 3	\\ \hline
%
int	& {\tt sub\_type}	& {\tt T\_OPEN\_NORMAL}		& 0	\\
	&			& {\tt T\_CLOSED\_NORMAL} 	& 1	\\
	&			& {\tt T\_OPEN\_INTERPOLATED}	& 2	\\
	&			& {\tt T\_CLOSED\_INTERPOLATED}	& 3	\\ \hline
%
\multicolumn{4}{c}{\it common fields}					\\ \hline
%
int	& {\tt forward\_arrow},	& 0: no arrow			&	\\
	& {\tt backward\_arrow}	& 1: arrow			&	\\ \hline
\end{tabular}
\end{center}
%
The Spline object description has a {\em points line} following
	any arrow line which has the same format as described above
	for the Polyline object description.
If the {\tt sub\_type} of the spline is	{\tt T\_OPEN\_INTERPOLATED} or
	\linebreak {\tt T\_CLOSED\_INTERPOLATED}, then an additional
	{\em control points line} follows the points line.
The line consists of a sequence of coordinate pairs, two coordinate pairs
	for each point in the points line.
%
\begin{quote}
$
	{\tt lx}_1 ~{\tt ly}_1 ~{\tt rx}_1 ~{\tt ry}_1
	~{\tt lx}_2 ~{\tt ly}_2 ~{\tt rx}_2 ~{\tt ry}_2
	\ldots
	~{\tt lx}_n ~{\tt ly}_n ~{\tt rx}_n ~{\tt ry}_n
$
\end{quote}
%
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)	&	\\ \hline
\hline
%
float	& ${\tt lx}_i,{\tt ly}_i,
	   {\tt rx}_i,{\tt ry}_i$& pixels		&	\\ \hline
\end{tabular}
\end{center}
%
The interpretation of Spline objects is more complex than of other
	object descriptions, and is discussed in section~\ref{s:splines}.

\subsubsection{Text Objects}

\begin{center}
\begin{tabular}{|l|l|ll|}
\hline
Type 	& Field			& Units (values) 		&	\\ \hline
\hline
\tt
int	& {\tt object\_type}	& {\tt O\_TEXT}			& 4	\\ \hline
%
int	& {\tt sub\_type}	& {\tt T\_LEFT\_JUSTIFIED}	& 0	\\
	&			& {\tt T\_CENTER\_JUSTIFIED}	& 1	\\
	&			& {\tt T\_RIGHT\_JUSTIFIED}	& 2	\\
									\hline
%
int +	& {\tt font}		& {\tt DEFAULT}		& 	\\
	&			& {\tt ROMAN}		& 1	\\
	&			& {\tt BOLD}		& 2	\\
	&			& {\tt ITALICS}		& 3	\\
	&			& {\tt MODERN}		& 4	\\
	&			& {\tt TYPEWRITER}	& 5	\\ \hline
%
float +	& {\tt font\_size}	& points		&	\\ \hline
%
int +	& {\tt pen}		& {\tt DEFAULT}		&	\\ \hline
%
int +	& {\tt color}		& {\tt DEFAULT}		&	\\ \hline
%
int  	& {\tt depth}		& no units		&	\\ \hline
%
float	& {\tt angle}		& radians		&	\\ \hline
%
int +	& {\tt text\_flags}	& no units		&	\\ \hline
%
float +	& {\tt height, length}	& pixels		&	\\ \hline
%
int	& {\tt x, y}		& pixels		&	\\ \hline
%
string	& string		& 			&	\\ \hline
\end{tabular}
\end{center}
%
The positioning of the string is specified by the {\tt sub\_type}.
The values {\tt T\_LEFT\_JUSTIFIED}, {\tt T\_CENTER\_JUSTIFIED},
	and {\tt T\_RIGHT\_JUSTIFIED} specify that 
	$({\tt x}, {\tt y})$ is the left end, center and right end
	 of the baseline, respectively.
The {\tt height} and {\tt length} fields specify the box that the
	text fits into.
These specifications are accurate only for the fonts used by Fig.

The {\tt string} field is an ascii string terminated by the character
	\verb|'\01'|.
This terminating character is not a part of the	string.
Note that the string may contain the new-line character \verb|'\n'|.

The {\tt text\_flags} field is a bit vector which specifies various
	settable properties of the text object.
Each flag corresponds to a bit position in the field; the default value
	of each flag is {\tt FALSE}.

\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Flag			& Bit mask	& Description		\\
			& (in binary)	&			\\ \hline
\hline
%
{\tt RIGID\_TEXT}	& 001 	&  Font size scales with magnification\\ \hline
%
{\tt SPECIAL\_TEXT}	& 010	&  Text includes formatting commands \\ \hline
%
{\tt PSFONT\_TEXT}	& 100	&  Font field Specifies PS font	\\ \hline
\end{tabular}
\end{center}

The {\tt RIGID\_TEXT} flag is used to preserve the size of text objects
	relative to graphical objects as the figure is scaled.
The {\tt SPECIAL\_TEXT} flag is used to inhibit the ``escaping'' of formatting
	commands when translating text to \LaTeX or Troff, in order to allow
	the user to inject such commands directly into the figure.
Finally, the {\tt PSFONT\_TEXT} flag changes the interpretation of the font
	field.
Rather than selecting from the limited set of generic fonts shown in the table
	above, the field is interpreted as selecting from the following table
	of PostScript fonts.
A text object with the {\tt PSFONT\_TEXT} flag set may not be fully 
	translatable into output forms other than PostScript.

\begin{center}
\begin{tabular}{|l|l|}
\hline
PS Font				& Value		\\ \hline
\hline
Times-Roman			& 1 		\\ \hline
Times-Italic			& 2 		\\ \hline
Times-Bold			& 3 		\\ \hline
Times-BoldItalic		& 4		\\ \hline
AvantGarde			& 5		\\ \hline
AvantGarde-BookOblique		& 6		\\ \hline
AvantGarde-Demi			& 7		\\ \hline
AvantGarde-DemiOblique		& 8		\\ \hline
Bookman-Light			& 9		\\ \hline
Bookman-LightItalic		& 10		\\ \hline
Bookman-Demi			& 11		\\ \hline
Bookman-DemiItalic		& 12		\\ \hline
Courier				& 13		\\ \hline	
Courier-Oblique			& 14		\\ \hline
Courier-Bold			& 15		\\ \hline
Courier-BoldItalic		& 16		\\ \hline
Helvetica			& 17		\\ \hline
Helvetica-Oblique		& 18		\\ \hline
Helvetica-Bold			& 19		\\ \hline
Helvetica-BoldOblique		& 20		\\ \hline
Helvetica-Narrow		& 21		\\ \hline
Helvetica-Narrow-Oblique	& 22		\\ \hline
Helvetica-Narrow-Bold		& 23		\\ \hline
Helvetica-Narrow-BoldOblique	& 24		\\ \hline
NewCenturySchlbk-Roman		& 25		\\ \hline
NewCenturySchlbk-Italic		& 26		\\ \hline
NewCenturySchlbk-Bold		& 27		\\ \hline
NewCenturySchlbk-BoldItalic	& 28		\\ \hline
Palatino-Roman			& 29		\\ \hline
Palatino-Italic			& 30		\\ \hline
Palatino-Bold			& 31		\\ \hline
Palatino-BoldItalic		& 32		\\ \hline
Symbol				& 33		\\ \hline
ZapfChancery-MediumItalic 	& 34		\\ \hline
ZapfDingbats			& 35		\\ \hline
\end{tabular}
\end{center}

\subsubsection{Arc Objects}
%
\begin{center}
\begin{tabular} {|l|l|ll|}
\hline
Type	& Field			& Units (values)	&	\\ \hline
\hline
%
int	& {\tt object\_code} 	& {\tt O\_ARC}		& 5	\\ \hline
%
int	& {\tt sub\_type}	& {\tt T\_3\_POINT\_ARC}& 1	\\ \hline
%
\multicolumn{4}{c}{\it common fields}				\\ \hline
%
int	& {\tt direction}	& 0: clockwise		&	\\
	&			& 1: counter		&	\\ \hline
%
int	& {\tt forward\_arrow},	& 0: no arrow		&	\\
	& {\tt backward\_arrow}	& 1: arrow		&	\\ \hline
%
float	& {\tt center\_x},
	  {\tt center\_y}	& pixels		&	\\ \hline
%
int   	& ${\tt x}_1, {\tt y}_1,
	   {\tt x}_2, {\tt y}_2,
	   {\tt x}_3, {\tt y}_3$& pixels		&	\\ \hline
\end{tabular}
\end{center}
%
The Arc object describes a circular arc centered at the point
	\linebreak $({\tt center\_x}, {\tt center\_y})$, starting at 
	$({\tt x}_1, {\tt y}_1)$, passing through $({\tt x}_2, {\tt y}_2)$,
	and ending at $({\tt x}_3, {\tt y}_3)$.
It is drawn either clockwise of counter-clockwise as specified by
	{\tt direction}.
Note that this description is quite overdetermined, as the center and
	direction of the arc can be deduced from the three points
 	of the arc which are specified.
	 
\subsubsection{Compound Objects}

\begin{center}
\begin{tabular}{|l|l|ll|}
\hline
Type 	& Field			& Units (values) 		&	\\ \hline
\hline
\tt
int	& {\tt object\_type}	& {\tt O\_COMPOUND}		& 6	\\ \hline
%
int	& {\tt upperright\_corner\_x}	& pixels		&	\\
int	& {\tt upperright\_corner\_y}	& 			&	\\
int	& {\tt lowerleft\_corner\_x}	& 			&	\\
int	& {\tt lowerleft\_corner\_y}	& 			&	\\ \hline
\end{tabular}
\end{center}

The Compound object description describes a compound object
	bounded by the rectangle determined by the points
%
\begin{quote}
\[ \begin{array}{l}
	({\tt upperright\_corner\_x}, {\tt upperright\_corner\_y})	\\
	({\tt lowerleft\_corner\_x}, {\tt lowerleft\_corner\_y})
\end{array} \]
\end{quote}
%
It consists of all the objects following it until an object whose 
	{\tt object\_type} field is {\tt O\_END\_COMPOUND} (-6) is encountered.
Compound objects may be nested.

\subsection{Splines}
\label{s:splines}

Specifying the interpretation of a Spline object description is more problematic
	than other graphics objects.
A graphics object description can be viewed as having two parts:
	an abstract description of the locus of points which 
	make up the object; and a set of appearance parameters
	which specify how the abstract object is to be represented.
For example, a circular arc has a very precise and well understood abstract
	definition, independent of the width of the line used to
	draw it.
Unfortunately, the abstract specification of splines is more complex.
The following descriptions come at second hand; the author of this
	guide is not versed in spline algorithms, and so 
	may have garbled them.
Hopefully, they will give the knowledgeable reader some idea of the
	intended meaning of Spline objects.

Fig splines come in two major varieties: B-splines and Interpolated splines.
Each of these is available in open or closed versions.
If the {\tt sub\_type} field has the values {\tt T\_OPEN\_NORMAL}
	or {\tt T\_CLOSED\_NORMAL} then it describes a B-spline.
In these cases, the points line which follows contains the
	{\tt control points} for the spline.
The spline does not actually pass through these points, but they determine
	where it will pass, which is generally quite close to the control
	points.
B-splines are quite smooth.

If the {\tt sub\_type} field has the values {\tt T\_OPEN\_INTERPOLATED}	or
	\linebreak {\tt T\_CLOSED\_INTERPOLATED} then it describes an
	interpolated spline.
In these cases, the points line which follows contains the
	{\em interpolation points} through which the spline will pass.
In addition, a {\em control points} line follows the points line,
	which specifies two control points $({\tt lx}_i, {\tt ly}_i)$ and
	$({\tt rx}_i, {\tt ry}_i)$ for each interpolation point.
The {\tt i}'th section of the interpolated spline is drawn using the
	Bezier cubic with the four points
	$({\tt x}_i, {\tt y}_i)$,  \linebreak $({\tt rx}_i, {\tt rx}_i)$,  
	$({\tt lx}_{i+1}, {\tt ly}_{i+1})$,
	and $({\tt x}_{i+1}, {\tt y}_{i+1})$.
Interpolated splines are not as smooth as B-splines.

For either type of closed splines, the first and last points
on the point line
	$({\tt x}_1, {\tt y}_1)$ and $({\tt x}_n, {\tt y}_n)$
	are identical.
For closed interpolated splines, the last pair of control points on the
control points line,
	$({\tt lx}_n, {\tt ly}_n)$ and $({\tt rx}_n, {\tt ry}_n)$
	are the same as
	$({\tt lx}_1, {\tt ly}_1)$ and $({\tt rx}_1, {\tt ry}_1)$
	respectively.

\end{document}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦748a72519⟧ TextFile

Derivation

TextFile
