# Generating PostScript for CUPS

## Introduction

This document describes how to generate PostScript output for CUPS and is largely based on the Adobe TechNote #5001: PostScript Language Document Structuring Conventions Specification Version 3.0. 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.

> Note: While PostScript is currently the de-facto 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. macOS 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.

### Anatomy of a PostScript File

PostScript files are ASCII text files starting with a header line (`%!PS-Adobe-3.0`) followed by a combination of comment lines starting with the percent sign (`%`) 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:

    %!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

Figure 1: Sample PostScript File Output

## Embedding Printer Options

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

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

CUPS options apply to the entire job. To apply options to individual pages, use the `%%IncludeFeature` comment instead:

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

## Embedding Fonts and Text

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.

## Embedding Images

The `image` 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.