diff options
Diffstat (limited to 'macros/generic/boxedeps/boxedeps.doc-old')
-rw-r--r-- | macros/generic/boxedeps/boxedeps.doc-old | 1107 |
1 files changed, 1107 insertions, 0 deletions
diff --git a/macros/generic/boxedeps/boxedeps.doc-old b/macros/generic/boxedeps/boxedeps.doc-old new file mode 100644 index 0000000000..d202bfa8c9 --- /dev/null +++ b/macros/generic/boxedeps/boxedeps.doc-old @@ -0,0 +1,1107 @@ +%%%%% boxedeps.doc + %% + %%% 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 (4-95): + %% * High resolution bounding boxes are used when available. + %% * Log file epsf.lst reports epsf files integrated; + %% use it as an inventory for exporting. + %%%% 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 --- + + +SYNOPSIS + + BoxedEPSF lets one integrate Encapsulated +PostScript Files (EPSFs) into TeX documents by making them +behave as TeX boxes --- using the following commands: + + \input boxedeps.tex %% lower case "8+3" convention for file names + \Set...EPSFSpecial %% e.g. \SetOzTeXEPSFSpecial + \BoxedEPSF{<filename> scaled <scale in mils>} + \tBoxedEPSF{...} + \bBoxedEPSF{...} + \cBoxedEPSF{...} + \EPSFbox{...} + \EPSFfile{...} + \EmulateRokicki + \ShowDisplacementBoxes + \HideDisplacementBoxes + \SetEPSFDirectory{<directory pathname>} + \SetDefaultEPSFScale{<scale in mils>} + \ForceWidth{<dimen>} + \EPSFxsize=<dimen> + \ForceHeight{<dimen>} + \EPSFysize=<dimen> + \ForceOn + \ForceOff + \TrimTop{<dimen>} + \TrimLeft{<dimen>} + \TrimBottom{<dimen>} + \TrimRight{<dimen>} + \TrimBoundingBox{<dimen>} + \hSlide{<dimen>} + \vSlide{<dimen>} + +This list can serve to locate details by string search. +The user should promptly familiarize him/her self with the left +alligned commands; the indented ones are less used. + + +INTRODUCTION + + BoxedEPSF is a highly portable package for insertion of +EPSFs (Encapsulated PostScript Files) in TeX documents. It is 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 Bert +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 Bert 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. +BoxedEPSF is a link in the integration chain. + + 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 should be easy to understand to the +point that with a bit of luck, a texpert will be able to port it to a +new driver in a few hours. It does provide a few useful things +that others may not, eg. box fitting, and, above all, ready-made +adaptation to nearly all dvi-to-PostScript drivers. + + It is well known that, in a spirit of self reliance, texperts +tend to do adhoc programming to integrate their graphics. See for +example N. Jungers' <ANORSU@BUCLLN11.BITNET> posting on the +GUTenberg bulletin board dated 17 November 1990 for a good +explanation of the principles. A bit of understanding of TeX and +PostScript programming can go a long way. If this is your +inclination, perusal of Trevor Darrell psfig package is also highly +recommended. + + It seems to me there is room for packages which require no +tinkering with any programming language --- whether it be for +everyday use or for porting --- even at the cost of being heavier. +Most users have neither time nor taste for more adventurous +approaches. + + 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) 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 be initialize the integration +process by using a driver-specific command of the form: +\Set...EPSFSpecial. 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). + + 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 EPSF test file gdisk.eps given below will let you run trials. +(Beware that in 1991 many TeX screen previewers are unable to let you +see 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, 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, 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 only lowercase letters should be used +if at all possible, and failing that only uppercase. Thus all public +postings of BoxedEPSF the macro file should bear the name +"boxedeps.tex". + + [[To experts: On an experimental basis, current versions of +BoxedEPSF are a bit more liberal in allowing five punctuation marks +punctuation: :,;?! and also any character that has catcode 11 +(=letter) or 12 (=other). The backslash is used as a directory separator +in the PC world; thus BoxedEPSF lets one use backslash provided +backslash is coded as \\ inside the arguments of \SetEPSFDirectory{...} +and \BoxedEPSF{...}. I have been told that the slash / can +often replace backslash in the MSDOS world, so this backslash feature +may not be essential. This \\ is of course a marco; one can +hopefully use other TeX macros in these arguments provided they +expand under \edef without mishap.]] + + --- 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 + + As W. Neumann pointed out to me, there are some unique uses for +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. + +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 optimal size. + + In actual practice (notably on Macintosh computers), the +Bounding Box posted in the EPSF is often not what it should be, +namely the least rectangle containing the ink that will print the +graphic object; it tends to be somewhat larger. Thus, tools are provided +to correct the box to fit the object. + + 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 would be justified, but just as for TeX +characters, this is not necessarily so (cf. TeXbook p.63). These +commands are used intensively; some alternative older +terminology (less recommended) can be found inside boxedeps.tex. + + 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 takes a dimension argument referring to the PostScript (artist's) +coordinates; with no scaling. Their names say what they do; just +remember that they do NOT mask off part of the object when the box +becomes too small; thus trimming is NOT "clipping". + + TeX is pretty good at shunting boxes around. But the command +to *slide* an image around without changing its 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 +scale, then trim. Finally, slide, or shunt using TeX tools. + + By default, the box produced has a baseline (roughly!) through +the middle like the letter "g"; it is constructed using TeX's \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 but it solves an important problem +mentioned by Georg Denk <denk@mathematik.tu-muenchen.de> concerning +co-authors sharing a develloping ".tex" plus ".eps" document in a +heterogeneous networked environment. As they use quite different +drivers, the above documentation seems to suggest that before +compiling, an author must reset his driver declaration, say from +\SetTexturesEPSFSpecial to \SetBechtolsheimDVITPSEPSFSpecial. This is +a pain which can easily be avoided, as follows. The authors agree to +each set up a file "boxedeps.cfg" in his TeX inputs directory that +contains just the command \Set...EPSFSpecial appropriate to his +driver; then in the the ".tex" source file the variable command +\Set...EPSFSpecial is replaced by the invariable command \input +boxedeps.cfg. This tells each TeX which is its appropriate driver. A +model boxedeps.cfg file with some advice may be included in the +BoxedEPSF distribution. + + (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 +the 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. + + 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 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. + + + + ****** Changing 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 + + \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 + %% \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 1.4.2--1.6 must now either +update to OzTeX1.7, or use \SetOzTeXEPSFSpecial\PSOrigintrue 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 C 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 is +an admirable exception.) 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 EPSF>}} + +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 +classical metafont type. + + (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" that is normally +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 +is 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); 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; can be adapted to LaTeX, by puting + %% everything from \input to ZZ into the middle of a LateX file. + %\magnification=1200 %% uncomment later + \input boxedeps.tex %% lower case "8+3" convention for file names + \Set...EPSFSpecial %%%% complete this line!!!!!!!! + \ShowDisplacementBoxes%\HideDisplacementBoxes %%alternatives + \null\vfill\vfill + AA\BoxedEPSF{gdisk.eps scaled 500}ZZ + + \bye + + ------ 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. + + + + 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 88 on the Mac by Adobe Corp is a MacDraw-like +program that uses the EPSF norm. Although in some respects rustic, +it is favored by professionals since it is geared for highest +quality output. Illustrator 3.0 is an update of 1990. + + 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 is +distributed with Illustrator 88 on the Mac. To get preview, and +sometimes 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) Macintosh output to LaserWriter printers is PostScript code, and +can be diverted into a file. This file cannot be used as is, but a +header file can be added which with a few other changes produces a +(bulky) EPSF. See the macps converter of unix, or OzTeX or the +$20 shareware Mac package AddLPrep copyright 1988 by SoftWare 101, +15151 Old Ranch road, Los Gatos CA. The output is I believe +equivalent at similar resolution to what the Macintosh-LaserWriter +combination produces. However, starting from the same PICT file, +method (a) often gives better results! + + 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. + + 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) LaserWriter 8.1.1 of 1993 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 ditributed with System 7.5. +Bounding boxes do not yet behave correctly in all cases, and many other +bugs remain to be eliminated. Perhaps not yet ripe for general use as of +early 1994. 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. + + + ***************************************** + + 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). + + **************************************** + + +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. + + For PC see the distribution of emtex on ftp +rusinfo.rus.uni-stuttgart.de. + + For Macintosh see the directory /info-mac/util/ of ftp +sumex.stanford.edu; the author is Martin Fong +<mwfong@nisc.sri.com>; the February 1993 version (2.5.2beta2) +works well. (For some Macintosh EPSFs you may need to load +some "laserprep" macros using a menu, but that is a sign +of non-portability of the EPSFs.) + + 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 is still a 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, normally number 256. (There is a variant for PC +but I have not yet seen extensive support for it.) Macintosh +sources of PostScript graphics do follow this standard faithfully, +but PostScript graphics coming from non-Mac sources more often do +not, especially where unix systems are concerned. + + +Macintosh Preview for EPSFs. + + MacGS could undoubtedly be adapted to provide the PICT +resource just mentioned (and Bounding box comment) in a fully +mechanized way. Until that comes to pass here is a recipe to do +the job by hand. Transfer the graphics window image via clipboard +to a MacPaint-like program and select just the interior of the +bounding box indicated by the bb4gs.ps header; transfer this +selection via the Mac clipboard to the Mac scrapbook; then +transfer the PICT resource from there to the resource fork of the +PS file using ResEdit, changing the PICT number to 256. Remember +to insert in the EPSF (data fork) header the Bound Box comment +provided by bb4gs.ps. + + +Mechanized Macintosh Preview production with unix help. + + Georg DENK <denk@mathematik.tu-muenchen.de> exploits +unix tools to obtain Macintosh preview (under Textures, OzTeX, +and Direct TeX) for PostScript graphics coming from other +computers. (Georg's PostScript material is coming from various +data analysis programs on Sun workstations.) + + He reports extensive experience with a solution +mounted on the Sun side of his local network. The enhanced Mac +PostScript file is created under unix (as a MacBinary file) using +ghostscript (gs), pbmplus-package, and the shell script +ps2eps-mac with its C-language programs ps-pict2macb, st_echo, +er_echo, pbmtoepsi. The most recent item is ps2eps-mac by George +Jefferson, <george@mech.seas.upenn.edu>; the graphics conversion +package pbmplus-package (by ...) is also rather new and it is +conveniently included in the shar-file distribution of +ps2eps-mac, available from ftp sumex.stanford.edu in the directory +/info-mac/unix/. Setting up these tools requires knowledge of C +compilation and the unix shell. + + -------------- + + +SOMMAIRE FRANCAIS: boxedeps.tex d'efinit des macro-commandes + qui permettent d'int'egrer dans un document TeX des + objets graphiques d'ecrits par fichier de norme EPSF, tout + en accordant `a chacun le statut d'une bo^ite TeX ayant + les bonnes dimensions. La (seule!) contribution unique + de ce fichier 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. + + |