diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/psfig/psfig-doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/psfig/psfig-doc.tex | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/psfig/psfig-doc.tex b/Master/texmf-dist/doc/generic/psfig/psfig-doc.tex new file mode 100644 index 00000000000..0aec9e81218 --- /dev/null +++ b/Master/texmf-dist/doc/generic/psfig/psfig-doc.tex @@ -0,0 +1,292 @@ +%\documentstyle[psfig]{article} +\documentstyle{article} +\input ../psfig.sty +\begin{document} +\pssilent +\psfigurepath{figs} +\def\Ps{Post\-Script} +% +\title{Psfig/\TeX\ 1.10 Users Guide} +\author{Trevor Darrell \\ {\it trevor@media.mit.edu}} +\date{\ } +\maketitle + +\section{Introduction} +Psfig/\TeX\ is a macro package for \TeX\ that facilitates the +inclusion of \Ps\ figures into \TeX\ documents. With the +help of a compatible postprocessor, +\footnote{The {\tt dvips} program developed by T. Rokicki +has full psfig support; it is available via anonymous FTP from {\tt labrea.stanford.edu}. OzTeX also supports psfig and is available from various ftp sites. Psfig is available from {\tt whitechapel.media.mit.edu}.} +\Ps\ figures are automatically +scaled and positioned on the page, and the proper amount of space is +reserved. +Custom characters such as +`\psfig{figure=pretzel.ps,height=8pt,silent=}' and +`\psfig{figure=cm.ps,height=8pt,silent=}' +may be created and used freely throughout a document, or figures can +be presented as traditional broken-out displays: +\par +\hbox{ +\hspace{.3in} +\vbox{\psfig{figure=zip.ps}\vspace{.5in}} +\psfig{figure=piechart.ps,height=1.5in} +\vbox{\psfig{figure=starlines.ps}\vspace{.6in}} +} + +\section{Simple figures} +To include a \Ps\ figure with psfig, include the psfig style at the top +of your document: +\begin{quote} +{\tt\verb+\documentstyle[psfig,...]{article}+} +\end{quote} +and then, when you wish to include a figure, invoke the macro +\begin{quote} +{\tt\verb+\+psfig\{figure={\it input}\}} +\end{quote} +where {\it input} is the name of a \Ps\ file. Psfig will +automatically position the figure at the current point on the page, +and reserve the proper amount of space in \TeX\ so that it doesn't +block any other objects on the page. For example, if we have a file +called `piechart.ps' which contains the \Ps\ code to draw the chart in +the introduction, we could use the commands +\begin{quote} +\tt +\verb+\+par \\ +\verb+\+centerline\{\verb+\+psfig\{figure=piechart.ps\}\} \\ +\verb+\+par +\end{quote} +to include it as a centered paragraph. +Since no mention of size was made in the above example, psfig draws the figure +at its natural size (as if it was printed directly on +a \Ps\ printer.) The pie's natural size is several inches across, which +is a little large; the pie in the introduction was produced with: +\begin{quote} +\tt\verb+\+centerline\{\verb+\+psfig\{figure=piechart.ps,height=1.5in\}\} +\end{quote} +The {\tt height} option specifies how tall the figure should be on the +page. Since no {\tt width} was specified, the figure was scaled +equally in both dimensions. (This will also happen with a {\tt width} +but no {\tt height} option.) By listing both a {\tt height} and {\tt +width}, figures can be scaled disproportionately, with interesting +results: +\par +\centerline{\hbox{ +\psfig{figure=rosette.ps,height=.8in,width=.15in} +\psfig{figure=rosette.ps,height=.8in,width=.35in} +\psfig{figure=rosette.ps,height=.8in} +\psfig{figure=rosette.ps,height=.8in,width=1.2in} +\psfig{figure=rosette.ps,height=.8in,width=1.5in} +}} +\par +\noindent This figure was produced with: +\begin{quote} +\tt\verb+\+centerline\{\verb+\+hbox\{ \\ +\verb+\+psfig\{figure=rosette.ps,height=.8in,width=.15in\}\\ +\verb+\+psfig\{figure=rosette.ps,height=.8in,width=.35in\}\\ +\verb+\+psfig\{figure=rosette.ps,height=.8in\} \\ +\verb+\+psfig\{figure=rosette.ps,height=.8in,width=1.2in\}\\ +\verb+\+psfig\{figure=rosette.ps,height=.8in,width=1.5in\}\\ +\}\} +\end{quote} +The \verb+\psfig+ macro is (unfortunately) sensitive to whitespace, and will be +confused by any extra spaces or newlines in its argument. +\section{Sources of figures} +\hbox{ +\vbox{\psfig{figure=trevor.ps,height=1in}} +\hspace{.15in} +\vbox{\parbox{3.5in} {Any program that produces \Ps\ as output +can be used for psfig figures +as long as it adheres to the bounding box comment convention (see below). +For instance, the bitmap image +of the author was included as a figure at left.}\vspace{.2in}}} + +Since the Macintosh drawing applications produce \Ps, they can be used +to create figures. However, the \Ps produced by most Macintosh +applications is often not well suited to be included directly as +aBpsfig figure, unless it is saved as an ``EPSF compliant'' file. If +the file is not EPSF compliant then the postscript may have to be +edited before being used as an included figure. + +\section{Draft figures and Silent mode} +\begin{figure} +\centerline{ +\psfig{figure=rosette.ps,height=2in} +\psdraft +\psfig{figure=rosette.ps,height=2in} +\psfull +} +\vspace{.25in} +\centerline{Figure 2: The rosette.ps figure, in non-draft and draft mode} +\end{figure} +Normally, psfig will print advisory messages to remind you that it is +including figures as TeX processes a document. This behavior can +be disabled with {\tt \verb+\+pssilent}, and re-enabled with +{\tt \verb+\+psnoisy}. +\par +Some \Ps\ figures can take quite a long time to transmit and print; +for these figures a draft mode is available to speed printing of draft +versions of the document. A figure printed in draft mode will appear +as an outlined box (Figure 2). The macro {\tt +\verb+\+psdraft} will switch into draft mode, and all subsequent psfig +macros will produce draft figures until reaching the macro {\tt +\verb+\+psfull}, which switches out of draft mode. + +No {\tt +\verb+\+special} commands are used in draft mode, so a draft document +can be previewed using any Dvi viewer. Psfig uses the \LaTeX\ {\tt +\verb+\+fbox} command to produce the draft box; thus draft boxes will +not work in plain \TeX. The printing of boxes in draft mode can be +disabled/enabled with {\tt +\verb+\+psnodraftbox} and {\tt +\verb+\+psdraftbox}. + +\section{Bounding boxes} +To properly translate and scale a figure psfig must know its `natural' +position on the page; this information is present +in what is called the {\it bounding box} of a \Ps\ program. The +bounding box is an outer limit to the marks created by a program, +and is specified as four coordinates of a rectangle: the lower-left $x$ coordinate +(bbllx), the lower-left $y$ coordinate (bblly), the upper-right +$x$ coordinate (bburx), and the upper-right $y$ coordinate (bbury). +Adobe has defined a convention whereby the bounding box of a program +is contained in a `bounding box comment'. +\footnote{See `Appendix J: \Ps\ File Structuring Conventions' in +{\it The \Ps\ Language Reference Manual}} +This comment, which must be present in any file to be used as a psfig figure, +is a line of the form +\begin{quote} +\tt \verb+%%+BoundingBox: \it bbllx bblly bburx bbury +\end{quote} +All values are in \Ps\ points, relative to the {\it default} +transformation matrix. The only mandatory \Ps\ convention is +that the first line of the file should begin with the characters +`\verb+%+!' (a `\verb+%+' begins a comment in \Ps.) A good place for the +bounding box comment is as the second line of the file. +\par +If a bounding box comment is present in the figure file, psfig will +extract its values. The bounding box values may instead be specified +directly in the {\tt \verb+\+psfig} argument, using clauses of the +form {\tt bbllx=\it bbllx},{\tt bblly=\it bblly},..., in which case +the figure file is not searched for the bounding box. + +\section{Reserved size} +\par +\psfig{figure=box.ps,rheight=0bp,rwidth=0bp,height=1.25in,width=\textwidth,silent=} +\par +There are two sizes associated with each psfig figure: the size +at which it is to be printed on the page +and the size it reserves in \TeX. This latter size is appropriately +termed the {\it reserved size}, and is expressed as clauses of the form +``{\tt rheight={\it dimen}}'' +and ``{\tt rwidth={\it dimen}}''. If omitted, the reserved size defaults +to the real size. Some special effects need to be transparent +to \TeX\ and thus have a zero reserved size, such as the grey +box enclosing +this paragraph. + +\section{Clipping} +Normally a \Ps\ program can be expected to not mark the page +outside its bounding box. If this is not the case, or if you +want to specify a bounding box so as to isolate part of a larger figure, +there is an option that sets the \Ps\ clip path so that +no marks will show up outside the declared bounding box. Currently +this is invoked by adding a clause of the form ``{\tt clip=}''. +Here a slice has been taken out of the pie chart in the example by +specifying a smaller bounding box and adding the clip option. +\par +\centerline{\protect\fbox{\psfig{figure=piechart.ps,height=2in,bbllx=306bp,bblly=396bp,bburx=486bp,bbury=546bp,clip=}}} +\centerline{A piece of the pie.} +\vspace{.2in} +\par +Some \Ps\ programs use the clipping path to position their output on +the page; if a figure is being drawn at its natural size and position +despite psfig commands to the contrary, it may need the clip option. + +\newpage +\section{Rotating figures} +Figures can be rotated by psfig using the {\tt angle={\it degrees}} +clause. For example, here is the rosette and its 90 degree rotation: + +\centerline{\hbox{ +\psfig{figure=rosette.ps,height=1.0in} +\psfig{figure=rosette.ps,height=1.0in,angle=90} +}} + +By default psfig scales the figure so that its rotated bounding box +fits within the desired size. This can lead to counterintuitive results +when rotating to angles which are not multiples of 90 degrees. Here +is the rosette rotated to 0,20,40, and 60 degrees. + +\centerline{\hbox{ +\psfig{figure=rosette.ps,height=1.0in} +\psfig{figure=rosette.ps,height=1.0in,angle=20} +\psfig{figure=rosette.ps,height=1.0in,angle=40} +\psfig{figure=rosette.ps,height=1.0in,angle=60} +}} + +With autoscaling, some rotated figures come out smaller because the +diagonal of their bounding box is of course longer than their height +or width alone. This behavior can be disabled with {\tt +\verb+\+psscalefirst}, and re-enabled with {\tt +\verb+\+psrotatefirst}. With {\tt \verb+\+psscalefirst} a new +height and width is computed after the bounding box; +the previous figure would now look like: + +\psscalefirst +\centerline{\hbox{ +\psfig{figure=rosette.ps,height=1.0in} +\psfig{figure=rosette.ps,height=1.0in,angle=20} +\psfig{figure=rosette.ps,height=1.0in,angle=40} +\psfig{figure=rosette.ps,height=1.0in,angle=60} +}} + +While the rotated figures will all come out at the same +size their reserved sizes will be different, thus +they may not be aligned correctly. + +\section{Compressed Figures} +Psfig allows the inclusion of compressed \Ps files when using +the {\tt dvips} dvi processor. +The shell script {\tt pscompress} is used to compress figures, and +produces two files: {\it filename}{\tt .bb} and {\it filename}{\tt .Z}. +The first file contains the bounding box comment only, while the second +file contains the actual compressed PostScript file. Usage: +\begin{quote} +\tt \verb+%+ pscompress \it filename +\end{quote} +When psfig searches for a figure, if it fails to find +{\it filename}, it then searches for {\it filename}{\tt .bb}. +If that file exists, it is used for bounding box processing, +and a command to decompress and include the file {\it filename}{\tt .Z} +is issued to dvips. + +\section{Figure search path} + +Psfig first searches in the current directory for a figure (or +in the specified directory if given an absolute path). If it fails +to find the figure in the current directory, it optionally searches +a search path of figure directories to see if the figure is +present. To specify the figure search path, use +\begin{quote} +\tt \verb+\+psfigurepath\verb+{+\it dir1 \tt :\it dir2\tt :\it ...\tt :\it dirn\tt\verb+}+ +\end{quote} +where {\it dir1...dirn} are the directories figures are to be found in. +\newpage +\section{Acknowledgements} +\par +This work was done while the author was with the Department of +Computer and Information Science, University of Pennsylvania. Ned +Batchelder co-developed the original {\it troff} version of this +program with the author, and was responsible for much of the overall +design. For more detailed information on the original version of \Ps\ +see {\it Psfig -- A Ditroff Preprocessor for PostScript Figures} in +the USENIX 87 proceedings, or {\it Bringing troff up to speed} in the +July 1987 issue of Unix Review. + +Greg Hager provided the initial pure-\TeX\ implementation of psfig. +J. Daniel Smith of Schlumberger CAD/CAM implemented the rotation +feature and improved the file scanning routines, using certain code +fragments from Tom Rokicki's dvips program. +\par +\end{document} + |