A PostScript program can only be understood by running it, so Adobe defined comments
that describe its structure: where the pages are, what fonts and paper it needs. The
interpreter ignores them; spoolers, previewers and page-reordering tools read them.
This page follows Adobe Technical Note 5001, PostScript Language Document
Structuring Conventions Specification, version 3.0 (1992). Comments start with
%% (or %? for queries) in the first column, are at most 255
characters per line, and continue on lines starting %%+. Arguments are
text, numbers, or (atend), meaning “given in the trailer”.
Structure of a conforming file
%!PS-Adobe-3.0
%%Title: report.ps header comments
%%Pages: (atend)
%%EndComments
%%BeginProlog prolog: definitions only
…
%%EndProlog
%%BeginSetup document setup
…
%%EndSetup
%%Page: 1 1 page 1
%%BeginPageSetup
…
%%EndPageSetup
…
%%PageTrailer
%%Trailer trailer
%%Pages: 3
%%EOFPages must be independent: each can be printed after the prolog and setup alone,
so tools can reorder or extract them. A file that cannot keep these rules should
start with plain %!.
Header comments
| Comment | Arguments | Meaning |
|---|---|---|
%!PS-Adobe-3.0 | optional keywords: EPSF-3.0, Query, ExitServer, Resource-type | First line: the file follows DSC 3.0 and is a document, an EPS file, a query job, an exitserver job or a resource file. |
%%BoundingBox: | llx lly urx ury | (atend) | The box enclosing all marks, in whole points (1/72 inch), in default user space. |
%%HiResBoundingBox: | four reals | The same at full precision. Not part of DSC 3.0, but written by many later applications. |
%%Copyright: | text | Copyright notice. |
%%Creator: | text | The program that made the file. |
%%CreationDate: | text | When it was made, in any form. |
%%DocumentData: | Clean7Bit | Clean8Bit | Binary | What bytes the file contains, so a channel can be chosen. |
%%Emulation: | mode: diablo630, fx100, lj2000, hpgl, hplj, impress, ti855 | The document is in another printer language, run by an emulator. |
%%EndComments | Ends the header. Optional if the next line does not start with %%. | |
%%Extensions: | DPS, CMYK, Composite, FileSystem | Language extensions beyond Level 1 that the file needs. |
%%For: | text | The person the document is for. |
%%LanguageLevel: | integer | The LanguageLevel needed: 1, 2 or 3. |
%%Orientation: | Portrait | Landscape | (atend) | How a previewer should show the pages. |
%%Pages: | number | (atend) | The number of pages; 0 for a file that draws no page, such as EPS. |
%%PageOrder: | Ascend | Descend | Special | (atend) | The order of the pages; Special means they cannot be reordered. |
%%Routing: | text | Where to deliver the printout. |
%%Title: | text | The document’s title. |
%%Version: | version revision | The document’s version. |
Body comments
| Comment | Arguments | Meaning |
|---|---|---|
%%+ | text | Continues the previous comment’s arguments. |
%%BeginProlog, %%EndProlog | The prolog: procedure definitions, no marks. | |
%%BeginSetup, %%EndSetup | Document setup: device settings, fonts, done once before the pages. | |
%%BeginDefaults, %%EndDefaults | Page-level comments in between apply to every page unless a page overrides them. | |
%%BeginData:, %%EndData | count [Hex | Binary | ASCII [Bytes | Lines]] | A block of data of that many bytes or lines, which a tool must skip without parsing. |
%%BeginBinary:, %%EndBinary | bytecount | Binary data (superseded by BeginData). |
%%BeginEmulation:, %%EndEmulation | mode | A section in another printer language. |
%%BeginPreview:, %%EndPreview | width height depth lines | A device-independent preview bitmap as hex comment lines, used in EPSI files. |
Page comments
| Comment | Arguments | Meaning |
|---|---|---|
%%Page: | label ordinal | Starts a page: its label as printed (such as iv) and its position in the file, from 1. |
%%PageBoundingBox: | llx lly urx ury | (atend) | This page’s bounding box. |
%%PageOrientation: | Portrait | Landscape | This page’s orientation. |
%%BeginPageSetup, %%EndPageSetup | Page setup code. | |
%%BeginObject:, %%EndObject | name [code] | A graphic object within a page, for tools that print parts. |
%%PageTrailer | Starts the page’s trailer, where (atend) page comments are given. |
Trailer comments
| Comment | Meaning |
|---|---|
%%Trailer | Starts the trailer, after the last page. Header comments given as (atend) are repeated here with their values. |
%%EOF | The end of the document. Nested documents have their own. |
Requirement conventions
Header
| Comment | Arguments | Meaning |
|---|---|---|
%%DocumentMedia: | name width height weight colour type | Each paper used: a name for the document, size in points, weight in g/m², colour and type (such as Plain, Transparency). |
%%DocumentNeededResources: | type name… | (atend) | Resources the printer must supply: font, file, procset, pattern, form, encoding. |
%%DocumentSuppliedResources: | same | Resources the file contains. |
%%DocumentPrinterRequired: | printer product version revision | The document only works on that printer. |
%%OperatorIntervention: | [password] | The job needs an operator. |
%%OperatorMessage: | text | A message to show the operator. |
%%ProofMode: | TrustMe | Substitute | NotifyMe | What to do when resources are missing. |
%%Requirements: | keywords, some with options: collate, color, duplex, faceup, fax, fold, jog, manualfeed, numcopies, punch, resolution, rollfed, staple; each may take a style in parentheses, such as numcopies(3), punch(3), duplex(tumble) | Printer features the document needs. |
%%VMlocation: | global | local | For resources: which VM they load into. |
%%VMusage: | max min | For resources: memory they use. |
Version 3.0 replaced the per-kind comments of version 2.1 with the resource forms
above; these are still common and readers should accept them:
%%DocumentFonts:, %%DocumentFiles:,
%%DocumentProcSets:, %%DocumentNeededFonts:,
%%DocumentSuppliedFonts:, %%DocumentNeededFiles:,
%%DocumentSuppliedFiles:, %%DocumentNeededProcSets:,
%%DocumentSuppliedProcSets:, %%DocumentPaperColors:,
%%DocumentPaperForms:, %%DocumentPaperSizes:,
%%DocumentPaperWeights:.
Body and page
| Comment | Arguments | Meaning |
|---|---|---|
%%BeginDocument:, %%EndDocument | name [version [type]] | A whole document, such as an EPS file, included inside this one. |
%%IncludeDocument: | same | Ask the spooler to insert a document here. |
%%BeginFeature:, %%EndFeature | *Keyword [option] | Printer-specific code for a PPD feature, such as *PageSize A4. |
%%IncludeFeature: | same | Ask the spooler to insert the code for that feature. |
%%BeginResource:, %%EndResource | type name [max min] | A resource supplied in the file; the optional numbers are the most and least VM it uses. |
%%IncludeResource: | type name | Ask the spooler to insert a resource. |
%%PageMedia: | name | Paper for this page, from DocumentMedia. |
%%PageRequirements: | keywords | Requirements for this page. |
%%PageResources: | type name… | (atend) | Resources this page uses. |
%%BeginExitServer:, %%EndExitServer | password | Code that leaves the server loop to change persistent state. |
Also from version 2.1, still accepted: %%BeginFont:,
%%EndFont, %%IncludeFont:, %%BeginFile:,
%%EndFile, %%IncludeFile:, %%BeginProcSet:,
%%EndProcSet, %%IncludeProcSet:,
%%BeginPaperSize:, %%EndPaperSize,
%%PaperColor:, %%PaperForm:, %%PaperSize:,
%%PaperWeight:, %%PageFonts:, %%PageFiles:,
%%ExecuteFile:, %%ChangeFont: and
%%Feature:.
Colour separation conventions
| Comment | Arguments | Meaning |
|---|---|---|
%%DocumentProcessColors: | Cyan Magenta Yellow Black | (atend) | Process colours used in the document. |
%%DocumentCustomColors: | names | (atend) | Spot colours used. |
%%CMYKCustomColor: | c m y k name | A spot colour’s CMYK approximation. |
%%RGBCustomColor: | r g b name | A spot colour’s RGB approximation. |
%%PageProcessColors:, %%PageCustomColors: | as above | The same for one page. |
%%BeginProcessColor:, %%EndProcessColor | colour | Code that draws only on that process separation. |
%%BeginCustomColor:, %%EndCustomColor | name | Code that draws only on that spot separation. |
Query conventions
A file starting %!PS-Adobe-3.0 Query asks the printer questions. Each
query is code between a begin and an end comment; the end comment gives the default
answer for spoolers that answer for the printer.
| Begin | End | Asks about |
|---|---|---|
%?BeginQuery: identifier | %?EndQuery: default | Anything. |
%?BeginFeatureQuery: *Keyword | %?EndFeatureQuery: default | A PPD feature’s setting. |
%?BeginFileQuery: filename | %?EndFileQuery: default | Whether a file exists. |
%?BeginFontListQuery | %?EndFontListQuery: default | The fonts available. |
%?BeginFontQuery: fontnames | %?EndFontQuery: default | Whether fonts are available. |
%?BeginPrinterQuery | %?EndPrinterQuery: default | The printer’s product, version and revision. |
%?BeginProcSetQuery: procname | %?EndProcSetQuery: default | Whether a procset is loaded. |
%?BeginResourceQuery: type name | %?EndResourceQuery: default | Whether a resource is available. |
%?BeginResourceListQuery: type | %?EndResourceListQuery: default | The resources of a type. |
%?BeginVMStatus | %?EndVMStatus: default | Free memory. |
Encapsulated PostScript
An EPS file is a one-page DSC file with EPSF-3.0 on its first line and
a required %%BoundingBox, meant to be placed inside other documents. It
must not use operators that change the whole page or device, and may carry a preview.
Its rules are in Adobe Technical Note 5002 and on this site’s
EPS page.
Sources
- Adobe Technical Note #5001, PostScript Language Document Structuring Conventions Specification, version 3.0, 25 September 1992 – every comment above, its argument grammar and Appendix A (changes from version 2.1)
- Adobe Technical Note #5002, Encapsulated PostScript File Format Specification, version 3.0, 1 May 1992