source: trunk/texinfo/doc/epsf.tex@ 3003

Last change on this file since 3003 was 2617, checked in by bird, 19 years ago

GNU Texinfo 4.8

File size: 22.2 KB
Line 
1%%% ====================================================================
2%%% This file is freely redistributable and placed into the
3%%% public domain by Tomas Rokicki.
4%%% @TeX-file{
5%%% author = "Tom Rokicki",
6%%% version = "2.7k",
7%%% date = "19 July 1997",
8%%% time = "10:00:05 MDT",
9%%% filename = "epsf.tex",
10%%% address = "Tom Rokicki
11%%% Box 2081
12%%% Stanford, CA 94309
13%%% USA",
14%%% telephone = "+1 415 855 9989",
15%%% email = "rokicki@cs.stanford.edu (Internet)",
16%%% codetable = "ISO/ASCII",
17%%% keywords = "PostScript, TeX",
18%%% supported = "yes",
19%%% abstract = "This file contains macros to support the inclusion
20%%% of Encapsulated PostScript files in TeX documents.",
21%%% docstring = "This file contains TeX macros to include an
22%%% Encapsulated PostScript graphic. It works
23%%% by finding the bounding box comment,
24%%% calculating the correct scale values, and
25%%% inserting a vbox of the appropriate size at
26%%% the current position in the TeX document.
27%%%
28%%% To use, simply say
29%%%
30%%% \input epsf % somewhere early on in your TeX file
31%%%
32%%% % then where you want to insert a vbox for a figure:
33%%% \epsfbox{filename.ps}
34%%%
35%%% Alternatively, you can supply your own
36%%% bounding box by
37%%%
38%%% \epsfbox[0 0 30 50]{filename.ps}
39%%%
40%%% This will not read in the file, and will
41%%% instead use the bounding box you specify.
42%%%
43%%% The effect will be to typeset the figure as
44%%% a TeX box, at the point of your \epsfbox
45%%% command. By default, the graphic will have
46%%% its `natural' width (namely the width of
47%%% its bounding box, as described in
48%%% filename.ps). The TeX box will have depth
49%%% zero.
50%%%
51%%% You can enlarge or reduce the figure by
52%%% saying
53%%%
54%%% \epsfxsize=<dimen> \epsfbox{filename.ps}
55%%% or
56%%% \epsfysize=<dimen> \epsfbox{filename.ps}
57%%%
58%%% instead. Then the width of the TeX box will
59%%% be \epsfxsize and its height will be scaled
60%%% proportionately (or the height will be
61%%% \epsfysize and its width will be scaled
62%%% proportionately).
63%%%
64%%% The width (and height) is restored to zero
65%%% after each use, so \epsfxsize or \epsfysize
66%%% must be specified before EACH use of
67%%% \epsfbox.
68%%%
69%%% A more general facility for sizing is
70%%% available by defining the \epsfsize macro.
71%%% Normally you can redefine this macro to do
72%%% almost anything. The first parameter is
73%%% the natural x size of the PostScript
74%%% graphic, the second parameter is the
75%%% natural y size of the PostScript graphic.
76%%% It must return the xsize to use, or 0 if
77%%% natural scaling is to be used. Common uses
78%%% include:
79%%%
80%%% \epsfxsize % just leave the old value alone
81%%% 0pt % use the natural sizes
82%%% #1 % use the natural sizes
83%%% \hsize % scale to full width
84%%% 0.5#1 % scale to 50% of natural size
85%%% \ifnum #1>\hsize\hsize\else#1\fi
86%%% % smaller of natural, hsize
87%%%
88%%% If you want TeX to report the size of the
89%%% figure (as a message on your terminal when
90%%% it processes each figure), say
91%%% `\epsfverbosetrue'.
92%%%
93%%% If you only want to get the bounding box
94%%% extents, without producing any output boxes
95%%% or \special{}, then say
96%%% \epsfgetbb{filename}. The extents will be
97%%% saved in the macros \epsfllx \epsflly
98%%% \epsfurx \epsfury in PostScript units of
99%%% big points.
100%%%
101%%% Revision history:
102%%%
103%%% ---------------------------------------------
104%%% epsf.tex macro file:
105%%% Originally written by Tomas Rokicki of
106%%% Radical Eye Software, 29 Mar 1989.
107%%%
108%%% ---------------------------------------------
109%%% Revised by Don Knuth, 3 Jan 1990.
110%%%
111%%% ---------------------------------------------
112%%% Revised by Tomas Rokicki, 18 Jul 1990.
113%%% Accept bounding boxes with no space after
114%%% the colon.
115%%%
116%%% ---------------------------------------------
117%%% Revised by Nelson H. F. Beebe
118%%% <beebe@math.utah.edu>, 03 Dec 1991 [2.0].
119%%% Add version number and date typeout.
120%%%
121%%% Use \immediate\write16 instead of \message
122%%% to ensure output on new line.
123%%%
124%%% Handle nested EPS files.
125%%%
126%%% Handle %%BoundingBox: (atend) lines.
127%%%
128%%% Do not quit when blank lines are found.
129%%%
130%%% Add a few percents to remove generation of
131%%% spurious blank space.
132%%%
133%%% Move \special output to
134%%% \epsfspecial{filename} so that other macro
135%%% packages can input this one, then change
136%%% the definition of \epsfspecial to match
137%%% another DVI driver.
138%%%
139%%% Move size computation to \epsfsetsize which
140%%% can be called by the user; the verbose
141%%% output of the bounding box and scaled width
142%%% and height happens here.
143%%%
144%%% ---------------------------------------------
145%%% Revised by Nelson H. F. Beebe
146%%% <beebe@math.utah.edu>, 05 May 1992 [2.1].
147%%% Wrap \leavevmode\hbox{} around \vbox{} with
148%%% the \special so that \epsffile{} can be
149%%% used inside \begin{center}...\end{center}
150%%%
151%%% ---------------------------------------------
152%%% Revised by Nelson H. F. Beebe
153%%% <beebe@math.utah.edu>, 09 Dec 1992 [2.2].
154%%% Introduce \epsfshow{true,false} and
155%%% \epsfframe{true,false} macros; the latter
156%%% suppresses the insertion of the PostScript,
157%%% and instead just creates an empty box,
158%%% which may be handy for rapid prototyping.
159%%%
160%%% ---------------------------------------------
161%%% Revised by Nelson H. F. Beebe
162%%% <beebe@math.utah.edu>, 14 Dec 1992 [2.3].
163%%% Add \epsfshowfilename{true,false}. When
164%%% true, and \epsfshowfalse is specified, the
165%%% PostScript file name will be displayed
166%%% centered in the figure box.
167%%%
168%%% ---------------------------------------------
169%%% Revised by Nelson H. F. Beebe
170%%% <beebe@math.utah.edu>, 20 June 1993 [2.4].
171%%% Remove non-zero debug setting of \epsfframemargin,
172%%% and change margin handling to preserve EPS image
173%%% size and aspect ratio, so that the actual
174%%% box is \epsfxsize+\epsfframemargin wide by
175%%% \epsfysize+\epsfframemargin high.
176%%% Reduce output of \epsfshowfilenametrue to
177%%% just the bare file name.
178%%%
179%%% ---------------------------------------------
180%%% Revised by Nelson H. F. Beebe
181%%% <beebe@math.utah.edu>, 13 July 1993 [2.5].
182%%% Add \epsfframethickness for control of
183%%% \epsfframe frame lines.
184%%%
185%%% ---------------------------------------------
186%%% Revised by Nelson H. F. Beebe
187%%% <beebe@math.utah.edu>, 02 July 1996 [2.6]
188%%% Add missing initialization \epsfatendfalse;
189%%% the lack of this resulted in the wrong
190%%% BoundingBox being picked up, mea culpa, sigh...
191%%% ---------------------------------------------
192%%%
193%%% ---------------------------------------------
194%%% Revised by Nelson H. F. Beebe
195%%% <beebe@math.utah.edu>, 25 October 1996 [2.7]
196%%% Update to match changes in from dvips 5-600
197%%% distribution: new user-accessible macros:
198%%% \epsfclipon, \epsfclipoff, \epsfdrafton,
199%%% \epsfdraftoff, change \empty to \epsfempty.
200%%% ---------------------------------------------
201%%%
202%%% Modified to avoid verbosity, give help.
203%%% --kb@cs.umb.edu, for Texinfo.
204%%% }
205%%% ====================================================================
206%
207\ifx\epsfannounce\undefined \def\epsfannounce{\immediate\write16}\fi
208 \epsfannounce{This is `epsf.tex' v2.7k <10 July 1997>}%
209%
210\newread\epsffilein % file to \read
211\newif\ifepsfatend % need to scan to LAST %%BoundingBox comment?
212\newif\ifepsfbbfound % success?
213\newif\ifepsfdraft % use draft mode?
214\newif\ifepsffileok % continue looking for the bounding box?
215\newif\ifepsfframe % frame the bounding box?
216\newif\ifepsfshow % show PostScript file, or just bounding box?
217\epsfshowtrue % default is to display PostScript file
218\newif\ifepsfshowfilename % show the file name if \epsfshowfalse specified?
219\newif\ifepsfverbose % report what you're making?
220\newdimen\epsfframemargin % margin between box and frame
221\newdimen\epsfframethickness % thickness of frame rules
222\newdimen\epsfrsize % vertical size before scaling
223\newdimen\epsftmp % register for arithmetic manipulation
224\newdimen\epsftsize % horizontal size before scaling
225\newdimen\epsfxsize % horizontal size after scaling
226\newdimen\epsfysize % vertical size after scaling
227\newdimen\pspoints % conversion factor
228%
229\pspoints = 1bp % Adobe points are `big'
230\epsfxsize = 0pt % default value, means `use natural size'
231\epsfysize = 0pt % ditto
232\epsfframemargin = 0pt % default value: frame box flush around picture
233\epsfframethickness = 0.4pt % TeX's default rule thickness
234%
235\def\epsfbox#1{\global\def\epsfllx{72}\global\def\epsflly{72}%
236 \global\def\epsfurx{540}\global\def\epsfury{720}%
237 \def\lbracket{[}\def\testit{#1}\ifx\testit\lbracket
238 \let\next=\epsfgetlitbb\else\let\next=\epsfnormal\fi\next{#1}}%
239%
240% We use \epsfgetlitbb if the user specified an explicit bounding box,
241% and \epsfnormal otherwise. Because \epsfgetbb can be called
242% separately to retrieve the bounding box, we move the verbose
243% printing the bounding box extents and size on the terminal to
244% \epsfstatus. Therefore, when the user provided the bounding box,
245% \epsfgetbb will not be called, so we must call \epsfsetsize and
246% \epsfstatus ourselves.
247%
248\def\epsfgetlitbb#1#2 #3 #4 #5]#6{%
249 \epsfgrab #2 #3 #4 #5 .\\%
250 \epsfsetsize
251 \epsfstatus{#6}%
252 \epsfsetgraph{#6}%
253}%
254%
255\def\epsfnormal#1{%
256 \epsfgetbb{#1}%
257 \epsfsetgraph{#1}%
258}%
259%
260\newhelp\epsfnoopenhelp{The PostScript image file must be findable by
261TeX, i.e., somewhere in the TEXINPUTS (or equivalent) path.}%
262%
263\def\epsfgetbb#1{%
264%
265% The first thing we need to do is to open the
266% PostScript file, if possible.
267%
268 \openin\epsffilein=#1
269 \ifeof\epsffilein
270 \errhelp = \epsfnoopenhelp
271 \errmessage{Could not open file #1, ignoring it}%
272 \else %process the file
273 {% %start a group to contain catcode changes
274 % Make all special characters, except space, to be of type
275 % `other' so we process the file in almost verbatim mode
276 % (TeXbook, p. 344).
277 \chardef\other=12
278 \def\do##1{\catcode`##1=\other}%
279 \dospecials
280 \catcode`\ =10
281 \epsffileoktrue %true while we are looping
282 \epsfatendfalse %[02-Jul-1996]: add forgotten initialization
283 \loop %reading lines from the EPS file
284 \read\epsffilein to \epsffileline
285 \ifeof\epsffilein %then no more input
286 \epsffileokfalse %so set completion flag
287 \else %otherwise process one line
288 \expandafter\epsfaux\epsffileline:. \\%
289 \fi
290 \ifepsffileok
291 \repeat
292 \ifepsfbbfound
293 \else
294 \ifepsfverbose
295 \immediate\write16{No BoundingBox comment found in %
296 file #1; using defaults}%
297 \fi
298 \fi
299 }% %end catcode changes
300 \closein\epsffilein
301 \fi %end of file processing
302 \epsfsetsize %compute size parameters
303 \epsfstatus{#1}%
304}%
305%
306% Clipping control:
307\def\epsfclipon{\def\epsfclipstring{ clip}}%
308\def\epsfclipoff{\def\epsfclipstring{\ifepsfdraft\space clip\fi}}%
309\epsfclipoff % default for dvips is OFF
310%
311% The special that is emitted by \epsfsetgraph comes from this macro.
312% It is defined separately to allow easy customization by other
313% packages that first \input epsf.tex, then redefine \epsfspecial.
314% This macro is invoked in the lower-left corner of a box of the
315% width and height determined from the arguments to \epsffile, or
316% from the %%BoundingBox in the EPS file itself.
317%
318% This version is for dvips:
319\def\epsfspecial#1{%
320 \epsftmp=10\epsfxsize
321 \divide\epsftmp\pspoints
322 \ifnum\epsfrsize=0\relax
323 \special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space
324 llx=\epsfllx\space
325 lly=\epsflly\space
326 urx=\epsfurx\space
327 ury=\epsfury\space
328 rwi=\number\epsftmp
329 \epsfclipstring
330 }%
331 \else
332 \epsfrsize=10\epsfysize
333 \divide\epsfrsize\pspoints
334 \special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space
335 llx=\epsfllx\space
336 lly=\epsflly\space
337 urx=\epsfurx\space
338 ury=\epsfury\space
339 rwi=\number\epsftmp\space
340 rhi=\number\epsfrsize
341 \epsfclipstring
342 }%
343 \fi
344}%
345%
346% \epsfframe macro adapted from the TeXbook, exercise 21.3, p. 223, 331.
347% but modified to set the box width to the natural width, rather
348% than the line width, and to include space for margins and rules
349\def\epsfframe#1%
350{%
351 \leavevmode % so we can put this inside
352 % a centered environment
353 \setbox0 = \hbox{#1}%
354 \dimen0 = \wd0 % natural width of argument
355 \advance \dimen0 by 2\epsfframemargin % plus width of 2 margins
356 \advance \dimen0 by 2\epsfframethickness % plus width of 2 rule lines
357 \vbox
358 {%
359 \hrule height \epsfframethickness depth 0pt
360 \hbox to \dimen0
361 {%
362 \hss
363 \vrule width \epsfframethickness
364 \kern \epsfframemargin
365 \vbox {\kern \epsfframemargin \box0 \kern \epsfframemargin }%
366 \kern \epsfframemargin
367 \vrule width \epsfframethickness
368 \hss
369 }% end hbox
370 \hrule height 0pt depth \epsfframethickness
371 }% end vbox
372}%
373%
374\def\epsfsetgraph#1%
375{%
376 %
377 % Make the vbox and stick in a \special that the DVI driver can
378 % parse. \vfil and \hfil are used to place the \special origin at
379 % the lower-left corner of the vbox. \epsfspecial can be redefined
380 % to produce alternate \special syntaxes.
381 %
382 \leavevmode
383 \hbox{% so we can put this in \begin{center}...\end{center}
384 \ifepsfframe\expandafter\epsfframe\fi
385 {\vbox to\epsfysize
386 {%
387 \ifepsfshow
388 % output \special{} at lower-left corner of figure box
389 \vfil
390 \hbox to \epsfxsize{\epsfspecial{#1}\hfil}%
391 \else
392 \vfil
393 \hbox to\epsfxsize{%
394 \hss
395 \ifepsfshowfilename
396 {%
397 \epsfframemargin=3pt % local change of margin
398 \epsfframe{{\tt #1}}%
399 }%
400 \fi
401 \hss
402 }%
403 \vfil
404 \fi
405 }%
406 }}%
407 %
408 % Reset \epsfxsize and \epsfysize, as documented above.
409 %
410 \global\epsfxsize=0pt
411 \global\epsfysize=0pt
412}%
413%
414% Now we have to calculate the scale and offset values to use.
415% First we compute the natural sizes.
416%
417\def\epsfsetsize
418{%
419 \epsfrsize=\epsfury\pspoints
420 \advance\epsfrsize by-\epsflly\pspoints
421 \epsftsize=\epsfurx\pspoints
422 \advance\epsftsize by-\epsfllx\pspoints
423%
424% If `epsfxsize' is 0, we default to the natural size of the picture.
425% Otherwise we scale the graph to be \epsfxsize wide.
426%
427 \epsfxsize=\epsfsize{\epsftsize}{\epsfrsize}%
428 \ifnum \epsfxsize=0
429 \ifnum \epsfysize=0
430 \epsfxsize=\epsftsize
431 \epsfysize=\epsfrsize
432 \epsfrsize=0pt
433%
434% We have a sticky problem here: TeX doesn't do floating point arithmetic!
435% Our goal is to compute y = rx/t. The following loop does this reasonably
436% fast, with an error of at most about 16 sp (about 1/4000 pt).
437%
438 \else
439 \epsftmp=\epsftsize \divide\epsftmp\epsfrsize
440 \epsfxsize=\epsfysize \multiply\epsfxsize\epsftmp
441 \multiply\epsftmp\epsfrsize \advance\epsftsize-\epsftmp
442 \epsftmp=\epsfysize
443 \loop \advance\epsftsize\epsftsize \divide\epsftmp 2
444 \ifnum \epsftmp>0
445 \ifnum \epsftsize<\epsfrsize
446 \else
447 \advance\epsftsize-\epsfrsize \advance\epsfxsize\epsftmp
448 \fi
449 \repeat
450 \epsfrsize=0pt
451 \fi
452 \else
453 \ifnum \epsfysize=0
454 \epsftmp=\epsfrsize \divide\epsftmp\epsftsize
455 \epsfysize=\epsfxsize \multiply\epsfysize\epsftmp
456 \multiply\epsftmp\epsftsize \advance\epsfrsize-\epsftmp
457 \epsftmp=\epsfxsize
458 \loop \advance\epsfrsize\epsfrsize \divide\epsftmp 2
459 \ifnum \epsftmp>0
460 \ifnum \epsfrsize<\epsftsize
461 \else
462 \advance\epsfrsize-\epsftsize \advance\epsfysize\epsftmp
463 \fi
464 \repeat
465 \epsfrsize=0pt
466 \else
467 \epsfrsize=\epsfysize
468 \fi
469 \fi
470}%
471%
472% Issue some status messages if the user requested them
473%
474\def\epsfstatus#1{% arg = filename
475 \ifepsfverbose
476 \immediate\write16{#1: BoundingBox:
477 llx = \epsfllx\space lly = \epsflly\space
478 urx = \epsfurx\space ury = \epsfury\space}%
479 \immediate\write16{#1: scaled width = \the\epsfxsize\space
480 scaled height = \the\epsfysize}%
481 \fi
482}%
483%
484% We still need to define the tricky \epsfaux macro. This requires
485% a couple of magic constants for comparison purposes.
486%
487{\catcode`\%=12 \global\let\epsfpercent=%\global\def\epsfbblit{%BoundingBox}}%
488\global\def\epsfatend{(atend)}%
489%
490% So we're ready to check for `%BoundingBox:' and to grab the
491% values if they are found.
492%
493% If we find a line
494%
495% %%BoundingBox: (atend)
496%
497% then we ignore it, but set a flag to force parsing all of the
498% file, so the last %%BoundingBox parsed will be the one used. This
499% is necessary, because EPS files can themselves contain other EPS
500% files with their own %%BoundingBox comments.
501%
502% If we find a line
503%
504% %%BoundingBox: llx lly urx ury
505%
506% then we save the 4 values in \epsfllx, \epsflly, \epsfurx, \epsfury.
507% Then, if we have not previously parsed an (atend), we flag completion
508% and can stop reading the file. Otherwise, we must keep on reading
509% to end of file so that we find the values on the LAST %%BoundingBox.
510\long\def\epsfaux#1#2:#3\\%
511{%
512 \def\testit{#2}% % save second character up to just before colon
513 \ifx#1\epsfpercent % then first char is percent (quick test)
514 \ifx\testit\epsfbblit % then (slow test) we have %%BoundingBox
515 \epsfgrab #3 . . . \\%
516 \ifx\epsfllx\epsfatend % then ignore %%BoundingBox: (atend)
517 \global\epsfatendtrue
518 \else % else found %%BoundingBox: llx lly urx ury
519 \ifepsfatend % then keep parsing ALL %%BoundingBox lines
520 \else % else stop after first one parsed
521 \epsffileokfalse
522 \fi
523 \global\epsfbbfoundtrue
524 \fi
525 \fi
526 \fi
527}%
528%
529% Here we grab the values and stuff them in the appropriate definitions.
530%
531\def\epsfempty{}%
532\def\epsfgrab #1 #2 #3 #4 #5\\{%
533 \global\def\epsfllx{#1}\ifx\epsfllx\epsfempty
534 \epsfgrab #2 #3 #4 #5 .\\\else
535 \global\def\epsflly{#2}%
536 \global\def\epsfurx{#3}\global\def\epsfury{#4}\fi
537}%
538%
539% We default the epsfsize macro.
540%
541\def\epsfsize#1#2{\epsfxsize}%
542%
543% Finally, another definition for compatibility with older macros.
544%
545\let\epsffile=\epsfbox
546\endinput
547
Note: See TracBrowser for help on using the repository browser.