Encapsulated PostScript File Format for PageMaker Import (For PC Windows and Macintosh Applications) by John Nelson and Sheri Hargus The following specifies the format required for import of Encapsulated PostScript (EPS) Files into PageMaker. This specification suggests a standard for both Macintosh and PC Windows applications. PageMaker version 2.0 for the Macintosh and PageMaker version 1.0 for the IBM PC and compatibles will both support this format. The EPS format was originally developed by Jim Von Ehr of Altsys Corporation; some enhancements to that original format are included here in order to conform to Adobe PostScript Document Structuring Conventions, version 2.0, to add support for print spoolers, and to allow compatibility with Windows. This specification is compatible with EPS file specifications distributed by Adobe Systems Incorporated. January 5, 1987 EPSF Version 1.2 Summary of changes for 1.2: * added DocumentNeededFont * LoadFont renamed to IncludeFont * added %%+ continuation lines * revised version comment * deleted Call comment * added IncludeFile comment * added TIFF screen representation * revised Windows EPS header format * made other minor changes Previous EPS versions will be supported, but are not recommended. This document revision supercedes all previously-dated revisions. Please direct comments in writing to: Tim Davenport Aldus Corporation 411 First Avenue South, Suite 200 Seattle, WA 98104 INTRODUCTION The rules that should be followed in creating importable PostScript files for PageMaker are a subset of the structuring conventions proposed by Adobe Systems Incorporated; refer to the PostScript Language Reference Manual, Appendix C, and PostScript Document Structuring Conventions, version 2.0, available from Adobe. Files must also be "well-behaved" in their use of certain PostScript operators, manipulation of the graphics state, and manipulation of the PostScript stacks and global dictionaries. These conventions are designed to allow cooperative sharing of files between many systems using PostScript. Encapsulated PostScript FILE GUIDELINES An EPS file should conform to version 2.0 of the Adobe Document Structuring conventions, in that any comments used should be in accordance with that specification. In addition, the %%BoundingBox comment is required. PageMaker will scan imported files, doing minor syntax checking and handling comments as noted in the following sections. Structuring Comments Structuring comment lines must begin with "%!" or "%%" and terminate with a newline (either return or linefeed) character. PageMaker import requires that a comment line not be longer than 256 bytes. A comment line may be continued by beginning the continuation line with "%%+". The colon in any comment is optional. The EPS file should begin with a "header" of structuring comments (see the PostScript Language Reference Manual, Appendix C). Required Comments The first comment in the header (and the first text line in the file) should be the version comment: %!PS-Adobe-2.0 EPSF-1.2 This indicates to PageMaker that the PostScript file conforms to this standard. The version number following the word Adobe indicates the level of adherence to standard PostScript comments, as defined in PostScript Document Structuring Conventions. The version number following the word EPSF indicates the level of EPSF-specific comments. The following comment must be present in the header; if it is not present then PageMaker will issue an error message and abort the import: %%BoundingBox: llx lly urx ury The values are in the PostScript "default user coordinate" system, in points (72nds of an inch), with the origin at the lower left. General Informational Comments The following header comments are strongly recommended: %%Creator: creator_name %%Title: PSfile_title %%CreationDate: date_and_time Creator, Title, and CreationDate information is used by PageMaker to create a screen representation of the PostScript segment if no other screen representation is included in the file. %%EndComments This comment indicates the end of the header comments. Font Management Comments If fonts are used, the following two comments should be included in the header of the EPS file: %%DocumentFonts: font1 font2 ... The DocumentFonts comment is a full list of all fonts used by the file. Font names should refer to non-reencoded printer fonts. PageMaker will load these fonts if necessary at the beginning of the file; if this comment is not present then PageMaker will assume that no fonts need to be preloaded. (See also the %%DocumentNeededFonts and %%IncludeFont comments.) PageMaker will convert the DocumentFonts comment to a PageFonts comment for output in order to ensure compatibility with print spoolers. Note: For PC Windows applications, it is recommended that only standard device-resident fonts be used. %%DocumentNeededFonts: font1 font2 ... The DocumentNeededFonts comment lists all fonts that are loaded at specific points within the EPSF file as a result of IncludeFont comments. These fonts must also be listed in the DocumentFonts comment, but PageMaker will not preload these at the beginning of the file. Within the body of the PostScript file, PageMaker will handle the following comment: %%IncludeFont: font The IncludeFont comment signals to PageMaker that the specified font is to be loaded at that point in the imported PostScript code. PageMaker will load the specified font regardless of whether the same font has been loaded already by other preceding IncludeFont comments, since the font may be embedded within a PostScript save and restore construct. However, PageMaker will not load any font specified that has already been determined (at the beginning of the print job) to be permanently present in the printer. The names of fonts that are loaded in this way should be also included in the DocumentNeededFonts comment in the header of the file. A font that is wholly contained, defined, and used within the EPS file should be noted in the DocumentFonts comment but not the DocumentNeededFonts comment. The font should follow conventions listed in Postscript Document Structuring Conventions in order to retain compatibility with print spoolers. File Inclusion Comments %%IncludeFile: file_name This comment, which can occur only in the body of an EPS file, allows a separate file to be inserted at any point within the EPS file. The file must be present in the same working directory as PageMaker, or else the filename must be a fully qualified pathname. The file might not be searched for or inserted until printing actually occurs, so user care is required to ensure its availability. This comment is not recommended for use with PC Windows. "WELL-BEHAVED" RULES PageMaker will encapsulate the imported PostScript code in a save and restore construct, which will allow all VM to be recovered and the graphics state restored. Since the code in the imported EPS file will be embedded within the PostScript that PageMaker generates for the current page, it is necessary that it obey the following rules. Dangerous Operators The following operators should not be included in a PostScript file for PageMaker import; the result of executing any of these is not guaranteed. grestoreall initgraphics initmatrix initclip erasepage banddevice framedevice nulldevice renderbands setpageparams note The following operator results in an error message and in PageMaker terminating the PostScript file import: exitserver The following operators are allowed, but are removed from the code during import parsing, or are redefined to have no affect: showpage copypage PostScript Stacks: All stacks (including the dictionary stack) should be left in the state that they were in before the imported PostScript code was executed. Dictionaries: No global strings should be changed. It is recommended that the imported PostScript code create its own dictionary instead of writing into the dictionary that PageMaker currently has placed on the top of the dictionary stack. However, reference to that dictionary should be removed from the dictionary stack with an end command within the EPS file. If a special header or dictionary is required in order for the imported PostScript code to execute, then it should be included as part of the PostScript file. However, it should be enclosed in comments as specified in the Postscript Document Structuring Conventions. No dictionary should be assumed to be already present in the printer; fonts should not be assumed to be already reencoded. FILE TYPES Macintosh The Macintosh file type for application-created PostScript files is EPSF. Files of type TEXT will also be allowed so that users can create EPS files with standard Macintosh editors, although the document structuring conventions should still be strictly followed. PC-Windows The recommended file extension is .EPS. Other file extensions will also be allowed, but it will be assumed that these files are text only files with no header, screen metafile, or TIFF section included in them. PAGEMAKER SCREEN REPRESENTATION The EPS PostScript file will have a graphical screen representation so that it can be manipulated on the PageMaker page. As with other PageMaker images, a user will be able to crop, scale, and translate the PostScript representation. Macintosh: PICT Representation A QuickDraw representation of the PostScript file can be created and stored as a PICT in the resource fork of the file. It should be given resource number 256. If the PICT exists, PageMaker will use it for screen display. The transformed (to PostScript default user coordinates) picframe should agree with the BoundingBox comment; if it doesn't, PageMaker will scale the picture to match the bounding box. PC-Windows: MetaFile or TIFF Representation Either a Windows MetaFile or a TIFF (Tag Image File Format) section can be included as the screen representation of an EPS file. The file format for EPS files is: Header: Bytes Description 0-3 Must be hex C5D0D3C6 (byte 0=C5) 4-7 Byte position in file for start of PostScript code section 8-11 Byte length of PostScript section 12-15 Byte position in file for start of MetaFile screen representation section 16-19 Byte length of MetaFile section (PSize) 20-23 Byte position of TIFF screen representation 24-27 Byte length of TIFF section 28-29 Checksum of header (XOR of bytes 0-27) note: if FFFF then ignored (Note: It is assumed that either the MetaFile or the TIFF position and length fields are zero; the non-zero section will be used by PageMaker.) Body: PostScript and MetaFile sections MetaFile section: 0 - MetaFile contents PSize-1 The MetaFile should follow the guidelines set by Windows; in particular, it should not set the viewport or mapping mode (PageMaker always uses the anisotropic mapping mode), and it should set the window origin and extent. The picture will be scaled to fit within the BoundinBox specified in the comment. The byte order of numeric fields (beginning with byte 4) should correspond to that expected by the PC. If there is no MetaFile or TIFF screen representation, the header may be omitted; the file would begin with the version comment. PageMaker-generated Representation If a screen picture presentation does not exist, PageMaker will create a framed box of BoundingBox proportions with descriptive text from the PostScript comments inside it.