# How to use Adobe PostScript language files properly.

## About 90% of the Adobe PostScript problems at CDF are the result of violating one rule:Illustrations should be EPS files and should be generated and tested as such!

Many of the problems where Ghostscript, gs, will display the document, but the document will not print on a printer is that the document was created using Microsoft or AppleSoft document preparation software. This is the result of these software assuming that the documention is being prepared to print on a specific printer type and that it is the responsibility of the document preparation software to condition the printer appropriately. Unfortunately, these assumptions are all too often incorrect in large computing environments with a variety of printer types and with print spooling systems which actually have the responsibility to condition the printer on which the document actually is printed. If the actual printer does not understand the embedded conditioning commands, which may be Hewlett-Packard Printer Control Language (HPCL), Adobe PostScript printer type specific commands, or some other printer language, then the usual result is a failure to print. The presence of the printer conditioning code may also confuse the print spooling system as to what type of print file it is with the result the file prints in an inappropriate manner; e.g., Adobe PostScript code is printed as ASCII text instead of being executed to generate page images.

In the case where Ghostscript, gs, will display the file, but it will not display properly when using a Ghostscript managing program such as Ghostview (ghostview) or gv, is that the file has improper Document Structuring Comments (DSC; see below). The wrapper programs are dependent on there either being no DSC or that the DSC is proper. The case of no DSC results in not having a page number that works.

Another major source of problems is improper copying of Adobe Postscript files between machines with very different operating systems. Most Adobe PostScript files are ASCII and should be moved as text. Adobe PDF files are binary and must be moved as such. For example, FTP and Kermit must be told which method to use.

Magic bullets for addressing Adobe PostScript problems in the general case are mathematically impossible.

Unreliable tricks and techniques for modifying Adobe PostScript files do exist that sometimes work. Such tricks and techniques are not presented in this document because they are not general or reliable.

Major sections of this document:

# The Basics

Adobe PostScript files contain programming to draw the image and may and usually do contain comments that describe the requirements and some of the structure of the file. The comments, called DSC, are intended to assist other programs to process the file without fully understanding the file. These comments are used, for example, by LaTeX and dvips when encapsulating (incorporating) an EPS file.

Slides and tranparencies are one class of PostScript material; they are the same class as other reports and documents. Illustrations are a separate class of PostScript material. Because of the extreme difficulties of making a file that can do both, these classes should be maintained as separate collections and used appropriately.

A page extracted from a paper, with the undesired material removed with White Out(tm)' operations, is still an Adobe print file. This is so even if one changes the DSC comments to claim that it is an EPS file. Please see the warning About extracting illustrations from print files'.

There are no foolproof, omnipotent, programmable, programmed or universally simple methods for fixing Adobe PostScript files! There is a mathematical proof of the Halting Problem which is the reason why such methods do not exist. Fixing' includes changing PS into EPS, making a file universally printable or viewable, rearranging or removing graphic elements from an image, etc.

Methods do exist for specific situations such as Adobe PostScript files generated by specific versions of specific applications. Program do exist that can modify the output of a large number of versions of a large number of commerically available applications. This is not the general case.

Because in the general case, there are no simple reliable methods, methods for addressing some Adobe PostScripts which must be complex or unreliable are not presented in this document.

# What is ...

Adobe PostScript language is a computer language with the primary purpose of generating graphical images (including text) in a device independent manner.

It describes these graphical images by describing how they are drawn with lines and curves and fillings of areas, by placing bitmap images or bitmap image overlays.

PostScript can describe an image in terms of its component elements. It can take full advantage of graphical engine capacities such as resolution and color. Conversely, it can ignore or select alternatives to circumvent graphical engine deficencies such as being black and white or if the interpreter lacks access to a particular font description.

Because PostScript is a full capacity computer language, it is has the same constraints which all programming languages have. In general, it is impossible to write a program to analyze other programs and determine whether those programs will produce any predetermined result, such as halt. In computer science, this is known as the Halting Problem. Therefore, in general, it is impossible to write a program to analyze an Adobe PostScript file with a view to changing that file's behavior in some predetermined manner.

