diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/psfig/psfig.man')
-rw-r--r-- | Master/texmf-dist/doc/generic/psfig/psfig.man | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/psfig/psfig.man b/Master/texmf-dist/doc/generic/psfig/psfig.man new file mode 100644 index 00000000000..b6388528674 --- /dev/null +++ b/Master/texmf-dist/doc/generic/psfig/psfig.man @@ -0,0 +1,261 @@ +.TH Psfig/TeX 1 +.SH NAME +Psfig/TeX (1.10) \- PostScript figures in TeX +.SH SYNTAX +\\\fBinput psfig\fP +.SH DESCRIPTION +.B Psfig/TeX +is a macro package for TeX, as well as LaTeX, that facilitates the +inclusion of PostScript figures into (La)TeX documents. +With the help of a compatible postprocessor, PostScript figures are +automatically scaled and positioned on the page, and the proper amount +of space is reserved. +Figures can be presented as traditional broken-out displays, +and Custom characters may be created and used freely throughout a document. +.PP +The \fBdvips\fP program developed by Tomas Rokicki has full +\fBpsfig\fP support. The \fBOzTeX\fP package has support for +all \fBpsfig\fp functions except compressed figures. +.PP +.SH USAGE +To include a figure with \fBpsfig\fP, include the \fBpsfig\fP style at +the top of your document. +In LaTeX: ``\\\fBdocumentstyle\fP[psfig,...]{article}''; in TeX: +``\\\fBinput\fP psfig''. +Then invoke the macro ``\\\fBpsfig\fP{figure=\fIfilename\fP}'', where +\fIfilename\fP is the name of a PostScript file. +.B Psfig +will automatically position the figure at the current +point on the page, and reserve the proper amount of space. +.PP +.SH OPTIONS +Options may be specified in the form +``\\\fBpsfig\fP{figure=\fIfilename\fP,\fIoption\fP=\fIvalue\fP,\fIoption\fP=\fIvalue\fP,...}''; +recognized options include \fBheight\fP, \fBwidth\fP, \fBrheight\fP, +\fBrwidth\fP, \fBclip\fP, and \fBangle\fP. +.IP height 9 +The ``\fBheight\fP=\fIdimen\fP'' option specifies how tall the +figure should be on the page. +When no \fBwidth\fP is specified, the figure is scaled equally +in both dimensions. +.IP width +The ``\fBwidth\fP=\fIdimen\fP'' option specifies how wide the +figure should be on the page. +When no \fBheigth\fP is specified, the figure is scaled equally +in both dimensions. +.IP +If no \fBheight\fP or \fBwidth\fP option is given, the figure's +`natural' size will be used. +By listing both a \fBheight\fP and \fBwidth\fP, figures can be scaled +disproportionately. +.IP rheight +There are two sizes associated with each \fBpsfig\fP 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 reserved size, and is +expressed as an option of the form ``\fBrheight\fP=\fIdimen\fP'', +to reserve a vertical size of \fIdimen\fP. +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 a grey box enclosing a paragraph. +.IP rwidth +To reserve a width in TeX, the ``\fBrwidth\fP=\fIdimen\fP'' +option is used. +.IP clip +The ``\fBclip\fP=t'' option sets the PostScript clipping path +so that no marks will show up outside the declared bounding box. +This option allows the user to isolate part of a larger figure, +by specifying a new bounding box: +``\\\fBpsfig\fP{figure=figs/piechart.ps,height=2in,bbllx=306bp,% +bblly=396bp,bburx=486bp,bbury=546bp,clip=}'' +.IP angle +Figures can be rotated by \fBpsfig\fP using the ``\fBangle\fP=\fIdegrees\fP'' +option. +Example: +``\\\fBpsfig\fP{figure=figs/rosette.ps,height=1.0in,angle=90}''. +.PP +.SH AUTOSCALING +With autoscaling, some rotated figures come out smaller because the +diagonal of their bounding box is longer than their \fBheight\fP +or \fBwidth\fP alone. +This behavior can be disabled with \\\fBpsscalefirst\fP, and re-enabled +with \\\fBpsrotatefirst\fP. +With \\\fBpsscalefirst\fP a new \fBheight\fP and \fBwidth\fP are +computed after the bounding box. +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. +.PP +.SH SOURCES OF FIGURES +Any PostScript program can be used as a +\fBpsfig\fP figure, as long as it adheres to the +Encapsulated PostScript Format (EPSF), which +dictates a set of forbidden operators and a comment +structuring convention. \fBPsfig\fP +is actually less restrictive than the EPSF requirements; it can handle +some of the "non-compliant" postscript operators, and the only +required comment is the Bounding Box comment (see below). +.PP +.SH BOUNDING BOXES +To properly translate and scale a figure \fBpsfig\fP must know +its `natural' position on the page; this information is present +in the `bounding box comment' of a PostScript program. +This is a line of the form +``%%BoundingBox: \fIbbllx bblly bburx bbury\fP'' in the header of +the file. +.PP +The bounding box specifies four coordinates of a rectangle that +defines the outermost edges of the PostScript figure: the lower-left +\fIx\fP coordinate (\fIbbllx\fP), the lower-left \fIy\fP coordinate +(\fIbblly\fP), the upper-right \fIx\fP coordinate (\fIbburx\fP), and +the upper-right \fIy\fP coordinate (\fIbbury\fP). +This rectangle must be present in any file to be used as a +\fBpsfig\fP figure. +Most modern graphics packages produce (encapsulated) PostScript +files which contain a ``%%BoundingBox:'' comment line in the header. +All \fIbb...\fP values are in points, relative to the default +transformation matrix. +.PP +.SH MISSING BOUNDING BOX +When no bounding box comment line is present in your PostScript file, +you can edit one in. +The only mandatory PostScript convention is that the first line of +the file should begin with the characters `%!'. +A good place for the bounding box comment is the second line of +the file. +.PP +The bounding box values may also be specified directly in the +\\\fBpsfig\fP argument, using clauses of the form +``bbllx=\fIbbllx\fP,bblly=\fIbblly\fP,...'', in which case +the figure file is not searched for the bounding box. +.PP +To control the amount of white space around a figure in a (La)TeX +document, it may be necessary to experiment with the bounding box +parameters \fIbb...\fP, also in cases where the bounding box is +provided by the plot or graphics package. +.PP +.SH DRAFT FIGURES +Some PostScript figures 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 empty box. +The macro \\\fBpsdraft\fP will switch into draft mode, and all +subsequent \fBpsfig\fP macros will produce draft figures until reaching +the macro \\\fBpsfull\fP, which switches out of draft mode. +.PP +No \\\fBspecial\fP commands are used in draft mode, so a draft document +can be previewed using \fIany\fP DVI viewer. +The printing of boxes in draft mode can be disabled/enabled with +\\\fBpsnodraftbox\fP and \\\fBpsdraftbox\fP. +.PP +.SH SILENT MODE +Normally, \fBpsfig\fP will print advisory messages to remind you that it is +including figures as (La)TeX processes a document. This behavior can +be disabled with \\\fBpssilent\fP, and re-enabled with \\\fBpsnoisy\fP. +.PP +.SH COMPRESSED POSTSCRIPT FILES +As off version 1.9, \fBpsfig\fP allows the inclusion of compressed +PostScript files (when using \fBdvips\fP). +.PP +To compress PostScript files, the shell script \fBpscompress\fP is used. +\fBPscompress\fP produces two files: \fIfilename\fP.bb and \fIfilename\fP.Z. +The first file contains the bounding box comment only, while the second +file contains the actual compressed PostScript file. +Usage: ``% \fBpscompress\fP \fIfilename\fP''. +.PP +When (La)TeX is run on \fIyour_document\fP.tex, the file \fIfilename\fP.bb +is scanned for the bounding box comment, to allow (La)TeX to properly +reserve the right size for the figure. +Only when the file \fIyour_document\fP.dvi is printed by means of \fBdvips\fP, +the actual PostScript file \fIfilename\fP.Z is decompressed (\fBzcat\fP-ed) +and included in \fIyour_document\fP.ps. +.PP +.SH MACINTOSH FIGURES +Since the Macintosh drawing applications produce PostScript, they can +be used to create figures. +However, the PostScript produced by most Macintosh applications is often +not well +suited to be included directly as a \fBpsfig\fP 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. See the \fBpsfig\fP tool \fBcleanfig\fP +and the sample document \fBmacdemo.tex\fP for guidance. +.PP +Non-EPSF Macintosh PostScript files often +require a ``Laserprep'' prolog in order to +be properly printed. +A laserprep prolog can be included with the \fBdvips\fP special +header command at the top of your (La)TeX file: +``\\\fBspecial\fP{header=lprep70.procs}''. +\fBPsfig\fP provides `lprep68.procs', as well as `lprep70.procs', +to suit various versions of the Macintosh applications. +.PP +.SH 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 +"\\psfigurepath{dir1:dir2:...:dirn}", +where dir1...dirn are the directories figures are to be found in. +.PP +.SH PROBLEMS +.IP Problem: 10 +The page with graphics is not printed. +.IP Solution: 10 +Remove lines containing `\fBshowpage\fP' and/or `\fBstop\fP' +from the PostScript graphics file. +Lines of this kind are usually found near the end of the file. +.IP Problem: 10 +The figure is positioned in weird places. +.IP +Generally, this is an indication that the PostScript ``%%BoundingBox:'' +comment is missing. +It may also be that a translation takes places \fIafter\fP the +bounding box was determined. +.RE +.IP Solution: 10 +Edit a bounding box comment into the PostScript file +and/or experiment with the \fIbb...\fP values (see: MISSING BOUNDING +BOX above). +.PP +.SH BUGS +The \\\fBpsfig\fP macro is (unfortunately) sensitive to whitespace, +and will be confused by any extra spaces or newlines in its argument. +.PP +The LaTeX \fBletter\fP style must be loaded after the +\\\fBpsfig\fP macros due to naming conflicts. This can be +forced by including psfig with an explicit \\\fBinput\fP +command before the \\\fBdocumentstyle\fP command. +.PP +.SH ACKNOWLEDGEMENTS +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 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 +see \fIPsfig \- A Ditroff Preprocessor for PostScript Figures\fP in +the USENIX 87 proceedings, or \fIBringing troff up to speed\fP in the +July 1987 issue of Unix Review. +.PP +Greg Hager provided the initial pure-TeX implementation of \fBpsfig\fP. +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 \fBdvips\fP program. +.PP +Thanks to Sake Hogeveen (hogeveen.fys.ruu.nl) for editing this man page. +.SH AUTHOR +Trevor Darrell +.PP +.SH SEE ALSO +tex(1), latex(1), dvips(1), psfig-troff(1) +.PP +A printed version of the psfig-tex manual may be obtained by typing +.br +``% \fBlatex\fP psfig-doc'', then ``% \fBdvips\fP psfig-doc'', +.br +and finally printing the resulting psfig-doc.ps file on your nearest +PostScript printer. +The manual provides many examples with real-life PostScript graphics, +see the text of psfig-doc.tex for more usage examples. + |