diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/generic/boxedeps/boxedeps.doc |
Initial commit
Diffstat (limited to 'macros/generic/boxedeps/boxedeps.doc')
-rw-r--r-- | macros/generic/boxedeps/boxedeps.doc | 1242 |
1 files changed, 1242 insertions, 0 deletions
diff --git a/macros/generic/boxedeps/boxedeps.doc b/macros/generic/boxedeps/boxedeps.doc new file mode 100644 index 0000000000..d534f4e218 --- /dev/null +++ b/macros/generic/boxedeps/boxedeps.doc @@ -0,0 +1,1242 @@ +%%%%% boxedeps.doc of Nov 1995 + %% + %%% POSTINGS: + %% --- ftp matups.matups.fr + %% This is the master copy in 1995. + %% Locate the full package on the CTAN servers + %% by using (while connected) the command + %% quote site index boxedeps + %%%% NEWS (11-95): + %% * BoundingBox trimming in percentage "pct" units. + %% * High resolution bounding boxes are used when available. + %% * Log file epsf.lst reports epsf files integrated; + %% use it as an inventory for exporting. + %% * EPSP the PC binary EPS format for including preview + %% as a Windows metafile bitmap or a TIFF bitmap + %% is now supported by this package. Beware that few + %% drivers on other platforms support it. + %%%% NEWS (1-95): + %% * \SetepsfEPSFSpecial works for the + %% several drivers that support the particular special syntax + %% first supported by Rokicki in dvips and used in his epsf.tex. + %% * Experimental feature: \SetEPSFMultiSpecial + %% works also for Textures. Intended to create ".dvi" files + %% for posting on the internet that will print with graphics + %% insertions on all major operating systems. Some drivers + %% produce spurious error reports but print correctly. + + ******************************************************* + + + ********* The BoxedEPSF Utility ********** + + by Laurent Siebenmann 1989-95 + + (in distribution since Winter 1991) + + + ******************************************************* + + --- THE DOCUMENTATION --- + + +COMMAND SUMMARY + + BoxedEPSF lets one integrate Encapsulated PostScript Files (EPSFs) +into TeX documents by making them behave as TeX boxes --- using the +commands in the following list. The user should promptly familiarize +him/her self with the left alligned commands; the indented ones are +less used. + + %%% Commands for article header or style file + \input boxedeps.tex %% obligatory (except for LaTeX, see below) + \input boxedeps.cfg %% can replace next line: + \Set...EPSFSpecial %% e.g. \SetOzTeXEPSFSpecial + \ShowDisplacementBoxes%\HideDisplacementBoxes %%alternatives + \SetEPSFDirectory{<directory pathname>} + \SetDefaultEPSFScale{<scale in mils>} + \EmulateRokicki + %%% EPSF insertion + \BoxedEPSF{<filename> scaled <scale in mils>} + %% scaled ... is optional + \tBoxedEPSF{...} %% 3 variants: + \bBoxedEPSF{...} + \cBoxedEPSF{...} + \EPSFbox{...} %% like Rokicki's syntax: + \EPSFfile{...} + %%% Adjustments that may preceed each \BoxedEPSF... + \TrimTop{<percentage>} + \TrimLeft{<percentage>} + \TrimBottom{<percentage>} + \TrimRight{<percentage>} + \TrimBoundingBox{<percentage>} + \hSlide{<dimen>} + \vSlide{<dimen>} + \ForceWidth{<dimen>} + \EPSFxsize=<dimen> + \ForceHeight{<dimen>} + \EPSFysize=<dimen> + \ForceOn (cf.\ForceOff) + + %%% Typical (minimal) Plain TeX example: + + \input boxedeps.tex + \input boxedeps.cfg + \midinsert + \centerline{\BoxedEPSF{gdisk.eps}} + \endinsert + \bye + +This list can serve to locate details by string search. Some +alternative older terminology is supported for compatibility (but not +recommended); it is found inside boxedeps.tex. + + *** LaTeX syntax variants *** + + BoxedEPS is compatible with LaTeX (2.09 or 2e). No change of +syntax is necessary. + + However, those who use LaTeX to the exclusion of other +TeX formats will find Alun Carr's "LaTeX wraper" boxedeps.sty +helpful to bring BoxedEPS into line with LaTeX conventions. +The following LaTeX syntax is valid as soon as the auxilliary file +boxedeps.sty is available to LaTeX. + +\usepackage[<option list>]{boxedeps} %% loads package, sets options + +Then \input boxedeps.tex must be omitted and \input boxedeps.cfg +also. The LaTeX option keywords with their Plain TeX equivalents +are: + + %% Driver support (use at most one) + epsf <==> \SetepsfEPSFSpecial + epsfmulti <==> \SetEPSFMultiSpecial + textures <==> \SetTexturesEPSFSpecial + unixcoop <==> \SetUnixCoopEPSFSpecial + niponunix <==> \SetNiponUnixEPSFSpecial + bechtolsheim <==> \SetBechtolsheimDVITPSEPSFSpecial + lis <==> \SetLisEPSFSpecial + rokicki <==> \SetRokickiEPSFSpecial + dvipsone <==> \SetDVIPSoneEPSFSpecial + dviwindow <==> \SetDVIWindowEPSFSpecial + directtex <==> \SetDirectTeXEPSFSpecial + cmactex <==> \SetCMacTeXEPSFSpecial + oztex <==> \SetOzTeXEPSFSpecial + oldoztex <==> \SetOldOzTeXEPSFSpecial + psprint <==> \SetPSprintEPSFSpecial + arbor <==> \SetArborEPSFSpecial + clark <==> \SetClarkEPSFSpecial + beebe <==> \SetBeebeEPSFSpecial + northlake <==> \SetNorthlakeEPSFSpecial + standard <==> \SetStandardEPSFSpecial %% (default!) + + %% Displacement Boxes (use at most one) + showboxes <==> \ShowDisplacementBoxes %% (default!) + hideboxes <==> \HideDisplacementBoxes + + %% Emulation of Rokicki's \epsfbox, \epsfxsize, \epsfysize + emulaterokicki <==> \EmulateRokicki + + %%% Typical (minimal) LaTeX example: + + \documentclass{article} + \usepackage[oztex,hideboxes]{boxedeps} + + \begin{document} + \begin{figure}\BoxedEPSF{gdisk.eps}\end{figure} + \end{document} + + +INTRODUCTION + + BoxedEPSF is a highly portable package for insertion of EPSFs +(Encapsulated PostScript Files) in TeX documents. It originated as +a fraction of a larger less portable package for several graphics +norms on the Mac (see BoxedArt.tex below) that was initially put +together for the GUTenberg special year for graphics, 1989. +BoxedEPSF was first posted in winter 1991, in response to Berthold +Horn's plea on the net in late 1990 for a standard for EPSF +integration, cf. his article in TUGboat 12 (1991) 377-381. The +use of bitmaps for preview is a technical obstacle to such a +standard and none has appeared since. BoxedEPSF is not the +standard he was calling for, but it seems to accomplish nearly as +much. + + PostScript is currently the unchallenged high performance +standard for electronic specification and typesetting of printed +graphics, while TeX is the unchallenged high performance standard for +the specification and typesetting of scientific manuscripts, minus +graphics. The convenient integration of PostScript graphics in TeX +manuscripts is clearly vital to the scientific publication process; +the BoxedEPSF package is a link in the integration chain. + + A PostScript printer is presumed to be the ultimate output device. +Is this an unfortunate restriction? In practice not; such is the +domination of PostScript printers. In addition, there are +increasingly computer based PostScript interpreters able to pilot +the screen and/or non-PostScript printers. (A new one +for Macintosh is T-SCRIPT tscript@teletype.com.) + + What of direct screen viewing? The Next-Step Graphical User +Interface (GUI) uses Display PostScript, an offshoot of +PostScript; no problem there. Another offshoot of PostScript is +PDF used by Acrobat viewers. Ghostview is a PostScript viewer +available on most unix workstations. The bigest chink in +PostScript's claim to universal acceptance is that only a tiny +proportion of GUIs exploit or even decently support PostScript. +Speed has been a stumbling block. Consequently, screen viewing of +PS graphics integrated in TeX frequently uses prefabricated +bitmaps as we shall further discuss below. + + + The main task of BoxedEPSF is to make EPSFs (Encapsulated +PostScript Files) behave for the TeX user like big characters or +boxes. In contrast, the \special command, the TeX primitive through +which such integration is normally accomplished, makes EPSFs behave +like dimensionless points. This is Knuth's recommendation, because +that permits TeX to typeset without any knowledge of the graphics +file. The box-like behavior is obviously more desirable from the +user's point of view. In the case of the EPSF norm, it is +attainable because TeX is clever enough to be able to read the EPSF +file to extract the dimensions of the bounding box of the graphics +object described. These are normally located in a comment line in +the header beginning "%%Bounding Box:" or better "%%HiResBounding +Box:". + + There are other packages that do the same essential job, +notably psfig of Trevor Darrell(1987), and T. Rokicki's "epsf.tex" +for his driver "dvips", but differences remain. This one is built, +above all, for portability and hence makes LOWEST-COMMON-DENOMINATOR +requirements on the driver. It does offer convenient adjustments +that others may not, eg. box trimming, and, above all, ready-made +adaptation to nearly all dvi-to-PostScript drivers. + + The basic requirement of BoxedEPSF is a "dvi-to-PostScript" +printer driver that for EPSF graphics implements in one way or +another Knuth's \special protocol. This \special should implement +scaling in some form since TeX cannot provide it. But translation +(=pushing the graphics around) can be done by TeX, which is +fortunate since some drivers (e.g. Textures' driver in versions <= +1.4 approx) do not bother to provide a \special command executing +translations. + + Until a standard for \special integration of EPSFs is well +established, BoxedEPSF will have to initialize the integration process +by using a driver-specific command of the form: \Set...EPSFSpecial (or +a corresponding LaTeX option in \usepackage[...]{boxedeps}). For +example, \SetOzTeXEPSFSpecial will initialize for the driver used by +OzTeX on Macintosh computers. (See a list of current alternatives +below.) This command can be put in the author's typescript header or +style file, but it is still better to put it in a configuration file +--- see mention of boxedeps.cfg below --- replacing +\Set...EPSFSpecial by \input boxedeps.cfg. + + Then, the primary command + + \BoxedEPSF{<filename> scaled <scale in mils>} + +scales by <scale in mils> the graphics object in the file <filename> +and inserts it at the current ".dvi" insertion point as a TeX box of +the dimensions of the bounding box scaled again by <scale in mils>. + + A tiny EPS test file gdisk.eps given below will let you run +trials. (Beware that many TeX screen previewers are still unable to +let you preview the graphics; but any printer of the PostScript norm +will let you run tests.) + + --- <filename> A file specification. This may be a simple +filename in case the file is in the default directory for TeX. + + More generally (but les portably!!), it can be a file pathname. +Better, one can separately specify the directory that will be the +directory in which TeX looks thereafter for simple EPSF names, by +typing + + \SetEPSFDirectory{<directory pathname>} + +For example, on a Macintosh, \SetEPSFDirectory{HardDisk:MyArtFolder:} +will direct TeX to the folder MyArtFolder of the volume HardDisk. And +\SetEPSFDirectory{:YourArtFolder:} will direct TeX to the subfolder +YourArtFolder of the directory that is the default directory for TeX. +Similarly for unix systems but with "/" in place of ":". + + Spaces in filenames or directory names are strictly forbidden +(usually already by TeX and drivers); this package gives a warning. + + For greater portability, please use in file names and directory +names only letters, digits, and perhaps one period ".". Beware of +conversions and confusions between upper and lower case letters. +Unix is case sensitive, but most other systems not; DOS even forces +to uppercase; while unix traditionally prefers lowercase. There is +a consensus that, for portability, lowercase letters only should be +used if at all possible, and failing that only uppercase. + + Also for portability, follow the DOS 8+3 rule: =< 8 +characters before an otioonal period and =< 3 after. To respect this +rule, public postings of BoxedEPSF, the macro file (for example) +bears the name "boxedeps.tex". + + [[To PC\DOS users: Slash / should replace backslash of the MSDOS +world, since backslash will upset TeX; if / does not work try \\.]] + + --- scaled <scale in mils> Optional. To conform to TeX syntax, +and avoid decimals most of the time, the scale is specified in mils +(=thousand'ths), rather than as a positive real number. (If you are a +precision freak, don't hesitate to add decimal parts of a mil.) + + If you specify no scale you get a default scale. This default +scale can be changed from its initial value of 1000 (for the rest of +the .tex file) by the command + + \SetDefaultEPSFScale{<scale in mils>} + + The scaling you select (however you do so) will always +be corrected by the TeX magnification factor. Thus if you select +scaling by 1000 mils at \magstep1 you in reality get scaling to 1200 +mils on the printed paper. + + There is a rather different way to specify scaling (championed +notably by Trevor Darrell since 1987); one can force width or height +to a specified dimension, by one (not both) of the commands: + + \ForceWidth{<dimen>} + \ForceHeight{<dimen>} + +This must precede the figure and normally applies to it alone. Any +such command takes precedence over any scaling command that might be +present. If you have two such commands, the last takes precedence. + + This forcing will persist indefinitely if you type + + \ForceOn + +and can then be stopped by + + \ForceOff + + There are some convenient uses of this "forced" dimensioning, for +example: + + a) To force neighboring figures to the same height or width. + + b) To maintain the exact same height for a figure through +minor revisions after TeX pagebreaks have been fixed. + + c) Artists may rescale their originals when they revise; +this will not affect the user if "forced" dimensioning is used. + +Incidentally, note that \ForceWidth{0.66\hsize} is perfectly +legitimate; similarly for all dimension specifications. + + On the other hand, scaling is the only right approach if you +have a well proportioned line diagram with included labelling of a +known point size. You scale to make the labels of about the same +size as that of the printed text. + + In actual practice, the "BoundingBox" posted in the EPSF is more +often than often not far from what it should be, namely the least +rectangle containing the ink that will print the graphic object; it +tends to be somewhat larger. Thus, the \Trim... commands described +below are provided to optionally correct the box to fit the object. +Since such corrections require the human eye and some trial and error +it is reasonable to cast about for tools that will instead +automatically correct "BoundingBox" marked in the EPS file. (See for +example the keywords ghostscript ane bb4gs.ps.) + + For diagnostic purposes, one has: + + \ShowDisplacementBoxes, \HideDisplacementBoxes + +to show (with a black frame), respectively hide, the corrected scaled +and positioned bounding boxes. The physical term "displacement" is +used to remind you that these are boxes that displace other boxes, like +TeX character boxes (see the TeXbook Chap 11), or indeed any TeX box. +In case you make the graphics neatly fit into this displacement box the +term "bounding box image" would be justified, but just as for TeX +characters, this is not always how things work out (cf. TeXbook p.63). + + For the sake of users who do not have preview of their EPSFs +the default has been set to \ShowDisplacementBoxes. It is +demoralising to beginners to see nothing at all! + + Before any individual \BoxedEPSF{...} command, one can insert +commands to adjust the bounding box: + + \TrimBoundingBox{...} + \TrimTop{...} + \TrimLeft{...} + \TrimBottom{...} + \TrimRight{...} + + Each such command takes a percentage argument as in + + \TrimTop{5pct} + +This means to trim off of the top of the BoundingBox five percent +of its height. One must not forget the percentage units +specification "pct". Indeed it is equally OK to specify a +TeX dimension unit: pt, bp, cm, etc. For example + + \TrimLeft{15bp} + +trims 15 big points (PostScript units) off of the left side of the +original BoundingBox (not the image on paper). + + Both percentage and dimension units remain valid if the user +subsequently changes scale on paper. + + The use of percent units is the best choice. Typically the user +sees a scaled image and so cannot perceive dimensions on the art +source file. Also, percentage specifications will remain valid if the +artist changes the scale of his source. In practice, even the user may +want to dramatically increase the source file scale to enhance the +precision of bitmapped previews supplied automatically by an art +program such as Adobe Illustrator, or he may reduce scale to make the +bitmaps smaller. + + The names of these trimming commands say what they do; note +that they do NOT mask off part of the object when the box becomes +too small; thus trimming is NOT is commonly referred to as "clipping". + + + TeX is pretty good at shunting boxes around. But the command to +*slide* an image around without changing its displacement box nor +shunting neighboring boxes is not readily accessible. So we provide: + + \hSlide{...} + \vSlide{...} + +which respectively slide horizontally to the right and vertically down +in dimension units of the TeX page, NOT the artist's page. + + + A good order of steps for implanting a graphics object is to trim +using percentage units, then scale, and finally, slide, or shunt using +TeX tools. + + + By default, the box is produced vertically "centered" using \vcenter. +This seems most agreeable in case of linefigures in text --- though +mostly it does not matter. The "height" mentioned above is the sum of +the height and the depth of this box (with rare exceptions mentioned +immediately below). + + The two other obvious choices of baseline are also available: + + --- \tBoxedEPSF{...} baseline at top as for washing hanging on a +clothesline. + + --- \bBoxedEPSF{...} baseline at bottom as for trucks on a highway + + The default choice is + + --- \cBoxedEPSF{...} baseline centered as for khebabs on a skewer. + +More precisely, it is centered on the "axis" of mathematics in prose, +which for computer modern ten point system is 2.5pt above the +baseline; this makes \cBoxedEPSF very convenient for insertion of +small "linefigures" in prose; for example, $\left(\BoxedEPSF{mylinefig +scaled 300}\right)$ should neatly fit "mylinefig" between parentheses. + + Beware, however, that TeX's refusal of negative heights or depths +for boxes leads to surprising results with \cBoxedEPSF when very tiny +linefigures occur (so tiny they do not reach the baseline). For example, +if the scaling is zero, the height is the math axis height, and the depth +is zero! If such extreme cases interest you, experiment with \hrule +\cBoxedEPSF{myfig scaled 0} \hrule. No such subtleties occur with +\tBoxedEPSF and \bBoxedEPSF! + + You can change the default behavior to "baseline at top" (for example) +by the command + + \let \BoxedEPSF=\tBoxedEPSF + + + + ****** Some file trickery ****** + + (A) The first trick is standard; if several authors on different +platforms are collaborating on one TeX typescript, each should use +boxedeps.cfg to specify the DVI-to-PS driver and not a command +\Set...EPSFSpecial Then provided each +author preserves and protects his boxedeps.cfg all other parts of the +".tex" typescript can be maintained identical for all authors. + + (B) The following comments respond to requests and suggestions of +Douglas Gray-Stephens <gray@SCR.SLB.COM>. + + Ad hoc user-macros can perform file searchs that might at +first sight seem beyond the scope of BoxedEPSF. + + 1) Graphics objects to be reused can be macros and they need not be in +a specific directory. Since \SetEPSFDirectory respects TeX grouping, +one can set out a definition as follows: + + \def\ourlogo#1{\bgroup\SetEPSFDirectory{<logopathname>}% + \BoxedEPSF{<logoname> scaled #1}\egroup} + +Then one inserts the boxed logo using \ourlogo{<scale>}. The directory +for EPSFs (if any) is momentarily changed but is the same before and +after \ourlogo{<scale>} is used. + + If just a few graphics objects are to be reused often, economy +and speed are best assured by storing the graphics object is a TeX box. +Suppose for example that a logo is to be used on each page. Then one +can prepare the box by + + \newbox\logobox + \bgroup\SetEPSFDirectory{<logopathname> + \global\setbox\logobox=% + \hbox{\BoxedEPSF + {<logo file name> scaled <scale in mils>}}\egroup + \gdef\Logo{\copy\logobox} + +Thereafter, \Logo places the logo very quickly and can be reused +at no extra cost to TeX. + + 2) It is possible to use simultaneously several graphics directories by +further exploiting TeX grouping. Suppose, for example, that one wants +an extra directory <graphpath> for scientific graphs. Then one can +define \BoxedGraph behaving just like \BoxedEPSF but always using +directory <graphpathname>, as follows: + + \def\BoxedGraph#1{\bgroup\SetEPSFDirectory{<graphpathname>}% + \BoxedEPSF{#1}\egroup} + +\BoxedGraph is insensitive to occurences elsewhere of \SetEPSFDirectory. + + 3) A useful special case of this approach gives a "wildcard" macro: + + \def\BoxedEPSFx#1{\bgroup\SetEPSFDirectory{}% + \BoxedEPSF{#1}\egroup} + +(This of course assumes one has used or will use +\SetEPSFDirectory{<pathname>}, for otherwise \BoxedEPSFx will behave +much like \BoxedEPSF.) One can use either "full" or "relative" file +specifications in + + \BoxedEPSFx{<filespec> [scaled <scale>]} + +Here "full" means no separator out front, and "relative" +means separator out front. The separator is the character "/" for +unix or PC and ":" for Macintosh. In the relative case, your current +directory behaves as root; normally, this is the directory of +the .tex file you launched. + + Example for the Macintosh: + + \BoxedEPSFx{:art:monalisa.eps} + +This searches in "art" a subdirectory of the default directory +for an EPS file called monalisa.eps. + + + + ****** Selecting PostScript printer drivers ****** + + The obstacle to portability is a lack of standard syntax for +the \special commands; they vary from driver to driver. This is +overcome by using a local standard "fake special" within boxedeps.tex, +and relating each driver to it. + + This local BoxedEPSF standard is a two-argument macro + + \EPSFSpecial#1#2 + +where #1 is <file spec> and #2 is <scale in mils>. A different +definition is given for each driver. For example, for Textures, the +user types (in his article header or in boxedeps.cfg): + + \SetTexturesEPSFSpecial + +and this package then institutes essentially the definition: + + \gdef\EPSFSpecial#1#2{\relax + \special{postscriptfile #1 scaled #2}}% + +Actually, it is not quite that simple, because we allow decimal +scaling factors like 726.7 (mils) while Textures <=1.6 required integer +values. + + Definitions for most known drivers are provided: + + %% \SetepsfEPSFSpecial %% ******* will work for many: + %% ----- dvips, the Y&Y drivers, DirectTeX, CMacTeX, OzTeX>=1.7 + %% \SetEPSFMultiSpecial %% ******* may work for more + %% \SetTexturesEPSFSpecial %% Textures + %% \SetUnixCoopEPSFSpecial %% dvi2ps early unix + %% \SetNiponUnixEPSFSpecial %% dvi2ps j-version + %% \SetBechtolsheimDVI2PSEPSFSpecial and + %% \SetBechtolsheimDVITPSEPSFSpecial %% by S.P.Bechtolsheim + %% \SetLisEPSFSpecial %% dvi2ps by Tony Lis + %% \SetRokickiEPSFSpecial %% dvips by Tom Rokicki + %% \SetDVIPSoneEPSFSpecial %% DVIPSONE of Y&Y same as + %% \SetDVIWindowEPSFSpecial %% DVIWindow of Y&Y + %% \SetDirectTeXEPSFSpecial %% DirectTeX by Wilfried Ricken + %% \SetCMacTeXEPSFSpecial %% CMacTeX by Tom Kiffe + %% \SetOzTeXEPSFSpecial %% OzTeX (>=1.7) by Andrew Trevorrow + %% \SetOldOzTeXEPSFSpecial %% OzTeX (1.42--1.6x) + %% \SetPSprintEPSFSpecial %% PSprint by Andrew Trevorrow + %% --- also for OzTeX versions <= 1.41 !! + %% \SetArborEPSFSpecial %% ArborTeX DVILASER/PS + %% \SetClarkEPSFSpecial %% dvitops by James Clark + %% \SetBeebeEPSFSpecial %% DVIALW by N. Beebe + %% \SetNorthlakeEPSFSpecial %% Northlake Software + %% \SetStandardEPSFSpecial %% Nonexistant: Placebo used + +and others will be on request --- see appendix. + + -------------------- + + OzTeX note June 1994: OzTeX 1.7 revised its \special for +EPSF insertion to place the lower left corner of the bounding box +at the TeX insertion point; \SetOzTeXEPSFSpecial is revised in +consequence. Users of OzTeX versions 1.4.2 to 1.6 must now either +update to OzTeX1.7, or use \SetOzTeXEPSFSpecial\PSOrigintrue or +\SetOldOzTeXEPSFSpecial in place of \SetOzTeXEPSFSpecial. Otherwise +the updated boxedeps.tex will badly misplace EPSFs. + + Since OzTeX's own \special syntax has changed so often, +where archival ".tex" files are involved, consider using +\SetepsfEPSFSpecial based on a stable syntax of Rokicki; this will +work with OzTeX in versions >= 1.7. + + -------------------- + + + ****** Compatibility with T. Rokicki's integration package ****** + + For users of Rokicki's integration package epsf.tex +attached to his DVI-to-PS driver dvips, we support the following +alternative syntax. + + \EPSFbox or \EPSFfile equivalent to \bBoxedEPSF. + \EPSFxsize=126pt equivalent to \ForceWidth{126pt} + \EPSFysize=76pt equivalent to \ForceHeight{76pt} + +This compatibility makes it straightforeward to move a manuscript +prepared with the most basic features of epsf.tex to a TeX site with +any other driver. + + Rokicki uses all-lowercase commands (epsf for EPSF); hence +his epsf.tex can be loaded along with boxedeps.tex without +conflict. If, on the other hand, you want BoxedEPSF to accept the +lowercase syntax and execute the three commands in place of +epsf.tex, you can type \EmulateRokicki. + + The (undocumented) \special syntax of dvips employed by +epsf.tex has gradually become widespread in other drivers; it is +this syntax on which \SetepsfEPSFSpecial above is based. + + -------------------- + + + ****** Known Problems ****** + + 1) The process of reading bounding boxes may prove annoyingly slow +on smaller computers when inserts are numerous. This problem will +be lessened if you can make the "BoundingBox" comment one of the +first in each PostScript file. The larger BoxedArt.tex package for +Macintosh users provides a complete cure through use of a "graphics +specification file", which can be read quickly. + + 2) TeX permanently uses up the string space needed to record the +(full) name of each EPS file it opens. If you are short on string +space use succinct EPS file names like F1, F2, ... and put your TeX +file in your graphics directory to make the default directory +coincide with the graphics directory. Then \BoxedEPSF{F1} will use +up just two string characters. + + 3) Early Textures problem (not in versions >=1.4??): PostScript +files that have a resource fork may upset the Textures driver. +Typically, nothing after the figure will print. This can be cured +by deleting the resource fork. For a PostScript file of +Illustrator88, the preview graphics are in a PICT resource; try +deleting all resources EXCEPT this PICT. + + 4) A common driver problem: EPS files seldom include the +PostScript fonts they need. Usually this does not cause a problem, +because (hopefully) the required font is already present in the +printer, or at least will be downloaded to the printer for the job +in which the EPSF is embedded. + + However, if necessary the driver should attempt to locate and +include the fonts needed. Unfortunately, few do. (Textures >= 1.7 and +DVIPSONE are admirable exceptions.) The *user* is then obliged to +intervene to assure the presence of the fonts. Fortunately an EPSF +header comment + + %%DocumentFonts: ... + +usually tells exactly which fonts are needed. Here are two +ways to download them: + + (a) Use a utility to download the fonts before the printing job is +run. (For Macintosh look for the name "LaserWriter [Font] +Utility".) + (b) Artificially employ in the TeX manuscript all the fonts +required for the EPS file; they are listed in the header. To +avoid adding an extra page to the output one can have the extra +material printed off-page using say + + \rightlap{\smash\hbox{\kern\hsize <text using fonts for EPSFs>}} + +This approach (b) makes the TeX document portable without special +instructions. However (b) sometimes fails; for example if the EPS +file uses CM/PS type1 Adobe fonts while the main text uses CM fonts of +the classical metafont sort. + + (c) Where figure labels are concerned, one can usually outright +avoid this font inclusion problem by puting the labels in a TeX +overlay, using, for example, the utility "labelfig.tex" +(often posted as a companion to boxedeps.tex). + + Laurent Siebenmann + Mathematique, Bat. 425, + Univ de Paris-Sud, + 91405-Orsay, + France + + lcs@topo.math.u-psud.fr + + + Fax number: 33-1-6941-6348 + + + REFERENCES + + The following may give you leads to alternative solutions. + + --- PSFIG a package by Trevor Darrell (for at least two drivers) +available by anonymous ftp from whitechapel.media.mit.edu +(18.85.0.124) in ./psfig or linc.cis.upenn.edu (130.91.6.8) in the +directory ./dist/psfig. + + --- Merging PostScript Illustrations: Gerald Roylance 1987, 1989, +see MIT AI Laboratory Working Paper 299a; this package supports dvi2ps +and DVILASER/PS. + + --- dvips and epsf.tex by by T. Rokicki <rokicki@Neon.Stanford.EDU> + + --- Une meilleure integration du graphisme Macintosh, par Laurent +Siebenmann, Cahiers GUTenberg, No. 4 (Dec 1989), pages 29-38. The +native Macintosh grapics norm is called PICT. TeX has not been able to +read PICT resources and files, as the resources are not files and the +files are "binary". Nevertheless, good integration under Textures (and +subsequently other Macintosh TeX implementations) has become possible +with the help of a preprocessor "ArtDealer" and the notion of a +"graphics description file". The strong points of this approach are +speed and compactness. Portability poses some problems. These ideas are +implemented by the parallel package consisting of BoxedArt.tex, +BoxedArt.doc, and ArtDealer available (hopefully) from the same sources +as this package. + + --- Nicolas Jungers <EDITEX@BUCLLN11.BITNET> two postings in the +GUTenberg forum <GUT@FRULM11.BITNET> 9 Nov 90 and 17 Nov 90. [A good +"do-it-yourself" kit!] + + --- Michael Ferguson <mike@inrs-telecom.uquebec.ca> espouses the +\ForceHeight{...} approach in Cahiers GUTenberg, No. 3 (May 1989); for +many drivers, it does not require TeX to read the EPS file. N. Beebe +indicates that his macros are available for DVIALW. + + +APPENDIX: A FIRST QUICK TEST OF BoxedEPSF + + Hopefully you have found your PostScript printer driver in the +above list of \Set...EPSFSpecial commands. In that case, try the +following test to check that this package is working + + ------ cut here + + %%%% test.tex for Plain TeX; by puting + %% everything from \input to ZZ into the middle of a LateX file. + + \input boxedeps.tex + \Set...EPSFSpecial %%%% complete this line!!!!!!!! + \ShowDisplacementBoxes%\HideDisplacementBoxes %%alternatives + \null\vfill\vfill + AA\BoxedEPSF{gdisk.eps scaled 500}ZZ + %% lower case "8+3" convention for file names + \bye + + %%%% test.tex for LaTeX (2e) + \documentclass{article} + \usepackage[standard,showboxes]{boxedeps} + %% change "standard" to indicate your PostScript printer driver + %% or omit and rely on boxedeps.cfg configuration + %% showboxes --> hideboxes for final version + \documentclass{article} + \usepackage[oztex,hideboxes]{boxedeps} + + \begin{document} + \begin{figure}AA\BoxedEPSF{gdisk.eps scaled 500}ZZ\end{figure} + \end{document} + + ------ cut here + %!PS-Adobe-2.0 EPSF-1.2 + %%Title: gdisk.eps + %%Remark: A simple test file + %%Remark: DELETE SPACES BEFORE ALL %% (especially for Textures) + %%Pages: 0 + %%BoundingBox: 216 216 432 432 + %%EndComments + + 72 72 scale % units are now inches instead of big points + newpath + 4.5 4.5 1.5 0 360 arc + closepath + 0.9 setgray + fill + + ------ cut here + + The files test.tex and gdisk.eps should be in the same +directory. + + A grey disk should appear fitting snuggly between AA and ZZ. +It should be neatly bounded by a square (the displacement box). + + Once this test is working you should be able to elaborate and +test all features. + + If it does not work, examine the TeX log for helpful +comments. + + If the one fault is that the box is blank on printing, test +settings for other drivers. In case you have no clue about your +printer driver, a sequence of commands of the form + +\Set...EPSFSpecial \string\Set...EPSFSpecial +\vfill\vfill + AA\BoxedEPSF{gdisk.eps scaled 500}ZZ\vfill\eject + +will conveniently try out *all* possibilities in a single TeX run. + + + APPENDIX: HOW TO GET SUPPORT FOR YOUR DRIVER + + To get support for your dvi to PostScript printer driver, +please send the \special syntax required to insert a file myfile.eps +with scaling 76 percent! + + For example, the answer for the ArborText DVILASER/PS driver +was: + + \special{ps: epsfile myfile.eps 760} + +And that was (almost) enough to let me program \SetArborEPSFSpecial. + + One more scrap of information is essential. Some \special's +for EPSFs place the lower left corner of the (scaled) bounding box at +the TeX insertion point, and others place the lower left corner of the +artist's page at the insertion point. No other choice seems consistent +with Knuth's recommendations in the TeXbook. Textures and ArborTeX +belong to the first type, while OzTeX (versions <=1.6x) and Rokicki's +dvips belong to the second. The first type of driver must read the +"bounding box comment" in the EPS File header. Please report on the +basis of documentation and/or experimentation, which type is in +question. An experimental test routine is provided below. + + In general, some testing and/or driver documentation may be +needed to clear up lingering questions. For example, are decimals +allowed in in the scaling specification? For ArborTeX I believe the +answer is no. + + An information form is included below for those who would like +to see BoxedEPSF adapted to another driver. + + + APPENDIX: AN INFORMATION KIT FOR OTHER DRIVERS + + -------------------------------cut +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + %%% spectest.tex for Plain TeX + %%% Test to discover which point in + % the graphics page (plane) your \special + % command distinguishes and identifies to + % the TeX insertion point. + % + % --- Put the file gsquare.eps into the same folder as + % TeX and this testfile. Hopefully this will make + % gsquare.eps accessible to the printer driver. + % + % --- Complete the \special{... gsquare.eps ...} command below + % as your driver documentation recommends for printing + % the EPSF gsquare.eps --- without any scaling, or other + % refinement. For example + % \special{ps: epsfile gsquare.eps 1000} + % is suitable for the ArborteX driver. + % + % --- Typeset this file + % + % --- Print the resulting .dvi file using your driver. + % + % INTERPRETATION: + % + % If the black box lies in the square, the + % distinguished point is the lower, left-hand corner of the + % PostScript bounding box. + % + % If the black box lies outside the square, the + % distinguished point is the lower, left-hand corner of the + % artist's page, i.e. the the PostScript origin. + % + % If the square is missing, your driver has probably not found + % the EPS file gsquare.eps, or you have formulated the \special + % command incorrectly. Follow driver instructions more + % carefully. + % + % --- report results to Laurent Siebenmann + % <lcs@topo.math.u-psud.fr> + % on the special reply "reply.doc" form provided below. + % + % + + \null + \vfill + \vskip -1 in + \moveright 1 in \vbox{\hrule height 1 in width 1 in} + \vskip 1 in + \special{... gsquare.eps ...}%% please carefully adjust this + \eject + \bye + + %% end of spectest.tex + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + -------------------------------cut +%!PS-Adobe-2.0 EPSF-1.2 + %%Title: gsquare.eps + %%Remark: Another simple test file + %%Remark: DELETE SPACES BEFORE ALL %% (especially for Textures) + %%Pages: 0 + %%BoundingBox: 216 216 432 432 + %%EndComments + + 72 72 scale % units are now inches instead of big points + + newpath + 3 3 moveto + 3 6 lineto + 6 6 lineto + 6 3 lineto + closepath + 0.8 setgray + fill + + -------------------------------cut +%!PS-Adobe-2.0 EPSF-1.2 + %%Title: heat.eps + %%Remark: Another simple test file + %%Remark: DELETE SPACES BEFORE ALL %% (especially for Textures) + %%Pages: 0 + %%BoundingBox: 216 216 432 432 + %%EndComments + + 72 72 scale % units are now inches instead of big points + newpath + 4.5 4.5 1.5 0 360 arc + closepath + 0.9 setgray + fill + + /Times-Italic findfont + .8 scalefont + setfont + 3.75 4.3 moveto + 0 setgray + (Heat) show + + -------------------------------cut + + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + %%% reply.doc %%% + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + INFORMATION FORM for adaptation of BoxedEPSF + to other "dvi-to-PostScript" printer drivers + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + Please provide information on the following items: + + --- Name and email address(es) of correspondent. + + --- Driver information: Name, version, date, copyright, vendor, +computer(s) served, price etc. + + --- Syntax required to print the EPS File gsquare.eps scaled to +76 percent using a command of the form \special{... gsquare.eps +...}. Is scaling to exactly 76.33 percent available? + + --- More info on \special. + + --- Location of the distinguished point. (Report result of test +in spectest.tex above). + + --- Source(s) of your EPSFs. + + --- Do you progam TeX? PostScript? + + A trial adaptation to your driver will be returned with +an update of BoxedEPSF. Thank you for cooperating! + + Laurent Siebenmann + Mathematique, Bat. 425, + Univ de Paris-Sud, + 91405-Orsay, + France + + lcs@topo.math.u-psud.fr + + Fax number: 33-1-6941-6348 + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + -------------------------------cut + + + + APPENDIX. HOW ARE THE EPS GRAPHICS FILES BEING CREATED? + + While everyone admires PostScript graphics, few TeX users are +entirely happy with their tools for producing the EPSFs. As soon +as your integration problem has been disposed of, this one will be +back to haunt you! Here are a few notes that may help. + + a) Illustrator on the Mac by Adobe Corp is a MacDraw-like program +that uses the EPSF norm. It is favored by professionals since it is +geared for highest quality output. + + b) DrawOver 1.0 copyright Michael Everest 1986, is a converter to +EPSF from the PICT graphics norm of the Macintosh, a norm for which +there are many excellent drawing programs such as MacDraw. It was +distributed with Illustrator 88 on the Mac. To get preview, and +sometimes even to print, its output has to be "validated" by passage +through Illustrator. The original DrawOver is aging inasmuch as it +handles the PICTs of more recent MacDraw versions less and less +well. One does best by using PICT files (re)generated by MacDraw +versions anterior to MacDrawII. Illustrator 3.0 included an +updated DrawOver. From Adobe, there is also a converter Streamline +for PICT, TIFF and MacPaint files. + + c) LaserWriter >= 8.1.1 of 1994 provides an option to "print" +almost any graphics objects to file of EPSF type. This approach +probably going to become the dominant one for Mac users. It has been +available on ftp.apple.com in directory dts and is distributed with +Systems >+ 7.5. Some bugs remain to be eliminated. In a pinch consider +converting the more reliable "PS job" files to EPSF form using bb.ps +or bb4gs.ps as described below. Pioneering users should be sure that +the graphics object well within the page being used; one way is to +use an big page as provided say by the Agfa printer configuration +file. + + d) fig and xfig by Micah Beck, Cornell University +<beck@cs.cornell.edu> are MacDraw-like programs for unix and unix +X-windows, for which a translator transfig exists to EPSF norm. + + e) Naked PostScript code. PostScript is a beautiful language, and the +three Adobe manuals are very helpful. + + f) Aldus Freehand on the Macintosh: see Berthold K.P. Horn's +comments below; cf Aldus Intellidraw below. + + g) Canvas (Denaba Software) on Macintosh in versions from 1991 +(3.0) on will have the ability to save a file in EPS format (and +also PICT and Illustrator 88 formats etc., the most impressive list +so far). + + h) Classic MacDraw, MacDraw Pro, indeed all versions from 1991 of +MacDraw on Macintosh, on will hopefully have the ability to save a +file in EPS as well as PICT format. At the same time Apple is +producing more and more non-PostScript printers... + + i) CricketDraw and CricketGraph + + ***************************************** + + Several users have kindly extended and updated the above list! + + Berthold K.P. HORN mentioned many possibilities: + +(*) Aldus Freehand on the Mac is a more sophisticated tool for +generating graphic illustrations than Adobe Illustrator. Both are +constrained to basically two-dimensional patterns. Both can +produce output in EPS form. [[See the "export" menu item, and use +the simple or Mac version of EPS format, not the IBMPC version that +yields a partly binary file. The Mac version includes a PICT +resource containing a bitmap visible in the Textures or OzTeX preview. +Aldus Freehand freehand also imports PICT resources via the Mac +clipboard, and this provides an interesting alternative to +DrawOver. This conversion sometimes handles MacDrawII PICT +files better than DrawOver. Freehand, unlike Illustrator, has +its own binary file format.]] + +(*) Micrografx Designer on the PC is a more sophisticated tool for +generating graphics illustrations than Adobe Illustrator. It is the +PC's answer to `MacEnvy', since it provides a Windows based tool that +is about as good as any on the Mac. Designer is also constrained to +basically two-dimensional patterns. It can produce output in EPS +form. + +(*) There are also CAD/CAM applications that run on high end PC's, Sun +workstations that can handle `solid modelling' of three dimensional +objects, but they are an order of magnitude more expensive, so few +people have access to them. + +(*) Illustrate on the Symbolics LispMachine was one of the first +drawing programs and is still used quite a bit. It can produce output +in EPS form. Very similar features to the other 2-D illustration +applications mentioned above. + +(*) Screen Dumps. Another useful source of graphic illustrations are +screen dumps available on LispMachine, Windows on PC, and on Mac in +EPS form. OF course, they are in bitmap form so very limited in +quality and not resolution-independent, but useful for illustrating +program operations. + +(*) Paint Programs. On the Mac and the PC there are programs that +instead of manipulating curves and areas work directly with bitmaps. +The output can be in EPS form. But same drawback as screendumps. Not +used much. + + Max CALVIANI <fisica@astrpd.unipd.it> mentions + +(**) Mongo or Supermongo ... superb ... produce a .ps file ... on +vax/vms, also under Unix. They are copyrighted, Mongo costs approx +500 USD, SuperMongo only 250 USD. + + Antonio POSSOLO in Seattle <antonio@atc.boeing.com> makes +recommendations for unix: + +An excellent tool to generate postscript figures in Unix is the S +programming environment for data analysis and graphics, +originally from AT&T Bell Labs, and S-PLUS, a superset [of S] +from Statistical Sciences, Inc. (Seattle, Washington, USA). This +is not a drawing tool in the sense of Adobe's Illustrator, or +MacDraw: instead, it is driven by issuing drawing commands. S is +described in R.A. Becker, J.M. Chambers, & A.R. Wilks (1988) +"The New S Language", Wadsworth & Brooks/Cole, and you will find +there many examples of its capabilities to produce beautiful +pictures (note the postscript() command, in particular, as means +to generate postscript output). + +============================= +Aldus (now Adobe) Intellidraw +(report by Alun J. Carr <ajcarr@ccvax.ucd.ie> Nov 1995) + +An excellent cross-platform (Mac and Windows) drawing package. It is +extremely flexible, if a little non-intuitive at times, and is capable of +producing top quality illustrations. On the Mac, Intellidraw can import +PICT, TIFF, and EPS graphics, although only the PICT variety are editable +in the program. Similarly, it can export in a few formats: PICT, EPS, +Illustrator 88, and Illustrator 1.1. I highly recommend this application, +particularly at its low price (less than 150 Irish pounds when I bought +version 2). + +============================= +A hint on generating EPS from Cricket Graph III on the Mac +(report by Alun J. Carr <ajcarr@ccvax.ucd.ie> Nov 1995) + +Using LaserWriter 8.3, printing to an EPS file from Cricket Graph produces +a very wrong BoundingBox. I have found that the following approach produces +an excellent EPS file: + +1) In Cricket Graph `Save As...' a PICT. + +2) Change the creator of the PICT to ttxt (I use Type Resolve 2.0.1, which +is a very handy drag-and-drop utility). + +3) Open the PICT file in SimpleText (Apple's current TeachText replacement). + +4) Print to an EPS file using the LaserWriter 8.3 driver. + +The bounding box is very close to being correct (usually within a +millimetre or two), and the Postscript code is of high quality and very +standard. + + + + **************************************** + + +Determining Bounding Boxes via bb.ps and bb4gs.ps + + Many postscript files originally created without regard to +EPSF standards will successfully function as EPSFs if they are +provided with a suitable Bounding Box comment in the header. Ned +Bachelder has distributed a PostScript "header" file bb.ps since 1990 +(modified by Bernie Cosell <cosell@bbn.com>) that will cause a +following Postscript file to have its bounding box marked +numerically and graphically on printing. + + William L. Kath <kath@nwu.edu> has distributed a +version modified for ghostscript (see below) called bb4gs.ps; it +is included in the unix ghostscript distribution. + + +Ghostscript. + + These computer-based Postscript interpreters with +electronic rather than physical output were initially programmed by +Peter L. Deutsch, and have become of increasing interest for TeX +preview. + + Ghostscript's public FTP site for all platforms is: +ftp.cs.wisc.edu in the directory: /pub/ghost. + + These Postscript interpreters are certainly of great +interest for PostScript programming. + + The preparation of preview bitmaps for EPSFs is +another important use. + + The frustration engendered by using PostScript graphics +without preview has been major obstacle to the use of PostScript +with TeX. The Adobe standard for Macintosh previewing of +encapsulated PostScript graphics is part of the EPSF standard +available from ftp adobe.com, and involves addition of a bitmap as +a PICT resource number 256. [There is a variant for PC supported by +DVIWindo of Y&Y and by DVIWin (on CTAN).] + + +Building Macintosh Preview for EPSFs. + + [Similar remarks apply to PC's under MSWindows.] + + There is shareware utility called epsConvert by Sam Weiss +1993-- (currently $25, Artemis software). It will convert many EPS +files to a format valid for Adobe Illustrator, which in turn will +provide the PICT bitmap preview. In conjunction with LaserWriter >= +8.1.1, it will also provide vectorized PICT resource preview. + + Ghostscript can be adapted to provide the PICT resource +just mentioned (and Bounding box comment) in a mechanized way. +(Is batch mode still missing? And automatic BoundingBox +insertion on demand?) + +PS2EPS+ by Peter Lerup <ptl@automation.alfalaval.se> + (reported by Alun J. Carr Nov 1995) + +This is a freeware application for the Mac, available from any +Info-Mac mirror in the directory /gst/grf/ under the name +ps-to-eps-plus-10.hqx. It uses Peter Lerup's own Mac port of +Ghostscript (v2.5) to interpret EPS files that have no preview, +and it then allows a PICT preview to be attached in Mac or PC +preview format, and also for the image to be saved separately as +a PICT or TIFF graphic. A very handy tool. + + -------------- + + +SOMMAIRE FRANCAIS: boxedeps.tex d'efinit des macro-commandes + qui permettent d'int'egrer dans un document TeX des + objets graphiques de norme EPSF, tout en accordant + `a chacun le statut d'une bo^ite TeX ayant + les bonnes dimensions. La contribution principale + de cet utilitaire est de faire cela d'une fa_con universelle, + c'est a dire de fa_con `a pouvoir commod'ement + servir avec tout pilote d'imprimante de norme + PostScript --- malgr'e l'absence d'une norme + pour \special. + + |