1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- SECTION: Specifications -->
4<head>
5	<title>Generating PostScript for CUPS</title>
6	<meta name='keywords' content='Programming, PostScript, Document Structuring Conventions'>
7	<link rel='stylesheet' type='text/css' href='/cups-printable.css'>
8</head>
9<body>
10<!--
11  "$Id$"
12
13  CUPS PostScript file specification for CUPS.
14
15  Copyright 2007-2012 by Apple Inc.
16  Copyright 2006 by Easy Software Products.
17
18  These coded instructions, statements, and computer programs are the
19  property of Apple Inc. and are protected by Federal copyright
20  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
21  which should have been included with this file.  If this file is
22  file is missing or damaged, see the license at "http://www.cups.org/".
23-->
24
25<H1 CLASS="title">Generating PostScript for CUPS</H1>
26
27<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
28
29<p>This document describes how to generate PostScript output for
30CUPS and is largely based on the <a
31href="http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf">
32Adobe TechNote #5001: PostScript Language Document Structuring
33Conventions Specification Version 3.0</a>. While CUPS can
34generally print any PostScript file, following the rules in the
35Adobe TechNote and this document will ensure that your PostScript
36output will work reliably.</p>
37
38<blockquote><b>Note:</b> While PostScript is currently the
39de-facto standard print job file format/language for UNIX-based
40applications, it is slowly being phased out in favor of Adobe's
41Portable Document Format ("PDF") which offers many advantages
42over PostScript. OS X uses PDF as the primary print job file
43format and Linux is making the transition. Both PostScript and
44PDF are complex formats, and we highly recommend using high-level
45toolkits whenever possible to create your print jobs.</blockquote>
46
47<h3>Anatomy of a PostScript File</h3>
48
49<p>PostScript files are ASCII text files starting with a header
50line (<tt>%!PS-Adobe-3.0</tt>) followed by a combination of
51comment lines starting with the percent sign (<tt>%</tt>) and
52PostScript code lines. The lines themselves should not exceed 255
53characters to conform to the DSC. The following short PostScript
54file produces a box with a smiley face in it:</p>
55
56<pre class="command">
57%!PS-Adobe-3.0
58%%BoundingBox: 36 36 576 756
59%%Pages: 1
60%%LanguageLevel: 2
61%%EndComments
62%%BeginSetup
63% this is where fonts would be embedded
64%%EndSetup
65%%Page: (1) 1
66%%BeginPageSetup
67% this is where page-specific features would be specified
68%%EndPageSetup
69% Draw a black box around the page
700 setgray
711 setlinewidth
7236 36 540 720 rectstroke
73
74% Draw a two inch blue circle in the middle of the page
750 0 1 setrgbcolor
76306 396 144 0 360 arc closepath fill
77
78% Draw two half inch yellow circles for eyes
791 1 0 setrgbcolor
80252 432 36 0 360 arc closepath fill
81360 432 36 0 360 arc closepath fill
82
83% Draw the smile
841 setlinecap
8518 setlinewidth
86306 396 99 200 340 arc stroke
87
88% Print it!
89showpage
90%%EOF
91</pre>
92
93<div class="figure"><table summary="Sample PostScript File Output">
94<caption>Figure 1: <a name="FIGURE_1">Sample PostScript File Output</a></caption>
95<tr><td align="center"><img src="/images/smiley.jpg"
96width="445" height="570" alt="Sample PostScript File Output"></td></tr>
97</table></div>
98
99
100<h2><a name='OPTIONS'>Embedding Printer Options</a></h2>
101
102<p>There are two main strategies for embedding printer options in PostScript
103files. The first is to list CUPS options using the <code>%cupsJobTicket</code>
104comment:</p>
105
106<pre>
107%!PS-Adobe-3.0
108%cupsJobTicket: media=A4 sides=two-sided-long-edge
109%cupsJobTicket: PrinterOption=foo PrinterOption2=bar
110...
111%%EndComments
112</pre>
113
114<p>CUPS options apply to the entire job. To apply options to individual pages,
115use the <code>%%IncludeFeature</code> comment instead:</p>
116
117<pre>
118%%Page: label 123
119%%BeginPageSetup
120%%IncludeFeature: *PageSize A4
121%%IncludeFeature: *PrinterOption Foo
122%%IncludeFeature: *PrinterOption2 Bar
123%%EndPageSetup
124...
125</pre>
126
127
128<h2><a name='FONTS'>Embedding Fonts and Text</a></h2>
129
130<p>Always embed the fonts used by your print job, and for best performance
131embed the fonts and character encodings in the setup section of the PostScript
132file. Type 1 and Type 3 fonts are supported by all PostScript printers, while
133Type 42 (TrueType) and CID fonts are supported by most level 2 and all level 3
134PostScript printers. Binary font files should always be converted to the
135corresponding ASCII (hex) encoding to avoid problems when printing over
136interfaces that do not support binary PostScript.</p>
137
138
139<h2><a name='IMAGES'>Embedding Images</a></h2>
140
141<p>The <code>image</code> operator should be used to embed images in PostScript
142files. Always use ASCII hex or Base-85 encoding for the image data to avoid
143problems when printing over interfaces that do not support binary PostScript.
144In most cases, the Base-85 encoding and compression filters can be used to
145embed images with very little, if any, increase in data size.</p>
146
147</body>
148</html>
149