This also implies, in the general case, that it is impossible to determine how many pages a PostScript print file will print. In fact, it is possible to write a program that prints a random number of pages each time it is executed. As examples of programs with clearly visible different behavior each time they execute, display or print the eyechart program mentioned below or redisplay the same page of the Just a little PostScript' seminars and watch the Fermilab logo change color.

Non-Adobe PostScript material, such as setting an HP printer to Adobe PostScript mode should not be included with an Adobe PostScript file. Such operations are the responsibility of the print spooler or the printer manager.

Illustrations should be EPS files and should be generated and tested as such! Many PC applications, both IBM and Apple compatible, violate this rule. These application frequently do not offer an option to generate EPS files. Or, the option to generate EPS files is not selected. Or, the option is selected; but it does not generate proper EPS files. Possibly this occurs because the artist wants to print the image to see how it looks rather then generating the EPS file and then using as it is to be used. As a direct result, many illustrations generated using these programs are not proper EPS files and have extranous printer control material. The result is problems when these files are used in an attempt to illustrate a document.

Slides, tranparencies, etc. are single page documents and should be prepared as such. That is, the EPS file should be encapsulated into a single page file, be properly places, sized and oriented and then printed as a print document.

Adobe PostScript files are intended to be written in 7-bit printable ASCII text using UNIX, Apple MacIntosh or MSDOS line terminators. But, it is possible to include binary information or extremely long lines in these files. Such conditions may cause problems with print spoolers and viewer managers such as Ghostview.

Adobe Encapsulated PostScript files are files which are intended to be encapsulated (or incorporated) into other Adobe PostScript files. They are subroutines which are called by copying them into the proper location within the larger Adobe PostScript file.

Because EPS files are intended to be part of a single page, they must be single page images themselves.

Because they are usually processed by encapsulating programs which do not have language level knowledge of the EPS file's contents, they should include Adobe PostScript Document Structuring Comments (DSC) and conform to constraints so that the encapsulating program can obtain its desired results.

A proper EPS file when it has been executed should leave the interpreter, except for any image generation, in the same state as the interpreter was in when the EPS file received control. A proper EPS file should honor any translation, rescaling or rotation established by the encapsulating code. A proper EPS file should not use any commands which reset the interpreter's state or cause an image to be displayed.

EPS and its requirements on a PostScript file are described in considerable detail in Appendix H of the second edition of the PostScript language reference manual, a.k.a. the Red and White Book.

DSC is an Adobe PostScript language commenting convention which permits processing of PS files without the processing programs needing language level knowledge of the PS file's contents.

Applications which encapsulate EPS files, PS file viewer managers, such as Ghostview, and print spoolers are such programs. Based on the comments within the PS file, these programs are able to resize, relocate or rotate images; disassemble the PS files into usable components and then reassemble selected components into other useful forms; decide required resources and select appropriate printers and printer resources to display the file.

DSC assumes that the file prolog, an individual page description and the file epilog when concatenated together will properly print that page.

DSC assumes that each page is independent of each other page. In particular, it assumes that the page order is not significant and that the interpreter state is restored to the conditions that existed after the file prolog had been run at the completion of each page.

DSC and its requirements on a PostScript program are described in considerable detail in Appendix G of the second edition of the PostScript language reference manual, a.k.a. the Red and White Book.

An Adobe PostScript print file may be any legal PostScript program. If it is desired that it can be properly processed by print spoolers and viewer managers, then it should conform to the DSC conventions as well. Any encapsulated images should conform to the EPS conventions.

# Warnings

## About extracting illustrations from print files

Admittedly, this is a very tempting operation. It can be done.

It can not be done properly by extracting the pertinent page from the print file, for example by using Ghostview page selection; using an illustration modifier program to White Out(tm)' the undesired material on the page; adding EPS DSC material to the resultant file and using the result as an EPS file.

With generally poor results and considerable effort, it can be done by extracting the pertinent page from the print file, converting the image to a bit-map image, doing a bit-map edit on the image, selecting the desired portion of the bitmap image and generating a PostScript bitmap image. There generally is a major loss of resolution and fine detail when this is done. The file size generally grows significantly--10 000 byte files can easily become 10 000 000 byte files.

