doc/help/spec-postscript.html

   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
  15   Copyright 2007-2008 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 <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
  40 over PostScript. Mac OS X uses PDF as the primary print job file
  41 format and Linux is making the transition. Both PostScript and
  42 PDF are complex formats, and we highly recommend using high-level
  43 toolkits whenever possible to create your print jobs.</blockquote>
  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
  49 comment lines starting with the percent sign (<tt>%</tt>) and
  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
  60 %%BeginSetup
  61 % this is where fonts would be embedded
  62 %%EndSetup
  63 %%Page: (1) 1
  64 %%BeginPageSetup
  65 % this is where page-specific features would be specified
  66 %%EndPageSetup
  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
  98 <h2><a name='OPTIONS'>Embedding Printer Options</a></h2>
  99
 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>
 103
 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>
 124
 125
 126 <h2><a name='FONTS'>Embedding Fonts and Text</a></h2>
 127
 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>
 135
 136
 137 <h2><a name='IMAGES'>Embedding Images</a></h2>
 138
 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>
 144
 145 </body>
 146 </html>