freebsd-skq/contrib/texinfo/doc/epsf.tex
markm 15da023077 Upgrade texinfo to the latest-and-greatest.
This has big improvements to the .info file utility support and
much recent OSS requires its features.
1999-01-14 19:35:19 +00:00

547 lines
22 KiB
TeX

%%% ====================================================================
%%% This file is freely redistributable and placed into the
%%% public domain by Tomas Rokicki.
%%% @TeX-file{
%%% author = "Tom Rokicki",
%%% version = "2.7k",
%%% date = "19 July 1997",
%%% time = "10:00:05 MDT",
%%% filename = "epsf.tex",
%%% address = "Tom Rokicki
%%% Box 2081
%%% Stanford, CA 94309
%%% USA",
%%% telephone = "+1 415 855 9989",
%%% email = "rokicki@cs.stanford.edu (Internet)",
%%% codetable = "ISO/ASCII",
%%% keywords = "PostScript, TeX",
%%% supported = "yes",
%%% abstract = "This file contains macros to support the inclusion
%%% of Encapsulated PostScript files in TeX documents.",
%%% docstring = "This file contains TeX macros to include an
%%% Encapsulated PostScript graphic. It works
%%% by finding the bounding box comment,
%%% calculating the correct scale values, and
%%% inserting a vbox of the appropriate size at
%%% the current position in the TeX document.
%%%
%%% To use, simply say
%%%
%%% \input epsf % somewhere early on in your TeX file
%%%
%%% % then where you want to insert a vbox for a figure:
%%% \epsfbox{filename.ps}
%%%
%%% Alternatively, you can supply your own
%%% bounding box by
%%%
%%% \epsfbox[0 0 30 50]{filename.ps}
%%%
%%% This will not read in the file, and will
%%% instead use the bounding box you specify.
%%%
%%% The effect will be to typeset the figure as
%%% a TeX box, at the point of your \epsfbox
%%% command. By default, the graphic will have
%%% its `natural' width (namely the width of
%%% its bounding box, as described in
%%% filename.ps). The TeX box will have depth
%%% zero.
%%%
%%% You can enlarge or reduce the figure by
%%% saying
%%%
%%% \epsfxsize=<dimen> \epsfbox{filename.ps}
%%% or
%%% \epsfysize=<dimen> \epsfbox{filename.ps}
%%%
%%% instead. Then the width of the TeX box will
%%% be \epsfxsize and its height will be scaled
%%% proportionately (or the height will be
%%% \epsfysize and its width will be scaled
%%% proportionately).
%%%
%%% The width (and height) is restored to zero
%%% after each use, so \epsfxsize or \epsfysize
%%% must be specified before EACH use of
%%% \epsfbox.
%%%
%%% A more general facility for sizing is
%%% available by defining the \epsfsize macro.
%%% Normally you can redefine this macro to do
%%% almost anything. The first parameter is
%%% the natural x size of the PostScript
%%% graphic, the second parameter is the
%%% natural y size of the PostScript graphic.
%%% It must return the xsize to use, or 0 if
%%% natural scaling is to be used. Common uses
%%% include:
%%%
%%% \epsfxsize % just leave the old value alone
%%% 0pt % use the natural sizes
%%% #1 % use the natural sizes
%%% \hsize % scale to full width
%%% 0.5#1 % scale to 50% of natural size
%%% \ifnum #1>\hsize\hsize\else#1\fi
%%% % smaller of natural, hsize
%%%
%%% If you want TeX to report the size of the
%%% figure (as a message on your terminal when
%%% it processes each figure), say
%%% `\epsfverbosetrue'.
%%%
%%% If you only want to get the bounding box
%%% extents, without producing any output boxes
%%% or \special{}, then say
%%% \epsfgetbb{filename}. The extents will be
%%% saved in the macros \epsfllx \epsflly
%%% \epsfurx \epsfury in PostScript units of
%%% big points.
%%%
%%% Revision history:
%%%
%%% ---------------------------------------------
%%% epsf.tex macro file:
%%% Originally written by Tomas Rokicki of
%%% Radical Eye Software, 29 Mar 1989.
%%%
%%% ---------------------------------------------
%%% Revised by Don Knuth, 3 Jan 1990.
%%%
%%% ---------------------------------------------
%%% Revised by Tomas Rokicki, 18 Jul 1990.
%%% Accept bounding boxes with no space after
%%% the colon.
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 03 Dec 1991 [2.0].
%%% Add version number and date typeout.
%%%
%%% Use \immediate\write16 instead of \message
%%% to ensure output on new line.
%%%
%%% Handle nested EPS files.
%%%
%%% Handle %%BoundingBox: (atend) lines.
%%%
%%% Do not quit when blank lines are found.
%%%
%%% Add a few percents to remove generation of
%%% spurious blank space.
%%%
%%% Move \special output to
%%% \epsfspecial{filename} so that other macro
%%% packages can input this one, then change
%%% the definition of \epsfspecial to match
%%% another DVI driver.
%%%
%%% Move size computation to \epsfsetsize which
%%% can be called by the user; the verbose
%%% output of the bounding box and scaled width
%%% and height happens here.
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 05 May 1992 [2.1].
%%% Wrap \leavevmode\hbox{} around \vbox{} with
%%% the \special so that \epsffile{} can be
%%% used inside \begin{center}...\end{center}
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 09 Dec 1992 [2.2].
%%% Introduce \epsfshow{true,false} and
%%% \epsfframe{true,false} macros; the latter
%%% suppresses the insertion of the PostScript,
%%% and instead just creates an empty box,
%%% which may be handy for rapid prototyping.
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 14 Dec 1992 [2.3].
%%% Add \epsfshowfilename{true,false}. When
%%% true, and \epsfshowfalse is specified, the
%%% PostScript file name will be displayed
%%% centered in the figure box.
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 20 June 1993 [2.4].
%%% Remove non-zero debug setting of \epsfframemargin,
%%% and change margin handling to preserve EPS image
%%% size and aspect ratio, so that the actual
%%% box is \epsfxsize+\epsfframemargin wide by
%%% \epsfysize+\epsfframemargin high.
%%% Reduce output of \epsfshowfilenametrue to
%%% just the bare file name.
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 13 July 1993 [2.5].
%%% Add \epsfframethickness for control of
%%% \epsfframe frame lines.
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 02 July 1996 [2.6]
%%% Add missing initialization \epsfatendfalse;
%%% the lack of this resulted in the wrong
%%% BoundingBox being picked up, mea culpa, sigh...
%%% ---------------------------------------------
%%%
%%% ---------------------------------------------
%%% Revised by Nelson H. F. Beebe
%%% <beebe@math.utah.edu>, 25 October 1996 [2.7]
%%% Update to match changes in from dvips 5-600
%%% distribution: new user-accessible macros:
%%% \epsfclipon, \epsfclipoff, \epsfdrafton,
%%% \epsfdraftoff, change \empty to \epsfempty.
%%% ---------------------------------------------
%%%
%%% Modified to avoid verbosity, give help.
%%% --kb@cs.umb.edu, for Texinfo.
%%% }
%%% ====================================================================
%
\ifx\epsfannounce\undefined \def\epsfannounce{\immediate\write16}\fi
\epsfannounce{This is `epsf.tex' v2.7k <10 July 1997>}%
%
\newread\epsffilein % file to \read
\newif\ifepsfatend % need to scan to LAST %%BoundingBox comment?
\newif\ifepsfbbfound % success?
\newif\ifepsfdraft % use draft mode?
\newif\ifepsffileok % continue looking for the bounding box?
\newif\ifepsfframe % frame the bounding box?
\newif\ifepsfshow % show PostScript file, or just bounding box?
\epsfshowtrue % default is to display PostScript file
\newif\ifepsfshowfilename % show the file name if \epsfshowfalse specified?
\newif\ifepsfverbose % report what you're making?
\newdimen\epsfframemargin % margin between box and frame
\newdimen\epsfframethickness % thickness of frame rules
\newdimen\epsfrsize % vertical size before scaling
\newdimen\epsftmp % register for arithmetic manipulation
\newdimen\epsftsize % horizontal size before scaling
\newdimen\epsfxsize % horizontal size after scaling
\newdimen\epsfysize % vertical size after scaling
\newdimen\pspoints % conversion factor
%
\pspoints = 1bp % Adobe points are `big'
\epsfxsize = 0pt % default value, means `use natural size'
\epsfysize = 0pt % ditto
\epsfframemargin = 0pt % default value: frame box flush around picture
\epsfframethickness = 0.4pt % TeX's default rule thickness
%
\def\epsfbox#1{\global\def\epsfllx{72}\global\def\epsflly{72}%
\global\def\epsfurx{540}\global\def\epsfury{720}%
\def\lbracket{[}\def\testit{#1}\ifx\testit\lbracket
\let\next=\epsfgetlitbb\else\let\next=\epsfnormal\fi\next{#1}}%
%
% We use \epsfgetlitbb if the user specified an explicit bounding box,
% and \epsfnormal otherwise. Because \epsfgetbb can be called
% separately to retrieve the bounding box, we move the verbose
% printing the bounding box extents and size on the terminal to
% \epsfstatus. Therefore, when the user provided the bounding box,
% \epsfgetbb will not be called, so we must call \epsfsetsize and
% \epsfstatus ourselves.
%
\def\epsfgetlitbb#1#2 #3 #4 #5]#6{%
\epsfgrab #2 #3 #4 #5 .\\%
\epsfsetsize
\epsfstatus{#6}%
\epsfsetgraph{#6}%
}%
%
\def\epsfnormal#1{%
\epsfgetbb{#1}%
\epsfsetgraph{#1}%
}%
%
\newhelp\epsfnoopenhelp{The PostScript image file must be findable by
TeX, i.e., somewhere in the TEXINPUTS (or equivalent) path.}%
%
\def\epsfgetbb#1{%
%
% The first thing we need to do is to open the
% PostScript file, if possible.
%
\openin\epsffilein=#1
\ifeof\epsffilein
\errhelp = \epsfnoopenhelp
\errmessage{Could not open file #1, ignoring it}%
\else %process the file
{% %start a group to contain catcode changes
% Make all special characters, except space, to be of type
% `other' so we process the file in almost verbatim mode
% (TeXbook, p. 344).
\chardef\other=12
\def\do##1{\catcode`##1=\other}%
\dospecials
\catcode`\ =10
\epsffileoktrue %true while we are looping
\epsfatendfalse %[02-Jul-1996]: add forgotten initialization
\loop %reading lines from the EPS file
\read\epsffilein to \epsffileline
\ifeof\epsffilein %then no more input
\epsffileokfalse %so set completion flag
\else %otherwise process one line
\expandafter\epsfaux\epsffileline:. \\%
\fi
\ifepsffileok
\repeat
\ifepsfbbfound
\else
\ifepsfverbose
\immediate\write16{No BoundingBox comment found in %
file #1; using defaults}%
\fi
\fi
}% %end catcode changes
\closein\epsffilein
\fi %end of file processing
\epsfsetsize %compute size parameters
\epsfstatus{#1}%
}%
%
% Clipping control:
\def\epsfclipon{\def\epsfclipstring{ clip}}%
\def\epsfclipoff{\def\epsfclipstring{\ifepsfdraft\space clip\fi}}%
\epsfclipoff % default for dvips is OFF
%
% The special that is emitted by \epsfsetgraph comes from this macro.
% It is defined separately to allow easy customization by other
% packages that first \input epsf.tex, then redefine \epsfspecial.
% This macro is invoked in the lower-left corner of a box of the
% width and height determined from the arguments to \epsffile, or
% from the %%BoundingBox in the EPS file itself.
%
% This version is for dvips:
\def\epsfspecial#1{%
\epsftmp=10\epsfxsize
\divide\epsftmp\pspoints
\ifnum\epsfrsize=0\relax
\special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space
llx=\epsfllx\space
lly=\epsflly\space
urx=\epsfurx\space
ury=\epsfury\space
rwi=\number\epsftmp
\epsfclipstring
}%
\else
\epsfrsize=10\epsfysize
\divide\epsfrsize\pspoints
\special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space
llx=\epsfllx\space
lly=\epsflly\space
urx=\epsfurx\space
ury=\epsfury\space
rwi=\number\epsftmp
rhi=\number\epsfrsize
\epsfclipstring
}%
\fi
}%
%
% \epsfframe macro adapted from the TeXbook, exercise 21.3, p. 223, 331.
% but modified to set the box width to the natural width, rather
% than the line width, and to include space for margins and rules
\def\epsfframe#1%
{%
\leavevmode % so we can put this inside
% a centered environment
\setbox0 = \hbox{#1}%
\dimen0 = \wd0 % natural width of argument
\advance \dimen0 by 2\epsfframemargin % plus width of 2 margins
\advance \dimen0 by 2\epsfframethickness % plus width of 2 rule lines
\vbox
{%
\hrule height \epsfframethickness depth 0pt
\hbox to \dimen0
{%
\hss
\vrule width \epsfframethickness
\kern \epsfframemargin
\vbox {\kern \epsfframemargin \box0 \kern \epsfframemargin }%
\kern \epsfframemargin
\vrule width \epsfframethickness
\hss
}% end hbox
\hrule height 0pt depth \epsfframethickness
}% end vbox
}%
%
\def\epsfsetgraph#1%
{%
%
% Make the vbox and stick in a \special that the DVI driver can
% parse. \vfil and \hfil are used to place the \special origin at
% the lower-left corner of the vbox. \epsfspecial can be redefined
% to produce alternate \special syntaxes.
%
\leavevmode
\hbox{% so we can put this in \begin{center}...\end{center}
\ifepsfframe\expandafter\epsfframe\fi
{\vbox to\epsfysize
{%
\ifepsfshow
% output \special{} at lower-left corner of figure box
\vfil
\hbox to \epsfxsize{\epsfspecial{#1}\hfil}%
\else
\vfil
\hbox to\epsfxsize{%
\hss
\ifepsfshowfilename
{%
\epsfframemargin=3pt % local change of margin
\epsfframe{{\tt #1}}%
}%
\fi
\hss
}%
\vfil
\fi
}%
}}%
%
% Reset \epsfxsize and \epsfysize, as documented above.
%
\global\epsfxsize=0pt
\global\epsfysize=0pt
}%
%
% Now we have to calculate the scale and offset values to use.
% First we compute the natural sizes.
%
\def\epsfsetsize
{%
\epsfrsize=\epsfury\pspoints
\advance\epsfrsize by-\epsflly\pspoints
\epsftsize=\epsfurx\pspoints
\advance\epsftsize by-\epsfllx\pspoints
%
% If `epsfxsize' is 0, we default to the natural size of the picture.
% Otherwise we scale the graph to be \epsfxsize wide.
%
\epsfxsize=\epsfsize{\epsftsize}{\epsfrsize}%
\ifnum \epsfxsize=0
\ifnum \epsfysize=0
\epsfxsize=\epsftsize
\epsfysize=\epsfrsize
\epsfrsize=0pt
%
% We have a sticky problem here: TeX doesn't do floating point arithmetic!
% Our goal is to compute y = rx/t. The following loop does this reasonably
% fast, with an error of at most about 16 sp (about 1/4000 pt).
%
\else
\epsftmp=\epsftsize \divide\epsftmp\epsfrsize
\epsfxsize=\epsfysize \multiply\epsfxsize\epsftmp
\multiply\epsftmp\epsfrsize \advance\epsftsize-\epsftmp
\epsftmp=\epsfysize
\loop \advance\epsftsize\epsftsize \divide\epsftmp 2
\ifnum \epsftmp>0
\ifnum \epsftsize<\epsfrsize
\else
\advance\epsftsize-\epsfrsize \advance\epsfxsize\epsftmp
\fi
\repeat
\epsfrsize=0pt
\fi
\else
\ifnum \epsfysize=0
\epsftmp=\epsfrsize \divide\epsftmp\epsftsize
\epsfysize=\epsfxsize \multiply\epsfysize\epsftmp
\multiply\epsftmp\epsftsize \advance\epsfrsize-\epsftmp
\epsftmp=\epsfxsize
\loop \advance\epsfrsize\epsfrsize \divide\epsftmp 2
\ifnum \epsftmp>0
\ifnum \epsfrsize<\epsftsize
\else
\advance\epsfrsize-\epsftsize \advance\epsfysize\epsftmp
\fi
\repeat
\epsfrsize=0pt
\else
\epsfrsize=\epsfysize
\fi
\fi
}%
%
% Issue some status messages if the user requested them
%
\def\epsfstatus#1{% arg = filename
\ifepsfverbose
\immediate\write16{#1: BoundingBox:
llx = \epsfllx\space lly = \epsflly\space
urx = \epsfurx\space ury = \epsfury\space}%
\immediate\write16{#1: scaled width = \the\epsfxsize\space
scaled height = \the\epsfysize}%
\fi
}%
%
% We still need to define the tricky \epsfaux macro. This requires
% a couple of magic constants for comparison purposes.
%
{\catcode`\%=12 \global\let\epsfpercent=%\global\def\epsfbblit{%BoundingBox}}%
\global\def\epsfatend{(atend)}%
%
% So we're ready to check for `%BoundingBox:' and to grab the
% values if they are found.
%
% If we find a line
%
% %%BoundingBox: (atend)
%
% then we ignore it, but set a flag to force parsing all of the
% file, so the last %%BoundingBox parsed will be the one used. This
% is necessary, because EPS files can themselves contain other EPS
% files with their own %%BoundingBox comments.
%
% If we find a line
%
% %%BoundingBox: llx lly urx ury
%
% then we save the 4 values in \epsfllx, \epsflly, \epsfurx, \epsfury.
% Then, if we have not previously parsed an (atend), we flag completion
% and can stop reading the file. Otherwise, we must keep on reading
% to end of file so that we find the values on the LAST %%BoundingBox.
\long\def\epsfaux#1#2:#3\\%
{%
\def\testit{#2}% % save second character up to just before colon
\ifx#1\epsfpercent % then first char is percent (quick test)
\ifx\testit\epsfbblit % then (slow test) we have %%BoundingBox
\epsfgrab #3 . . . \\%
\ifx\epsfllx\epsfatend % then ignore %%BoundingBox: (atend)
\global\epsfatendtrue
\else % else found %%BoundingBox: llx lly urx ury
\ifepsfatend % then keep parsing ALL %%BoundingBox lines
\else % else stop after first one parsed
\epsffileokfalse
\fi
\global\epsfbbfoundtrue
\fi
\fi
\fi
}%
%
% Here we grab the values and stuff them in the appropriate definitions.
%
\def\epsfempty{}%
\def\epsfgrab #1 #2 #3 #4 #5\\{%
\global\def\epsfllx{#1}\ifx\epsfllx\epsfempty
\epsfgrab #2 #3 #4 #5 .\\\else
\global\def\epsflly{#2}%
\global\def\epsfurx{#3}\global\def\epsfury{#4}\fi
}%
%
% We default the epsfsize macro.
%
\def\epsfsize#1#2{\epsfxsize}%
%
% Finally, another definition for compatibility with older macros.
%
\let\epsffile=\epsfbox
\endinput