With generally good results, it can be done by extracting the pertinent page from the print file, text editing the file to remove the encapsulating material, reconstructing the frequently deleted EPS DSC material and analyzing for and removing any undesired annotations. The resultant EPS file should be given the same testing as any other EPS file. Here is a basic set of EPS headers:

%!PS-Adobe-2.0 EPSF-1.2
%%BoundingBox: llx lly urx ury

The BoundingBox numbers are, in pairs, the coordinates of the lower left (ll) and upper right (ur) corners of the box which surrounds the figure. They must be integers. The horizontal (x) coordinate is the first coordinate in a pair; the vertical (y) coordinate is the second coordinate in a pair. The origin is the lower left corner of the interpreter's imaging area. The units are PostScript points (72ths of inches or 352 7/9 micrometers). Select values which are a small nearly uniform amount outside the actual figure.

The difficulty in the last method is mostly in the removal of undesired annotations. With LaTex, the encapsulating material is quite stylized and therefore usually easily removed. Ghostview can be used to reconstruct the BoundingBox data which is the hardest of the required EPS DSC material to reconstruct.

Whereas Adobe PostScript interpreters can process files with any of UNIX, Apple MacIntosh or MSDOS line terminators, the same is not generally true of the application programs that process the Adobe PostScript files. To each other operating system, UNIX and Apple MacOS files appear to be one long line. This can cause problem with line buffer sizes in applications and print spoolers. Adobe PostScript files should be copied between dissimilar operating systems as text files.

Whereas Apple MacOS considers null (zero) bytes to be white space characters, UNIX considers them to character string terminators. Unless an UNIX application is careful coded to handle character streams containing null bytes which are data, ommisions of data may occur. Many Adobe PostScript interpreters will treat null bytes as whitespace.

Ghostview is dependent on proper Adobe DSC. Ghostview uses these comments to locate the file's prolog which defines procedures and values used by the individual page descriptions, the individual page descriptions themselves and the file's epilog which may do some cleanup. If the application generating the file does not generate proper DSC or obey the constraints of page independence, the individual pages may not be properly handed to ghostscript for display. A common symptom is an eyeball hang. Ghostview presents an eyeball cursor until the underlying ghostscript interpreter signals that it has presented the page to the display. Then, Ghostview switches to a cross cursor. If the showpage command which should be part of the page description is not executed, then the cursor does not switch.

If ghostview erronously includes extra material after the showpage, such as combining multiple page descriptions into a single offering to ghostscript, then the extra material is silently ignored. This can result in a file that appears to display properly in Ghostview which prints extra pages on a printer.

## Font Selection

Yes, I know that Palatino looks good. But, it is not present in many interpreters and printers. If you want your document to be presentable on most printers and display programs, then you should only use the basic 13 fonts that the Apple Laserwriter and almost all other printers have:

• Courier
• Courier-Bold
• Courier-BoldOblique
• Courier-Oblique
• Helvetica
• Helvetica-Bold
• Helvetica-BoldOblique
• Helvetica-Oblique
• Times-Roman
• Times-Bold
• Times-BoldItalic
• Times-Italic
• ZapfDingbats

Even the Helvetica-Narrow family is suspect; some interpreters have Helvetica-Condensed instead.

## Paper bin, tray, size, feed mode, etc. selection

In a word, don't do this in a document intended for general distribution! What your printer calls bin 0, may mean manual feed or not exist on another printer or interpreter. The entire world does not use either A4 (about 8.28 by 11.7 inches) or American letter (215.9 by 279.4 mm) paper. Instead of selecting a paper size, set your margins so that the print area is not too high for an American letter page nor too wide for A4 paper.

Using an unavailable paper tray, bin, size, feed mode, etc. is a good way to cause the print job to be canceled without being printed!

There are tricks available to resize print files to fit the other paper sizes.

## In General ...

PostScript Sins lists a number of failings of a number of Adobe PostScript language generating and handling applications.

# Methodologies

## How to test an Adobe PostScript print file.

A minimal, useful, but inadequate test is:

