rsalz@bbn.com (Rich Salz) (08/31/90)
Submitted-by: Micah Beck <beck@cs.cornell.edu>
Posting-number: Volume 23, Issue 19
Archive-name: transfig/part06
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 6 (of 6)."
# Contents: transfig/doc/manual/manual.tex
# Wrapped by beck@rocky on Thu May 17 15:56:14 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'transfig/doc/manual/manual.tex' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'transfig/doc/manual/manual.tex'\"
else
echo shar: Extracting \"'transfig/doc/manual/manual.tex'\" \(36693 characters\)
sed "s/^X//" >'transfig/doc/manual/manual.tex' <<'END_OF_FILE'
X% Master File: manual.tex
X% Document Type: LaTeX
X%
X\input{setup12.tex}
X\input{transfig}
X%
X\newcommand{\version}{2.0}
X\newcommand{\release}{1}
X%
X%\lfoot{\small\it \today}
X\lfoot{\small 1 May 1990}
X\cfoot{\small Ver \version\ Rel \release}
X\rfoot{\small\rm page\ \thepage}
X%
X\newcommand{\PicTeX}{{PiC\TeX}}
X\newcommand{\EPIC}{{\sc epic}}
X\newcommand{\EEPIC}{{\sc eepic}}
X\newcommand{\PS}{{\sc ps}}
X\newcommand{\DVI}{{\sc dvi}}
X\newcommand{\PIC}{{\sc pic}}
X\newcommand{\TFX}{{\sc tfx}}
X\newcommand{\FTP}{{\tt FTP}}
X\newcommand{\tpic}{{\tt tpic}}
X%
X\begin{document}
X
X\begin{center}
X
X\Large \bf TransFig: Portable Figures for \LaTeX\ \\
X \rm Version \version\ Release \release \\[0.15in]
X
X\large \it Micah Beck
X \footnotetext{The author's Internet mail address is
X {\tt beck@cs.cornell.edu}} \\
X
X\rm Department of Computer Science \\
X Upson Hall, Cornell University \\
X Ithaca, New York 14853 \\[0.15in]
X\end{center}
X
XTransFig is a mechanism for integrating figures into \LaTeX\ documents.
XSeveral ``graphics languages'' exist which achieve such integration,
X but none is widely enough used to be called a standard.
XTransFig's goal is to maintain the portability of \LaTeX\ documents across
X printers and operating environments.
XThe central mechanism in TransFig is Fig code,
X the graphics description format of the Fig interactive graphics editor.
XTransFig provides an automatic and uniform way to
X {\it Trans}\,late {\it Fig} code into various graphics languages and
X to integrate that code into a \LaTeX\ document.
X
X\section{TransFig}
XThe TransFig package consists of the {\tt fig2dev} program,
X which translates between Fig code and other graphics languages,
X and the {\tt transfig} command which can be used to invoke it.
XThe available translations are illustrated in Figure~\ref{f:intro-trans}
X (which was included using TransFig).
X{\tt Fig2dev} can be used directly to translate from Fig code to
X the various graphics languages.
XHowever each graphics language requires the user to load a particular set of
X TeX macros and use particular commands to include the figure.
XTransFig allows these differences to be hidden.
X
XWhen the graphics language is specified to the {\tt transfig} command,
X it creates a macro file and a makefile.
XThe macro file loads any appropriate TeX macros,
X and the makefile specifies the appropriate commands to create
X \LaTeX\ files which load the figures.
XThe user simply {\verb|\input|} the macro file and the names of the files
X for loading the figures.
XTo switch graphics languages,
X it is necessary only to rerun {\tt transfig}, and then {\tt make}.
X{\tt Make} can also be used to keep the translated code up to date when
X figures change.
X
X\begin{figure}
X \hrule
X \vspace{2pt}
X \begin{center}
X \input{trans}
X \end{center}
X \hrule
X \caption{Fig Code Translations}
X \label{f:intro-trans}
X\end{figure}
X\vspace{2pt}
X
X\vfill
X\subsection{File Name Conventions}
X
XSuppose that a document is to include a set of figures which are stored in Fig
X code form.
XThese should be in files with the name suffix {\tt .fig}, for instance
X {\tt figure1.fig, figure2.fig,\ldots figuren.fig}.
XTransFig will create files {\tt figure1.tex, figure2.tex,\ldots figuren.tex}
X for {\verb|\input|} to the \LaTeX\ document,
X and in some cases will create files with other suffixes.
XAdditionally, TransFig creates a file named {\tt transfig.tex} which
X must be {\verb|\input|} at the start of the document.
X
X\vfill
X\subsection{Transfig \LaTeX\ Documents}
X
X\begin{figure}
X \hrule
X \vspace{2pt}
X \small
X \begin{center}
X \[ \begin{array}{lr}
X%
X \verb|\documentstyle{article}| & \\
X \verb|\input{transfig}| &
X ~~~\mbox{TransFig macro file}\\
X \verb|\begin{document}| & \\
X \hfill \vdots \hfill & \\
X%
X \verb|\begin{figure}| & \\
X ~~~\verb|\begin{center}| & \\
X ~~~\verb|\input{figurei}| &
X \mbox{i'th TransFig figure}\\
X%
X ~~~\verb| \end{center}| & \\
X \verb|\end{figure}| & \\
X \hfill \vdots \hfill & \\
X%
X \end{array} \]
X \end{center}
X \hrule
X \caption{Layout of a TransFig \LaTeX\ Document}
X \label{f:tex-format}
X\end{figure}
X\vspace{2pt}
X
XIn order to use TransFig, a \LaTeX\ file must follow the format shown in
X Figure~\ref{f:tex-format}.
XThe the file {\tt transfig.tex} must be {\verb|\input|} before any
X TransFig figure is encountered.
XAt the point where the $i$th figure {\tt figurei} is to be inserted,
X the file {\tt figurei.tex} is {\verb|\input|}.
X
X\vfill
X\pagebreak
X\subsection{Using TransFig}
X
XThe {\tt transfig} command has the form
X%
X\begin{center}
X {\tt transfig} [{\it option}~]\ldots
X ~[~[{\it control}~]\ldots ~{\it filename}~]\ldots
X\end{center}
X%
XWhere {\it option} is one of the following:
X%
X\begin{quote}
X\begin{description}
X\item[-L \it language]
X to translate into the specified {\it language}
X (default {\tt pictex}).
X\item[-M \it makefile]
X to name the output makefile {\it makefile}
X (default {\tt Makefile}).
X\item[-T \it texfile]
X to name the output \LaTeX\ macro file {\it texfile}
X (default {\tt transfig.tex}).
X\end{description}
X\end{quote}
X%
XThe {\it language} specifiers
X {\tt pictex, postscript, latex, (e)epic} and {tpic},
X indicate translation into \PicTeX\ macros, PostScript,
X \LaTeX\ picture environment, {\sc (e)}\EPIC\ macros,
X or \tpic\ specials, respectively.
XSee section~\ref{s:languages} for further details about these languages.
XThe special {\it language} specifier {\tt null} causes the figures to be
X replaced by empty boxes of the appropriate size.
X
XA {\it control} specifier sets a parameter which governs the translation
X of all files to its left in the argument list, until it is
X overridden.
XA {\it control} specifier must be one of the following:
X%
X\begin{quote}
X\begin{description}
X\item[-m \it magnification]
X to scale figures by {\it magnification} (default 1.0).
X\item[-f \it font]
X to set the default font family (default {\tt cmr}).
X\item[-s \it size]
X to set the default font size (default $12*\mbox{\it magnification}$).
X\end{description}
X\end{quote}
X
XEach file name specifies a Fig file, either with or without the {\tt .fig}
X suffix.
XTransFig creates a file called {\tt Makefile} to apply {\tt fig2dev} with
X the appropriate arguments to the named files,
X and creates an appropriate {\tt transfig.tex} file.
XThus, to create a {\tt Makefile} which will translate all figures in a
X directory to \LaTeX\ picture environment, with Computer Modern Bold as
X the default font family, the command would be
X%
X\begin{center}
X {\tt transfig -L latex -f cmb *.fig}
X\end{center}
X
XAfter running {\tt transfig}, simply run {\tt make} to create the
X appropriate \LaTeX\ files.
X{\tt Make} should be rerun whenever a Fig file is changed to recreate
X the corresponding \LaTeX\ file.
XTo change between graphics languages, simply run {\tt make clean} to
X remove the files created by {\tt transfig}, and then rerun
X {\tt transfig}.
X
XThe {\tt transfig} command can also be used to include figures described in
X Brian Kernighan's \PIC\ graphics language or in PostScript.
XThese graphics formats are distinguished by the file name suffix
X {\tt .pic} and {\tt .ps} respectively.
XTranslation from \PIC\ is accomplished by invoking {\tt pic2fig} program
X (see section \ref{s:pic2fig}).
X
X\subsection{Text in Figures and Portability}
X\label{s:portability}
X
XIn order to be translatable into different graphics languages, Fig code
X used in TransFig documents should use only those features which
X are supported by all of them.
XIn particular, some graphics languages support more sophisticated processing
X of text which is part of the figure than others.
X\PicTeX, for example, allows full use of \LaTeX\ commands in text strings,
X while PostScript does not.
X
XThe standard way to use text in TransFig figures is to use only
X straight text with no \LaTeX\ commands.
XThe text font is determined by the translator or the graphics language.
XA document which makes use of \LaTeX\ commands in text can still be
X created as a TransFig document,
X but it will not be portable.
X
XSimilarly, some graphics languages have controlling commands which are
X not understood by all.
XTo create a portable TransFig document, these commands should not be used.
XHowever, if portability is not an issue (as when developing a document),
X then they can be used at any point after the
X {\verb|\input{transfig}|} command.
X
X\vfill
X\pagebreak
X\section{Fig Code and Graphics Languages}
X\label{s:languages}
X
XTransFig's goal is to provide a framework for including graphics which
X maintains the portability of \LaTeX\ documents across
X printers and operating environments.
XThe central mechanism in TransFig is Fig code, a graphics description
X format which is produced by the Fig interactive graphics editor.
XIf this code is widely used as an intermediate form for figures,
X the builders of other graphics tools may be attracted
X to produce compatible output.
XThe reference guide in appendix~\ref{s:guide} describes Fig code in more
X detail.
X
X\subsection{Translations From Fig}
XTransFig currently translates Fig code into these graphics languages:
X \linebreak \PicTeX, PostScript, \LaTeX\ picture environment,
X and {\sc (e)}\EPIC.
XThe program which accomplishes these translations is {\tt fig2dev},
X which replaces the now-obsolete programs
X {\tt fig2tex}, {\tt fig2ps}, {\tt fig2latex}, and {\tt fig2epic}.
XThe {\tt transfig} command supports the translation of Fig code into
X \tpic\ specials (see below) using \tpic,
X which is not part of the TransFig package.
XEach language may be appropriate in different operating environments
X or for different applications.
XA short description of each language is given below:
X%
X\begin{quote}
X\begin{description}
X\item[\PicTeX]
X is a set of \TeX\ macros which implement simple
X graphics objects directly in \TeX.
X \PicTeX\ makes no use of pre- or post-processors; the \DVI\ files it
X generates are completely standard, and can be printed or
X previewed in any environment where \TeX\ is used.
X This result is achieved by using \TeX\ integer arithmetic to
X do all plotting calculations, and by drawing the figure
X using the period character as a ``brush''.
X As a result \PicTeX\ is quite slow and requires a large internal
X \TeX\ memory.
X
X\item[PostScript]
X (\PS)\, is a powerful graphics language which is gaining
X acceptance as a standard.
X In an environment where \DVI\ code is translated into \PS\ before
X being printed, it is usually possible to insert a
X separately generated PostScript file into a
X document, using the \TeX\ {\verb|\special|} command.
X However, the resulting \PS\ file can only be previewed using a
X \PS\ previewer, and must be printed on a \PS\ printer,
X such as the Apple LaserWriter.
X
X\item[\LaTeX]
X picture environment is a restricted graphics facility implemented
X within \LaTeX.
X It is a standard part of every version of \LaTeX, is processed
X quickly, and does not require a large internal \TeX\ memory.
X However, not every graphics object which can be described with
X Fig code can be drawn using the \LaTeX\ picture environment.
X Restrictions include a limited set of slopes at which lines can be
X drawn, and no ability to drawn splines.
X
X\item[\EPIC]
X is an enhanced version of the \LaTeX\ picture environment which
X removes many restrictions.
X It uses no facilities outside of those needed for the
X \LaTeX\ picture environment.
X
X\item[\EEPIC]
X is a further enhancement of \EPIC\ which uses \tpic\ specials
X to implement general graphics objects.
X It is subject to the same software requirements as \tpic.
X
X
X\item[\tpic]
X specials are a set of \verb|\special| commands which
X produce graphics instructions in the \DVI\ file
X produced by \TeX.
X However, the graphics in the resulting \DVI\ file can only be
X previewed or printed using software which understands
X these commands.
X
X\end{description}
X\end{quote}
X%
XWhen \LaTeX\ processes the file {\tt transfig.tex}, it will print the message
X \linebreak ``{\verb|TransFig: figures in |}{\it language}''
X indicating which graphics language is in use.
X
X\subsection{The Fig Graphics Editor}
X\label{s:fig}
XThe interpretation of Fig code was originally defined by
X the Fig graphics editor and the program {\tt f2p},
X which translates Fig code into the \PIC\ graphics language.
XHowever, this original definition has been extended,
X while maintaining the maximum possible degree of compatibility.
XThis extension is defined and implemented by the TransFig package,
X and thus is called \TFX,
X for TransFig eXtension.
XThe most complete implementation of \TFX\ is Fig 1.4.FS,
X a version of the Fig graphics editor which runs under SunView.
X
XAnother useful version of Fig is XFig,
X which runs under Version 11 of the X Windowing System.
XHowever, users of XFig should be aware of an incompatibility with TransFig.
XXFig version 2.0 uses an extension to Fig code (V2.0) which
X differs from \TFX\ in the definitions of the font and area fill fields.
XThe V2.0 definitions allow a richer set of values, which are specifically
X oriented towards output in PostScript.
XFor compatibility with XFig 2.0, TransFig supports translation of the V2.0
X format to PostScript only.
X
XPatchlevel 4 of XFig 2.0 introduced a compile-time option for compatibility
X with the \TFX\ format rather than V2.0.
XWith this option enabled, XFig 2.0 is compatible with all TransFig
X translations.
X
X\subsection{Other Fig Compatible Programs}
X\label{s:pic2fig}
X
XThe following programs use Fig code as a graphics description format,
X and thus are compatible with TransFig:
X%
X\begin{itemize}
X
X\item The numerical plotting program {\tt gnuplot} can optionally produce
X output in Fig code format.
X
X\item The \PIC-to-Fig translator {\tt pic2fig} translates \PIC,
X the language of Brian Kernighan's graphics preprocessor for Troff,
X into Fig code.
XThis allows users to create figures without employing a graphics editor.
X
X\item The Plot-to-Fig translator {\tt plot2fig} translates the Unix
X plot file format to Fig code.
X
X\item The XApGraph graphics editor is an experimental X-Windows application
X which can create and edit figures described in Fig code or in ApGraph,
X a new application level graphics language.
X
X\end{itemize}
X%
XThe Fig code produced by these programs can be viewed and edited
X using the Fig graphics editor.
X
X\vfill
X\pagebreak
X\section{Related Software}
X\label{s:software}
X
XSoftware availability is subject to change, and this list may not be
X completely up to date.
X
X\begin{description}
X
X\item[\EPIC]
X is an enhancement of the \LaTeX\ picture environment which
X removes many restrictions.
XIt uses only the facilities which implement the \LaTeX\ picture environment.
X\EPIC\ was developed by Sunil Podar at the State University of New York
X at Stonybrook, and is available via anonymous
X \FTP\ from {\tt CAYUGA.CS.ROCHESTER.EDU}.
X
X\item[\EEPIC]
X is a further enhancement of \EPIC\ which uses \tpic\ specials
X (see below) to implement general graphics objects.
XIt is subject to the same software requirements as \tpic,
X although there is an ``emulation package'' which will
X implement most of \EEPIC\ using the same facilities as \EPIC.
X\EEPIC\ was developed by Conrad Kwok at the University of California at Davis,
X and is available via anonymous \FTP\ from {\tt IRIS.UCDAVIS.EDU}.
X
X\item[Fig]
X is an interactive graphics editor in the style of MacDraw
X which runs under the Suntools/SunView windowing system.
XIt produces intermediate code which can be translated into
X a variety of graphics languages, including \PIC, Postscript,
X and \PicTeX.
X
XFig was developed by Supoj Sutanthavibul at the University of Texas at Austin,
X ({\tt supoj@SALLY.UTEXAS.EDU}), and is available via anonymous
X \FTP\ from {\tt SALLY}.
X
X\item[Fig 1.4.FS]
X is a version of Fig Version~1.4 Release~2 which implements various
X enhancements to the user interface,
X and also supports the \TFX\ extension to the definition of Fig code.
XFig~1.4.FS was developed by Frank Schmuck at Cornell University and
X is supported by Micah Beck ({\tt beck@CS.CORNELL.EDU}).
XIt is available via anonymous \FTP\ from {\tt SVAX.CS.CORNELL.EDU}.
X
X\item[Fig2dev]
X translates from Fig code to \PicTeX\ macros, Postscript,
X \LaTeX\ picture environment commands, {\sc (e)}\EPIC\ macros,
X and the \PIC\ graphics language.
XIt is part of the TransFig package, and supports the \TFX\ extension
X to Fig code.
X
X\item[Fig2tex, Fig2ps, Fig2latex, Fig2epic, Fig2pic]
X are Fig code translation programs which were distributed as
X part of earlier versions of the TransFig package.
XThey have been replaced by fig2dev (see above).
X
X\item[F2p, F2ps]
X are the original Fig code translation programs.
XThese programs are out of date and have been subsumed by fig2dev (see above).
X
X\item[GnuPlot]
X is a numerical plotting program which can optionally produce output
X in Fig code format.
XGnuPlot was developed by a group of people, including
X Thomas Williams and Colin Kelly of Pixar Corp.
X ({\tt pixar@INFO-GNUPLOT@SUN.COM}),
X and David F. Kotz of Duke University ({\tt dfk@DUKE.CS.DUKE.EDU}).
XGnuplot is available via anonymous \FTP\ from {\tt DUKE}.
X
X\item[\LaTeX]
X is a standard macro package used for describing documents in \TeX.
XPart of this package is the \LaTeX\ picture environment, a restricted
X graphics facility.
XThe capabilities of this facility are described in section~5.5 of
X {\em \LaTeX, A Document Preparation System} by Leslie Lamport.
X
X\item[Pic2fig]
X is a version of Brian Kernighan's \PIC\ graphics preprocessor
X for Troff.
XPic2fig, which is a modified form of \tpic\ (see below), has been altered
X to produce Fig code.
XFor Pic2fig distribution information, contact Micah Beck of
X Cornell University ({\tt beck@CS.CORNELL.EDU}).
X
X
X\item[\PicTeX]
X is a set of macros for describing graphics in \TeX\ documents.
X \PicTeX\ is implemented entirely within standard \TeX, and requires no
X pre- or post processing programs or special fonts.
XThe main problem in using \PicTeX\ is its slow operation (all calculations
X are done using \TeX's integer arithmetic) and large memory
X requirements.
XMany \PicTeX\ users have turned to C implementations of \TeX\ in order
X to obtain memory sizes larger than are possible using the standard
X Web/Pascal version.
X
X\PicTeX\ was developed by Michael Wichura at the University of
X Chicago ({\tt wichura@GALTON.UCHICAGO.EDU}), and is available via
X anonymous \FTP\ from {\tt A.CS.UIUC.EDU}.
XIt is also included as contributed software with the Unix \TeX\ distribution.
X
X\item [Plot2fig] translates figures from the Unix plot file format
X to Fig code.
XPlot2fig was developed by Richard Murphy of Rice University
X ({\tt rich@RICE.EDU}),
X and is available via anonymous \FTP\ from {\tt QED.RICE.EDU}.
X
X\item[\tpic]
X is a version of Brian Kernighan's \PIC\ graphics preprocessor
X for Troff.
X\tpic\ has been altered to produce \TeX\ {\verb|\special|} commands which
X are understood by some \DVI\ print drivers and previewers.
XFor information about distribution of \tpic, contact Tim Morgan of
X the University of California at Irvine ({\tt morgan@ICS.UCI.EDU}).
X
X\item[TransFig]
X was developed by Micah Beck at Cornell University
X \linebreak ({\tt beck@CS.CORNELL.EDU}), with major contributions
X by Frank Schmuck, now of IBM, and Conrad Kwok of UC Davis.
X It is available via anonymous \FTP\ from {\tt SVAX.CS.CORNELL.EDU}.
X
X\item[Xfig]
X is a version of the Fig graphics editor which can be compiled for
X either the Suntools or X Windows Version 11 windowing systems.
XXfig is part of the contributed software distributed with the X Windowing
X System, and can be obtained by anonymous FTP from
X {\tt EXPO.LCS.MIT.EDU}.
X
X\item[XApGraph]
X is an experimental X-Windows graphics editor which can create and
X edit figures described in Fig code or in ApGraph,
X a new application level graphics language.
XXApGraph is being developed by Alex Siegel at Cornell University
X ({\tt siegel@CS.CORNELL.EDU}), but is not currently available.
X
X\item[Xpic]
X is a graphical editor similar to Fig which runs under X Windows
X Version 11.
XXpic was developed by Mark Moraes at the University of Toronto
X ({\tt moraes@csri.toronto.edu}) and is available via anonymous
X \FTP\ from {\tt ai.toronto.edu}.
X
X\end{description}
X
X\raggedbottom
X\pagebreak
X
X\appendix
X
X\section{Fig Code Reference Guide}
X\label{s:guide}
XThis guide describes Fig code Version \version,
X an extension of the intermediate code produced by version 1.4
X of the Fig graphics editor.
XThis format is not compatible with the code produced by Fig version 1.3.
XA Fig \version code file has the following structure:
X%
X\begin{quote}
X\begin{tabbing}
X\verb|#FIG 1.4-TFX| \\
X\it global parameters \\
X\it object description \\
X\it object \= \it description \\
X\> $\vdots$
X\end{tabbing}
X\end{quote}
X%
X\subsection{Comment Lines}
XThe very first line is a comment line containing the version
X of the Fig format.
XPrograms which interpret Fig code verify compatibility by checking
X the first line for this comment.
XAll other lines which contain the character \verb|#| in the first column
X are treated as comments and are ignored.
X
X\subsection{Global Parameters}
XThe first non-comment line consists of two global parameters:
X%
X\begin{quote}
X\tt
Xfig\_resolution coordinate\_system
X\end{quote}
X%
XFields in a line of a Fig file are separated by blanks or tabs;
X newlines terminate object descriptions.
XThe fields of lines in Fig files are described throughout this
X guide by tables like the one below.
XThe fields must appear in the order given in the table.
X%
X\vspace{2pt}
X\begin{center}
X\begin{tabular}{|l|l|l|}
X\hline
XType & Field & Units (values) \\
X\hline
X\hline
Xint & {\tt fig\_resolution} & pixels/inch \\
X & & Fig value: 80 \\
X\hline
Xint & {\tt coordinate\_system} & 1: origin at lower left corner\\
X & & 2: origin at upper left corner\\
X & & Fig value: 2 \\
X\hline
X\end{tabular}
X\end{center}
X\vspace{2pt}
X
XThe {\em Type} column specifies the type of the field,
X and is either int(eger), float, or string.
XThe notation + following the type indicates that the values 0 or -1
X are interpreted as {\em default} values in this field.
XThe rightmost column of this table either defines the units in which
X the field is expressed, or lists the possible values which
X the field can take.
XThe notation {\tt DEFAULT} in this column indicates that no value other
X than the default values are allowed.
XIt is intended that future versions of Fig will define other values for
X these fields, but that the default values will remain legal,
X thus providing backward compatibility.
X
XThe basic unit of position in Fig files is the pixel.
XWhile figures in a Fig file are described at this resolution,
X the figure can be drawn at a higher or lower resolution.
XPixels are square, and so \verb|fig_resolution| represents position
X resolution in both the x and y dimensions.
X
XSome values are expressed as symbols and their numerical values are also listed.
XThese symbols are defined in the header file {\tt object.h}.
X
X\subsection{Object Descriptions}
XThe rest of the file contains objects descriptions,
X having one of six types:
X
X\begin{enumerate}
X\item Ellipse.
X\item Polyline, including Polygons and Boxes.
X\item Spline, including Closed/Open Control/Interpolated Splines.
X\item Text.
X\item Circular Arc.
X\item Compound object which is composed of one or more objects.
X\end{enumerate}
X
XThe following group of common fields appear in several object
X descriptions, and so the are described here, and later are
X simply referred to by the indicator {\it common fields}.
X%
X\vspace{2pt}
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
Xint & {\tt line\_style} & {\tt SOLID\_LINE} & 0 \\
X & & {\tt DASH\_LINE} & 1 \\
X & & {\tt DOTTED\_LINE} & 2 \\ \hline
X%
Xint & {\tt line\_thickness} & pixels & \\ \hline
X%
Xint + & {\tt color} & {\tt DEFAULT} & \\ \hline
X%
Xint & {\tt depth} & no units & \\ \hline
X%
Xint + & {\tt pen} & {\tt DEFAULT} & \\ \hline
X%
Xint + & {\tt area\_fill} & {\tt DEFAULT} & \\
X & & {\tt BLACK\_FILL} & 1 \\
X & & {\tt DARK\_GRAY\_FILL}& 2 \\
X & & {\tt MEDIUM\_GRAY\_FILL}& 3 \\
X & & {\tt LIGHT\_GRAY\_FILL}& 4 \\
X & & {\tt WHITE\_FILL} & 5 \\ \hline
X%
Xfloat & {\tt style\_val} & pixels & \\ \hline
X\end{tabular}
X\end{center}
X\vspace{4pt}
X%
XFor the dashed line style, the {\tt style\_val} specifies the length of a dash.
XFor dotted lines it indicates the gap between consecutive dots.
XDepth determines which filled objects will obscure other objects,
X with the objects of greater depth being obscured.
XMany graphics languages cannot fully implement area fill.
X
XArrow lines are used to describe optional arrows at the ends of
X Arc, Polyline, and Spline objects.
XIf an object has a forward arrow, then an arrow line describing it
X follows the object description.
XIf an object has a backward arrow, then an arrow line describing it
X follows the object description and the forward arrow description,
X if there is one.
X
XAn arrow line consists of the following fields
X%
X\vspace{4pt}
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xint + & {\tt arrow\_type} & {\tt DEFAULT} & \\ \hline
X%
Xint + & {\tt arrow\_style} & {\tt DEFAULT} & \\ \hline
X%
Xint + & {\tt arrow\_thickness}& {\tt DEFAULT} & \\ \hline
X%
Xint & {\tt arrow\_width} & pixels & \\ \hline
X%
Xint & {\tt arrow\_height} & pixels & \\ \hline
X\end{tabular}
X\end{center}
X\vspace{2pt}
X
XThe pen and color fields can only take the value DEFAULT.
XIt is intended that future extensions to Fig code will define
X other values for these fields.
XTheir intended use is discussed below:
X\begin{quote}
X\begin{description}
X
X\item[\tt pen] This will define the shape of
X pen used in drawing objects. It also includes
X the the stipple pattern for line filling.
X The default pen is a circular pen with black
X filling.
X
X\item[\tt color] The color used to draw an object and its area fill.
X
X\end{description}
X\end{quote}
X
X\subsubsection{Ellipse Objects}
X%
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
X
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xint & {\tt object\_code} & {\tt O\_ELLIPSE} & 1 \\ \hline
X%
Xint & {\tt sub\_type} & {\tt T\_ELLIPSE\_BY\_RAD} & 1 \\
X & & {\tt T\_ELLIPSE\_BY\_DIA} & 2 \\
X & & {\tt T\_CIRCLE\_BY\_RAD} & 3 \\
X & & {\tt T\_CIRCLE\_BY\_DIA} & 4 \\ \hline
X%
X\multicolumn{4}{c}{\it common fields} \\ \hline
X%
Xint & {\tt direction} & 1 & \\ \hline
X%
Xfloat & {\tt angle} & radians & \\ \hline
X%
Xint & {\tt center\_x},
X {\tt center\_y} & pixels & \\ \hline
X%
Xint & {\tt radius\_x},
X {\tt radius\_y} & pixels & \\ \hline
X%
Xint & {\tt start\_x},
X {\tt start\_y} & pixels & \\ \hline
X%
Xint & {\tt end\_x},
X {\tt end\_y} & pixels & \\ \hline
X\end{tabular}
X\end{center}
X%
XThe Ellipse object describes an ellipse (or circle) centered at the point
X \linebreak ({\tt center\_x}, {\tt center\_y})
X with radii {\tt radius\_x} and {\tt radius\_y}, and whose x-axis
X is rotated by {\tt angle} from the horizontal.
XIf the object describes a circle, then {\tt radius\_x} and {\tt radius\_y}
X must be equal.
X
XThe fields {\tt start\_x, start\_y, end\_x and end\_y} are used only by
X Fig, and are not used in drawing the object.
XIf the ellipse is specified by radius, then $({\tt start\_x}, {\tt start\_y})$
X is $({\tt center\_x}, {\tt center\_y})$,
X and $({\tt end\_x}, {\tt end\_y})$ is a corner of a box which
X bounds the ellipse.
XIf the ellipse is specified by diameter, then $({\tt start\_x}, {\tt start\_y})$
X and $({\tt end\_x}, {\tt end\_y})$ are the two corners of the box
X which bound the ellipse.
X
X\subsubsection{Polyline Objects}
X%
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xint & {\tt object\_code} & {\tt O\_POLYLINE} & 2 \\ \hline
X%
Xint & {\tt sub\_type} & {\tt T\_POLYLINE} & 1 \\
X & & {\tt T\_BOX} & 2 \\
X & & {\tt T\_POLYGON} & 3 \\ \hline
X%
X\multicolumn{4}{c}{\it common fields} \\ \hline
X%
Xint & {\tt forward\_arrow}, & 0: no arrow & \\
X & {\tt backward\_arrow} & 1: arrow & \\ \hline
X\end{tabular}
X\end{center}
X%
XThe Polyline object description has an addition {\em points line} following
X any arrow lines.
XThe line consists of a sequence of coordinate pairs followed by the
X pair 9999 9999 which marks the end of the line.
X%
X\begin{quote}
X$
X {\tt x}_1 ~{\tt y}_1 ~{\tt x}_2 ~{\tt y}_2 \ldots
X ~{\tt x}_n ~{\tt y}_n ~9999 ~9999
X$
X\end{quote}
X%
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xint & ${\tt x}_i, {\tt y}_i$& pixels & \\ \hline
X\end{tabular}
X\end{center}
X
XThe Polyline object describes a piecewise linear curve starting at
X the point $({\tt x}_1, {\tt y}_1)$ and passing through
X each point ${(\tt x}_i, {\tt y}_i)$ for $i = 2 \ldots n$.
XIf {\tt sub\_type} is {\tt T\_BOX} or {\tt T\_POLYGON} then
X $({\tt x}_1, {\tt y}_1)$ and $({\tt x}_n, {\tt y}_n)$ must
X be identical.
XIf {\tt sub\_type} is {\tt T\_BOX}, then the line segments must all be
X a vertically oriented rectangle.
X
X\subsubsection{Spline Objects}
X%
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xint & {\tt object\_code} & {\tt O\_SPLINE} & 3 \\ \hline
X%
Xint & {\tt sub\_type} & {\tt T\_OPEN\_NORMAL} & 0 \\
X & & {\tt T\_CLOSED\_NORMAL} & 1 \\
X & & {\tt T\_OPEN\_INTERPOLATED} & 2 \\
X & & {\tt T\_CLOSED\_INTERPOLATED} & 3 \\ \hline
X%
X\multicolumn{4}{c}{\it common fields} \\ \hline
X%
Xint & {\tt forward\_arrow}, & 0: no arrow & \\
X & {\tt backward\_arrow} & 1: arrow & \\ \hline
X\end{tabular}
X\end{center}
X%
XThe Spline object description has a {\em points line} following
X any arrow line which has the same format as described above
X for the Polyline object description.
XIf the {\tt sub\_type} of the spline is {\tt T\_OPEN\_INTERPOLATED} or
X \linebreak {\tt T\_CLOSED\_INTERPOLATED}, then an additional
X {\em control points line} follows the points line.
XThe line consists of a sequence of coordinate pairs, two coordinate pairs
X for each point in the points line.
X%
X\begin{quote}
X$
X {\tt lx}_1 ~{\tt ly}_1 ~{\tt rx}_1 ~{\tt ry}_1
X ~{\tt lx}_2 ~{\tt ly}_2 ~{\tt rx}_2 ~{\tt ry}_2
X \ldots
X ~{\tt lx}_n ~{\tt ly}_n ~{\tt rx}_n ~{\tt ry}_n
X$
X\end{quote}
X%
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xfloat & ${\tt lx}_i,{\tt ly}_i,
X {\tt rx}_i,{\tt ry}_i$& pixels & \\ \hline
X\end{tabular}
X\end{center}
X%
XThe interpretation of Spline objects is more complex than of other
X object descriptions, and is discussed in section~\ref{s:splines}.
X
X\subsubsection{Text Objects}
X
X\begin{center}
X\begin{tabular}{|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X\tt
Xint & {\tt object\_type} & {\tt O\_TEXT} & 4 \\ \hline
X%
Xint & {\tt sub\_type} & {\tt T\_LEFT\_JUSTIFIED} & 0 \\
X & & {\tt T\_CENTER\_JUSTIFIED} & 1 \\
X & & {\tt T\_RIGHT\_JUSTIFIED} & 2 \\
X \hline
X%
Xint + & {\tt font} & {\tt DEFAULT} & \\
X & & {\tt ROMAN} & 1 \\
X & & {\tt BOLD} & 2 \\
X & & {\tt ITALICS} & 3 \\
X & & {\tt MODERN} & 4 \\
X & & {\tt TYPEWRITER} & 5 \\ \hline
X%
Xint + & {\tt font\_size} & points & \\ \hline
X%
Xint + & {\tt pen} & {\tt DEFAULT} & \\ \hline
X%
Xint + & {\tt color} & {\tt DEFAULT} & \\ \hline
X%
Xint & {\tt depth} & no units & \\ \hline
X%
Xfloat & {\tt angle} & radians & \\ \hline
X%
Xint + & {\tt font\_style} & {\tt DEFAULT} & \\ \hline
X%
Xint & {\tt height, length} & pixels & \\ \hline
X%
Xint & {\tt x, y} & pixels & \\ \hline
X%
Xstring & string & & \\ \hline
X\end{tabular}
X\end{center}
X%
XThe positioning of the string is specified by the {\tt sub\_type}.
XThe values {\tt T\_LEFT\_JUSTIFIED}, {\tt T\_CENTER\_JUSTIFIED},
X and {\tt T\_RIGHT\_JUSTIFIED} specify that
X $({\tt x}, {\tt y})$ is the left end, center and right end
X of the baseline, respectively.
XThe {\tt height} and {\tt length} fields specify the box that the
X text fits into.
XThese specifications are accurate only for the fonts used by Fig.
X
XThe {\tt string} field is an ascii string terminated by the character
X \verb|'\01'|.
XThis terminating character is not a part of the string.
XNote that the string may contain the new-line character \verb|'\n'|.
X
X\subsubsection{Arc Objects}
X%
X\begin{center}
X\begin{tabular} {|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X%
Xint & {\tt object\_code} & {\tt O\_ARC} & 5 \\ \hline
X%
Xint & {\tt sub\_type} & {\tt T\_3\_POINT\_ARC}& 1 \\ \hline
X%
X\multicolumn{4}{c}{\it common fields} \\ \hline
X%
Xint & {\tt direction} & 0: clockwise & \\
X & & 1: counter & \\ \hline
X%
Xint & {\tt forward\_arrow}, & 0: no arrow & \\
X & {\tt backward\_arrow} & 1: arrow & \\ \hline
X%
Xfloat & {\tt center\_x},
X {\tt center\_y} & pixels & \\ \hline
X%
Xint & ${\tt x}_1, {\tt y}_1,
X {\tt x}_2, {\tt y}_2,
X {\tt x}_3, {\tt y}_3$& pixels & \\ \hline
X\end{tabular}
X\end{center}
X%
XThe Arc object describes a circular arc centered at the point
X \linebreak $({\tt center\_x}, {\tt center\_y})$, starting at
X $({\tt x}_1, {\tt y}_1)$, passing through $({\tt x}_2, {\tt y}_2)$,
X and ending at $({\tt x}_3, {\tt y}_3)$.
XIt is drawn either clockwise of counter-clockwise as specified by
X {\tt direction}.
XNote that this description is quite overdetermined, as the center and
X direction of the arc can be deduced from the three points
X of the arc which are specified.
X
X\subsubsection{Compound Objects}
X
X\begin{center}
X\begin{tabular}{|l|l|ll|}
X\hline
XType & Field & Units (values) & \\ \hline
X\hline
X\tt
Xint & {\tt object\_type} & {\tt O\_COMPOUND} & 6 \\ \hline
X%
Xint & {\tt upperright\_corner\_x} & pixels & \\
Xint & {\tt upperright\_corner\_y} & & \\
Xint & {\tt lowerleft\_corner\_x} & & \\
Xint & {\tt lowerleft\_corner\_y} & & \\ \hline
X\end{tabular}
X\end{center}
X
XThe Compound object description describes a compound object
X bounded by the rectangle determined by the points
X%
X\begin{quote}
X\[ \begin{array}{l}
X ({\tt upperright\_corner\_x}, {\tt upperright\_corner\_y}) \\
X ({\tt lowerleft\_corner\_x}, {\tt lowerleft\_corner\_y})
X\end{array} \]
X\end{quote}
X%
XIt consists of all the objects following it until an object whose
X {\tt object\_type} field is {\tt O\_END\_COMPOUND} (-6) is encountered.
XCompound objects may be nested.
X
X\subsection{Splines}
X\label{s:splines}
X
XSpecifying the interpretation of a Spline object description is more problematic
X than other graphics objects.
XA graphics object description can be viewed as having two parts:
X an abstract description of the locus of points which
X make up the object; and a set of appearance parameters
X which specify how the abstract object is to be represented.
XFor example, a circular arc has a very precise and well understood abstract
X definition, independent of the width of the line used to
X draw it.
XUnfortunately, the abstract specification of splines is more complex.
XThe following descriptions come at second hand; the author of this
X guide is not versed in spline algorithms, and so
X may have garbled them.
XHopefully, they will give the knowledgeable reader some idea of the
X intended meaning of Spline objects.
X
XFig splines come in two major varieties: B-splines and Interpolated splines.
XEach of these is available in open or closed versions.
XIf the {\tt sub\_type} field has the values {\tt T\_OPEN\_NORMAL}
X or {\tt T\_CLOSED\_NORMAL} then it describes a B-spline.
XIn these cases, the points line which follows contains the
X {\tt control points} for the spline.
XThe spline does not actually pass through these points, but they determine
X where it will pass, which is generally quite close to the control
X points.
XB-splines are quite smooth.
X
XIf the {\tt sub\_type} field has the values {\tt T\_OPEN\_INTERPOLATED} or
X \linebreak {\tt T\_CLOSED\_INTERPOLATED} then it describes an
X interpolated spline.
XIn these cases, the points line which follows contains the
X {\em interpolation points} through which the spline will pass.
XIn addition, a {\em control points} line follows the points line,
X which specifies two control points $({\tt lx}_i, {\tt ly}_i)$ and
X $({\tt rx}_i, {\tt ry}_i)$ for each interpolation point.
XThe {\tt i}'th section of the interpolated spline is drawn using the
X Bezier cubic with the four points
X $({\tt x}_i, {\tt y}_i)$, \linebreak $({\tt rx}_i, {\tt rx}_i)$,
X $({\tt lx}_{i+1}, {\tt ly}_{i+1})$,
X and $({\tt x}_{i+1}, {\tt y}_{i+1})$.
XInterpolated splines are not as smooth as B-splines.
X
XFor either type of closed splines, the first and last points
Xon the point line
X $({\tt x}_1, {\tt y}_1)$ and $({\tt x}_n, {\tt y}_n)$
X are identical.
XFor closed interpolated splines, the last pair of control points on the
Xcontrol points line,
X $({\tt lx}_n, {\tt ly}_n)$ and $({\tt rx}_n, {\tt ry}_n)$
X are the same as
X $({\tt lx}_1, {\tt ly}_1)$ and $({\tt rx}_1, {\tt ry}_1)$
X respectively.
X
X\end{document}
END_OF_FILE
if test 36693 -ne `wc -c <'transfig/doc/manual/manual.tex'`; then
echo shar: \"'transfig/doc/manual/manual.tex'\" unpacked with wrong size!
fi
# end of 'transfig/doc/manual/manual.tex'
fi
echo shar: End of archive 6 \(of 6\).
cp /dev/null ark6isdone
MISSING=""
for I in 1 2 3 4 5 6 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 6 archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
--
Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.
Use a domain-based address or give alternate paths, or you may lose out.