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