1. Print it on a PostScript language level 2 (a.k.a. Red and White Book) interpreter such as a QMS 1700 or HP 4si or 5si.
2. Ghostview. Check for the following:
• Eyeball hangs do not occur (i.e., that the cursor changes to a cross).
• All EPS images show up and are properly sized, located and oriented.
• The file shows all pages in the proper order with no extra pages.
• The page number bar appears in the Ghostview frame.

The print file should be submitted to each of the following and the outputs checked for proper behavior:

1. A PostScript language level 1 (a.k.a. Red Book) interpreter such as an Apple LaserWriter.
2. A PostScript language level 2 (a.k.a. Red and White Book) interpreter such as an QMS 1700 or a HP 4si or 5si.
3. Ghostview. Check for the following:
• Eyeball hangs (the cursor does not change to a cross) do not occur.
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check the image itself separately for a proper BoundingBox DSC comment.
• The file shows all pages in the proper order with no extra pages.
• The page number bar appears in the Ghostview frame.
• Skipping around in the file works between arbitary pages.
4. Ghostscript itself (somestimes the program name is gs). Check for the following:
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check the image itself separately for a proper BoundingBox DSC comment.
• The file shows all pages in the proper order with no extra pages.

## How to test an Adobe EPS file.

Note that an EPS file may itself contain other EPS files.

A minimal, useful, but inadequate test is:

1. After being encapsulated in a test harness, the resultant test file should be submitted to a PostScript language level 2 Red and White Book) interpreter such as an QMS 1700 or a HP 4si or 5si.
2. After being encapsulated in a test harness, the resultant test file should be submitted to Ghostview. Check for the following:
• Eyeball hangs (the cursor does not change to a cross) do not occur.
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check the image itself separately for a proper BoundingBox DSC comment.
• The page number bar appears in the Ghostview frame.
3. Give the EPS file by itself to Ghostview. Check for the following:
• Eyeball hangs (the cursor does not change to a cross) do not occur.
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check it for a proper BoundingBox DSC comment.

The EPS file should be submitted to each of the following tests and the outputs checked for proper behavior:

1. After being encapsulated in a test harness, the resultant test file should be submitted to a PostScript language level 1 (a.k.a. Red Book) interpreter such as an Apple LaserWriter.
2. After being encapsulated in a test harness, the resultant test file should be submitted to a PostScript language level 2 Red and White Book) interpreter such as an QMS 1700 or a HP 4si or 5si.
3. After being encapsulated in a test harness, the resultant test file should be submitted to Ghostview. Check for the following:
• Eyeball hangs (the cursor does not change to a cross) do not occur.
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check the image itself separately for a proper BoundingBox DSC comment.
• The file shows all pages in the proper order with no extra pages.
• The page number bar appears in the Ghostview frame.
• Skipping around in the file works between arbitary pages.
4. After being encapsulated in a test harness, the resultant test file should be submitted to ghostscript itself (somestimes the program name is gs). Check for the following:
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check the image itself separately for a proper BoundingBox DSC comment.
• The file shows all pages in the proper order with no extra pages.
5. The EPS file by itself to Ghostview. Check for the following:
• Eyeball hangs (the cursor does not change to a cross) do not occur.
• All EPS images show up and are properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check it for a proper BoundingBox DSC comment.
The EPS file by itself ghostscript itself (somestimes the program name is gs). Check for the following:
• The EPS image shows up and is properly sized, located and oriented. If an EPS image does not have appropriate amounts of white space around it, then check for a proper BoundingBox DSC comment. pages.

Here is a sample test harness using LaTeX. Either rename your EPS file to plot1.ps or change the file name within the test harness. (Another copy of the harness is here.)

\documentstyle{article}
\input epsf
\begin{document}
This is a dummy document.
The text and the figure have nothing to do
with each other.

A paraphrase of Arthur C. Clarke, radio engineer,
science fiction author, and the author of the artificial
earth-orbiting communications satellite in 1945:

{ \sloppy
\begin{quote} \em
$\ldots$ sufficiently advanced technology is indistinguishable
from magic.
\end{quote}
}

