doc/help/spec-postscript.html

   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 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 <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
  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
  42 over PostScript. Mac OS X uses PDF as the primary print job file
  43 format and Linux is making the transition. Both PostScript and
  44 PDF are complex formats, and we highly recommend using high-level
  45 toolkits 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
  50 line (<tt>%!PS-Adobe-3.0</tt>) followed by a combination of
  51 comment lines starting with the percent sign (<tt>%</tt>) and
  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
  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
  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
 100 <h2><a name='OPTIONS'>Embedding Printer Options</a></h2>
 101
 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>
 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,
 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>
 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
 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>
 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
 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>
 146
 147 </body>
 148 </html>