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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/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-printable.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/".
-->

<H1 CLASS="title">Generating PostScript for CUPS</H1>

<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
745129be	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
f7deaa1a	2	<html>
	3	<!-- SECTION: Specifications -->
	4	<head>
	5	<title>Generating PostScript for CUPS</title>
	6	<meta name='keywords' content='Programming, PostScript, Document Structuring Conventions'>
178cb736	7	<link rel='stylesheet' type='text/css' href='../cups-printable.css'>
f7deaa1a	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	-->
f7deaa1a	24
178cb736 MS	25	<H1 CLASS="title">Generating PostScript for CUPS</H1>
178cb736 MS	26
f7deaa1a	27	<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
	28
	29	<p>This document describes how to generate PostScript output for
	30	CUPS and is largely based on the <a
	31	href="http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf">
	32	Adobe TechNote #5001: PostScript Language Document Structuring
	33	Conventions Specification Version 3.0</a>. While CUPS can
	34	generally print any PostScript file, following the rules in the
	35	Adobe TechNote and this document will ensure that your PostScript
	36	output will work reliably.</p>
	37
	38	<blockquote><b>Note:</b> While PostScript is currently the
	39	defacto-standard print job file format/language for UNIX-based
	40	applications, it is slowly being phased out in favor of Adobe's
	41	Portable Document Format ("PDF") which offers many advantages
5f64df29 MS	42	over PostScript. Mac OS X uses PDF as the primary print job file
5f64df29 MS	43	format and Linux is making the transition. Both PostScript and
f7deaa1a	44	PDF are complex formats, and we highly recommend using high-level
5f64df29	45	toolkits whenever possible to create your print jobs.</blockquote>
f7deaa1a	46
	47	<h3>Anatomy of a PostScript File</h3>
	48
	49	<p>PostScript files are ASCII text files starting with a header
	50	line (<tt>%!PS-Adobe-3.0</tt>) followed by a combination of
5f64df29	51	comment lines starting with the percent sign (<tt>%</tt>) and
f7deaa1a	52	PostScript code lines. The lines themselves should not exceed 255
	53	characters to conform to the DSC. The following short PostScript
	54	file 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
5f64df29 MS	62	%%BeginSetup
	63	% this is where fonts would be embedded
	64	%%EndSetup
f7deaa1a	65	%%Page: (1) 1
5f64df29 MS	66	%%BeginPageSetup
	67	% this is where page-specific features would be specified
	68	%%EndPageSetup
f7deaa1a	69	% Draw a black box around the page
	70	0 setgray
	71	1 setlinewidth
	72	36 36 540 720 rectstroke
	73
	74	% Draw a two inch blue circle in the middle of the page
	75	0 0 1 setrgbcolor
	76	306 396 144 0 360 arc closepath fill
	77
	78	% Draw two half inch yellow circles for eyes
	79	1 1 0 setrgbcolor
	80	252 432 36 0 360 arc closepath fill
	81	360 432 36 0 360 arc closepath fill
	82
	83	% Draw the smile
	84	1 setlinecap
	85	18 setlinewidth
	86	306 396 99 200 340 arc stroke
	87
	88	% Print it!
	89	showpage
	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"
	96	width="445" height="570" alt="Sample PostScript File Output"></td></tr>
	97	</table></div>
	98
	99
5f64df29	100	<h2><a name='OPTIONS'>Embedding Printer Options</a></h2>
f7deaa1a	101
5f64df29 MS	102	<p>There are two main strategies for embedding printer options in PostScript
	103	files. The first is to list CUPS options using the <code>%cupsJobTicket</code>
	104	comment:</p>
f7deaa1a	105
5f64df29 MS	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,
	115	use 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>
f7deaa1a	126
f7deaa1a	127
5f64df29	128	<h2><a name='FONTS'>Embedding Fonts and Text</a></h2>
f7deaa1a	129
5f64df29 MS	130	<p>Always embed the fonts used by your print job, and for best performance
	131	embed the fonts and character encodings in the setup section of the PostScript
	132	file. Type 1 and Type 3 fonts are supported by all PostScript printers, while
	133	Type 42 (TrueType) and CID fonts are supported by most level 2 and all level 3
	134	PostScript printers. Binary font files should always be converted to the
	135	corresponding ASCII (hex) encoding to avoid problems when printing over
	136	interfaces that do not support binary PostScript.</p>
f7deaa1a	137
f7deaa1a	138
5f64df29	139	<h2><a name='IMAGES'>Embedding Images</a></h2>
f7deaa1a	140
5f64df29 MS	141	<p>The <code>image</code> operator should be used to embed images in PostScript
	142	files. Always use ASCII hex or Base-85 encoding for the image data to avoid
	143	problems when printing over interfaces that do not support binary PostScript.
	144	In most cases, the Base-85 encoding and compression filters can be used to
	145	embed images with very little, if any, increase in data size.</p>
f7deaa1a	146
	147	</body>
	148	</html>