\begin{figure}[h] \centering
\mbox{}
\epsfysize=3.5in
\leavevmode
\epsfbox{plot1.ps}
\caption[Plot 1]{This is the first plot.  Interesting, isn't it?}
\label{Fred}
\end{figure}

Here is the LaTeX for the figure above:
\begin{verbatim}
\begin{figure}[h] \centering
\mbox{}
\epsfysize=3.5in
\leavevmode
\epsfbox{plot1.ps}
\caption[Plot 1]{This is the first plot.  Interesting, isn't it?}
\label{Fred}
\end{figure}
\end{verbatim}

A reference to figure \ref{Fred}.
\end{document}
`

# Sample PostScript files and fragments

These files are not necessarily good examples of PostScript coding. They are included because I have found them useful at times.

# Seminars and Presentations

Viewgraph form of Brown Bag talk on Adobe PostScript language.

Handout form of Brown Bag talk on Adobe PostScript language.

# The FAQs

comp.lang.postscript

Ghostscript

# Information

## Books

• Adobe Systems Incorporated, PostScript Language Reference Manual, Addison-Wesley Publishing Company, Inc., 1985. A.k.a the Red Book.
• Adobe Systems Incorporated, PostScript Language Reference Manual, Second Edition, Addison-Wesley Publishing Company, Inc., 1990. A.k.a. the Red and White Book.
• Adobe Systems Incorporated, PostScript Language Program Design, Addison-Wesley Publishing Company, Inc., 1988. A.k.a. the Green Book.
• Adobe Systems Incorporated, PostScript Language Tutorial and Cookbook, Addison-Wesley Publishing Company, Inc., 1986. A.k.a. the Blue Book.
• Adobe Systems Incorporated, The Display PostScript System Reference Manual, (The Purple Book), Addison-Wesley Publishing Company, Inc., 1990.
• Adobe Developer Support, PostScript Printer Description File Format Specification, Adobe Systems Incorporated.
• Adobe Systems Incorporated, Portable Document Format Reference Manual, Addison-Wesley Publishing Company, Inc., 1993.
• Adobe Systems Incorporated, Adobe Type 1 Format, Version 1.1, Addison-Wesley Publishing Company, Inc., 1990. A.k.a the Black and White Book.
• McGilton, Henry and Mary Campione, PostScript by Example, Addison-Wesley Publishing Company, Inc., 1992.
• Reid, Glenn C., Thinking in PostScript, Addison-Wesley Publishing Company, Inc..
• Holzgang, David A., Understanding PostScript Programming, Sybex Inc., 1987.
• Roth, Stephen F., Real World PostScript Techniques from PostScript Professionals, Addison-Wesley Publishing Company, Inc., 1988.
• Roth, Stephen F., Real World PostScript, Addison-Wesley Publishing Company, Inc., 1988.

## WWW

The Adobe Systems Inc. WWW pages.

The Adobe Systems Inc. WWW pages search engine.

Other font resources

PostScript Troubleshooting, Operators, DSC, Errors, First Guide

Internet Resources for PostScript and Ghostscript

A First Guide to PostScript

PostScript Language Document Structuring Conventions Specification, V3.0 (about 400K PDF; from Adobe)

The PostScript Level 2 language specification (about 4M PDF; from Adobe; a.k.a. Red Book)

The PostScript Level 3 language specification (about 8M PDF; from Adobe; a.k.a. Red Book)

The PostScript Level 3 Core Font Set Overview (about 31K PDF; from Adobe)

The PostScript Level 3 Clipsave and Cliprestore (about 45K PDF; from Adobe)

The Compact Font Format Specification [TS 5176] (about 433K PDF; from Adobe)

PostScript Language Tutorial and Cookbook (about 868K PDF; from Adobe; a.k.a. Blue Book)

PostScript Language Program Design (about 868K PDF; from Adobe; a.k.a. Green Book)

PostScript Printer Description File Format Specification (about 1M PDF; from Adobe; a.k.a. PPD specification)

# Freely available Software

Ghostscript, Ghostview and GSview

gv 3.5.8

MGv: A Motif PostScript Viewer

GNU Image Manipulation Program

Last updated 2 July 2004 by Randolph J. Herber