Embedding post-script images in troff text

[Tim O'Reilly]

In article <4594 at venera.isi.edu>, cracraft at venera.isi.edu (Stuart Cracraft) writes:
> Is there a way to embed post-script images in troff text?
> For example, the PostScript language could be used to produce
> a fancy table or image, and this PostScript language and/or
> image could somehow be inserted in the middle of a troff
> document.
> 
It depends on the postprocessor you're using.  To include
PostScript code in troff is simply a matter of using any one
of a number of troff mechanisms.  For example, there's so
called "transparent output":

  \! PostScript code here

Or there's the .cf request to interpolate the contents of an
entire file, uninterpreted, into the troff output stream: 

   .cf file.ps

Or there's the .sy request, which runs a program an
interpolates its output, uninterpreted, into the troff output
stream:

   .sy cat file.ps

In addition, Berkeley ditroff includes a special escape sequence, \X,
which allows you to include in-line code:

   \X 'PostScript code'

Of course, when you do any of these things, you must make allowances,
in troff, for spacing and so forth, so troff and the output device 
don't get out of sync!  For example, if you are going to
interpolate the contents of a PostScript file containing a
figure, you must tell troff to space down, or else it will
resume printing at the original position, right on top of
the figure.

The real problem, though, is whether or not your troff-to-PostScript
postprocessor will let the code go through.  For example, versions
of transcript prior to 2.0 don't support this.

In current versions of transcript (that is, of psdit, the
ditroff-to-PostScript translator that is part of transcript), 
the % sign can be used to signal psdit that the following
lines contain PostScript code that is to be passed
uninterpreted to the printer.  This situation is terminated
by a line containing a single .  For example:

  \!%
  \!PostScript code here
  \!.

There get to be some complications with saving and restoring
the graphics state....how well this works depends on whether
or not your PostScript code interferes with the PostScript
being generated by psdit.  To make things easier, they've
defined some additional PostScript operators (PB--Picture
Begin--and PE--Picture End) to make things easier.  The full example
documented on the psdit man page looks like this:

  \& 
  .fl 
  \!%PB
  \!/showpage{}def
  .fl
  .sy cat mypic.ps
  \!PE
  \!.

In devps (from Pipeline Associates), you simply need to add a 
second exclamation point for a line of included code:

  \!! PostScript code here

so that devps will know to pass the line directly to the
printer.  

I find the .sy request particularly useful, since you can
use sed to edit your PostScript file to insert the extra
exclamation point:

  .sy sed -e 's/^/!/' file.ps

Devps includes a number of troff macros for including PostScript
special effects, as well as for taking care of figure
spacing problems.

With all of this, you can have problems if you include
PostScript code that isn't well behaved.  At a minimum, your
code should save and restore the context.  You may also need
to temporarily redefine the showpage operator.


We hope to have a Nutshell Handbook out on this topic
sometime later this year.  Till then, I hope this helps.

-- 
Tim O'Reilly (617) 527-4210
O'Reilly & Associates, Inc., Publishers of Nutshell Handbooks
981 Chestnut Street, Newton, MA 02164
UUCP:	uunet!ora!tim      ARPA:   tim at ora.uu.net