texinfo/doc/epsf.tex

   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
 261 TeX, 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
 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