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