[thirdparty/cups.git] / doc / help / spec-postscript.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<!-- SECTION: Specifications -->
<head>
	<title>Generating PostScript for CUPS</title>
	<meta name='keywords' content='Programming, PostScript, Document Structuring Conventions'>
	<link rel='stylesheet' type='text/css' href='../cups.css'>
</head>
<body>
<!--
  "$Id$"

  CUPS PostScript file specification for the Common UNIX Printing System (CUPS).

  Copyright 2007-2008 by Apple Inc.
  Copyright 2006 by Easy Software Products.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>

<p>This document describes how to generate PostScript output for
CUPS and is largely based on the <a
href="http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf">
Adobe TechNote #5001: PostScript Language Document Structuring
Conventions Specification Version 3.0</a>. While CUPS can
generally print any PostScript file, following the rules in the
Adobe TechNote and this document will ensure that your PostScript
output will work reliably.</p>

<blockquote><b>Note:</b> While PostScript is currently the
defacto-standard print job file format/language for UNIX-based
applications, it is slowly being phased out in favor of Adobe's
Portable Document Format ("PDF") which offers many advantages
over PostScript. Mac OS X uses PDF as the primary print job file
format and Linux is making the transition. Both PostScript and
PDF are complex formats, and we highly recommend using high-level
toolkits whenever possible to create your print jobs.</blockquote>

<h3>Anatomy of a PostScript File</h3>

<p>PostScript files are ASCII text files starting with a header
line (<tt>%!PS-Adobe-3.0</tt>) followed by a combination of
comment lines starting with the percent sign (<tt>%</tt>) and
PostScript code lines. The lines themselves should not exceed 255
characters to conform to the DSC. The following short PostScript
file produces a box with a smiley face in it:</p>

<pre class="command">
%!PS-Adobe-3.0
%%BoundingBox: 36 36 576 756
%%Pages: 1
%%LanguageLevel: 2
%%EndComments
%%BeginSetup
% this is where fonts would be embedded
%%EndSetup
%%Page: (1) 1
%%BeginPageSetup
% this is where page-specific features would be specified
%%EndPageSetup
% Draw a black box around the page
0 setgray
1 setlinewidth
36 36 540 720 rectstroke

% Draw a two inch blue circle in the middle of the page
0 0 1 setrgbcolor
306 396 144 0 360 arc closepath fill

% Draw two half inch yellow circles for eyes
1 1 0 setrgbcolor
252 432 36 0 360 arc closepath fill
360 432 36 0 360 arc closepath fill

% Draw the smile
1 setlinecap
18 setlinewidth
306 396 99 200 340 arc stroke

% Print it!
showpage
%%EOF
</pre>

<div class="figure"><table summary="Sample PostScript File Output">
<caption>Figure 1: <a name="FIGURE_1">Sample PostScript File Output</a></caption>
<tr><td align="center"><img src="../images/smiley.jpg"
width="445" height="570" alt="Sample PostScript File Output"></td></tr>
</table></div>


<h2><a name='OPTIONS'>Embedding Printer Options</a></h2>

<p>There are two main strategies for embedding printer options in PostScript
files. The first is to list CUPS options using the <code>%cupsJobTicket</code>
comment:</p>

<pre>
%!PS-Adobe-3.0
%cupsJobTicket: media=A4 sides=two-sided-long-edge
%cupsJobTicket: PrinterOption=foo PrinterOption2=bar
...
%%EndComments
</pre>

<p>CUPS options apply to the entire job. To apply options to individual pages,
use the <code>%%IncludeFeature</code> comment instead:</p>

<pre>
%%Page: label 123
%%BeginPageSetup
%%IncludeFeature: *PageSize A4
%%IncludeFeature: *PrinterOption Foo
%%IncludeFeature: *PrinterOption2 Bar
%%EndPageSetup
...
</pre>


<h2><a name='FONTS'>Embedding Fonts and Text</a></h2>

<p>Always embed the fonts used by your print job, and for best performance
embed the fonts and character encodings in the setup section of the PostScript
file. Type 1 and Type 3 fonts are supported by all PostScript printers, while
Type 42 (TrueType) and CID fonts are supported by most level 2 and all level 3
PostScript printers. Binary font files should always be converted to the
corresponding ASCII (hex) encoding to avoid problems when printing over
interfaces that do not support binary PostScript.</p>


<h2><a name='IMAGES'>Embedding Images</a></h2>

<p>The <code>image</code> operator should be used to embed images in PostScript
files. Always use ASCII hex or Base-85 encoding for the image data to avoid
problems when printing over interfaces that do not support binary PostScript.
In most cases, the Base-85 encoding and compression filters can be used to
embed images with very little, if any, increase in data size.</p>

</body>
</html>
Commit	Line	Data
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
	28	CUPS and is largely based on the <a
	29	href="http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf">
	30	Adobe TechNote #5001: PostScript Language Document Structuring
	31	Conventions Specification Version 3.0</a>. While CUPS can
	32	generally print any PostScript file, following the rules in the
	33	Adobe TechNote and this document will ensure that your PostScript
	34	output will work reliably.</p>
	35
	36	<blockquote><b>Note:</b> While PostScript is currently the
	37	defacto-standard print job file format/language for UNIX-based
	38	applications, it is slowly being phased out in favor of Adobe's
	39	Portable Document Format ("PDF") which offers many advantages
5f64df29 MS	40	over PostScript. Mac OS X uses PDF as the primary print job file
5f64df29 MS	41	format and Linux is making the transition. Both PostScript and
f7deaa1a	42	PDF are complex formats, and we highly recommend using high-level
5f64df29	43	toolkits 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
	48	line (<tt>%!PS-Adobe-3.0</tt>) followed by a combination of
5f64df29	49	comment lines starting with the percent sign (<tt>%</tt>) and
f7deaa1a	50	PostScript code lines. The lines themselves should not exceed 255
	51	characters to conform to the DSC. The following short PostScript
	52	file 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
	68	0 setgray
	69	1 setlinewidth
	70	36 36 540 720 rectstroke
	71
	72	% Draw a two inch blue circle in the middle of the page
	73	0 0 1 setrgbcolor
	74	306 396 144 0 360 arc closepath fill
	75
	76	% Draw two half inch yellow circles for eyes
	77	1 1 0 setrgbcolor
	78	252 432 36 0 360 arc closepath fill
	79	360 432 36 0 360 arc closepath fill
	80
	81	% Draw the smile
	82	1 setlinecap
	83	18 setlinewidth
	84	306 396 99 200 340 arc stroke
	85
	86	% Print it!
	87	showpage
	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"
	94	width="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
	101	files. The first is to list CUPS options using the <code>%cupsJobTicket</code>
	102	comment:</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,
	113	use 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
f7deaa1a	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
	129	embed the fonts and character encodings in the setup section of the PostScript
	130	file. Type 1 and Type 3 fonts are supported by all PostScript printers, while
	131	Type 42 (TrueType) and CID fonts are supported by most level 2 and all level 3
	132	PostScript printers. Binary font files should always be converted to the
	133	corresponding ASCII (hex) encoding to avoid problems when printing over
	134	interfaces 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
	140	files. Always use ASCII hex or Base-85 encoding for the image data to avoid
	141	problems when printing over interfaces that do not support binary PostScript.
	142	In most cases, the Base-85 encoding and compression filters can be used to
	143	embed images with very little, if any, increase in data size.</p>
f7deaa1a	144
	145	</body>
	146	</html>