diff options
Diffstat (limited to 'contrib/texinfo/doc/epsf.tex')
-rw-r--r-- | contrib/texinfo/doc/epsf.tex | 546 |
1 files changed, 546 insertions, 0 deletions
diff --git a/contrib/texinfo/doc/epsf.tex b/contrib/texinfo/doc/epsf.tex new file mode 100644 index 0000000..4f9dded --- /dev/null +++ b/contrib/texinfo/doc/epsf.tex @@ -0,0 +1,546 @@ +%%% ==================================================================== +%%% 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 |