Description of the "postscriptfile" CUPS backend

#########################################################################
# In case, you're running this backend under MacOS X 10.3 Panther, you  #
# will be affected by a problem where the URL decoding routine cannot   #
# be started due to a change in OS internal security settings. As an    #
# effect you won't be able to let the files be saved in subfolders of   #
# $TARGET_BASEDIR -- they will always be stored in this folder.         #
# The most simple fix seems to be another executing shell: /bin/bash    #
# So simply edit the first line of the backend so that it reads         #
# '#!/bin/bash' instead of '#!/bin/sh' and you're done                  #
#########################################################################

What is it?
===========

The main purpose of this backend is to have the ability to print into
watched folders, so that output files can be postprocessed automatically by
tools like distiller, PStill, PDF Enhancer, GhostScript, whatever...

Actually with "PDF Services" in MacOS X 10.2.4 there is no big need for
that. But it still can save you some time and... you can use all those
mechanisms over the network, too. Just activate PrinterSharing on the 
machine this backend is installed or use hotfolders residing on network
shares and you're done.
(check the license conditions of your postprocessing software whether
you're allowed to use it in that way, please)

In 0.3.0 "folder actionscripts" have been added. In case, the backend will
find executable files called "actionscript-pre" or "actionscript-post" in
$TARGET_DIR, it will execute them before or after the printfile has been
saved to disk. The backend will provide these scripts with as much infos
as possible, to let them assist handling the PS/PDF files. You can have
a look at some examples: 

http://users.phg-online.de/tk/MOSXS/postscriptfile-stuff/actionscripts/

How do I use it?
================

You simply copy it into your CUPS backend folder (on MacOS X usually
/usr/libexec/cups/backend), ensure, that it is executable and restart
the cups daemon (eg. by sending it a SIGHUP signal to reread it's
configuration or by rebooting the machine)

Ah... and you'll have to configure a bit inside the script:

$TARGET_BASEDIR      should be set as a "base dir" for hotfolders. All paths
                     are relative to that
$MAX_FILENAME_LENGTH defines how long filenames should be. This is useful if
                     you want to postprocess the files by e.g. distiller
                     running in the "classic environment"
$DEBUG               set to TRUE to get some debug messages
$DEBUG_LOG           This is where the backend will write log messages to
                     in case, you set $DEBUG to TRUE
$GROUP               This settings affects the group ownership of the files
$FILE_PERMS          With which permissions the files will be saved
$AppToLaunch         Specify the path to an application that should be
                     launched when a job will be printed. For GhostScript
                     this defaults to /usr/local/bin/gs. If you set it to
                     "None" (or to an illegal path) then no postprocessor
                     will be launched automatically

Operational details:
====================

The behaviour of the backend depends on how it is called. If you save it as
postscriptfile, than all it advertises when you invoke the PrintCenter
(while holding down [option]) is a basic print-to-disk "device". You have to
take care, that you encode the path names you want to use correctly.

If the backend will be called as "distiller", then it will advertise all
subfolders of $TARGET_BASEDIR that meet specific criteria (an "In" folder
and a folder.joboptions file inside). If it will be called as "pstill" then
it searches for a "ProcessedPS" folder and an options file, that ends with
".pPref". If called as "pdfenhancer" it will search for "*.spe" files and
a folder called "Pending" used by PDF Enhancer.

If called as "ghostscript" then it will look for a folder called "Finished"
and an options file called "gs-options.txt". In this special case, it will 
not only store the resulting PDF or PS file into the watched folder but 
instead invoke GhostScript with the specific settings. For a detailed
description read below...

What if I want to use the backend for more than one sort of postprocessing
mechanism? Simply create symlinks to the basic backend, as the functionality
only depends on the name:

[imac-2:/usr/libexec/cups/backend/] tk# ls -la
lrwxr-xr-x   1 root  wheel     14 Mar 15 09:42 distiller -> postscriptfile
lrwxr-xr-x   1 root  wheel     14 Mar 15 09:42 ghostscript -> postscriptfile
lrwxr-xr-x   1 root  wheel     14 Mar 15 09:42 pdfenhancer -> postscriptfile
-rwxr-sr-x   1 root  wheel  12217 Mar 17 10:23 postscriptfile
lrwxr-xr-x   1 root  wheel     14 Mar 15 09:42 pstill -> postscriptfile

How to drive GhostScript?
=========================

As there currently doesn't exist a hotfolder scheme for GhostScript, we
simply define our own :-)

Create inside $TARGET_BASEDIR a new folder, containing a subfolder called
"Finished" and a simple textfile called "gs-options.txt". In this file you
write the settings you want GhostScript to use, eg.

-q
-dNOPAUSE
-dBATCH
-r2400
-sDEVICE=pdfwrite
-dPDFSETTINGS=/prepress
-dProcessColorModel=/DeviceCMYK
-dCompatibilityLevel=1.3

(It's strongly recommended that you always use the "-q", "-dNOPAUSE" and
"-dBATCH" options because otherwise unexpected behaviour will occur)

For a more detailed description of the settings and how to use custom 
image compression or advanced features with pdfmarks consult the GhostScript
documentation please: 

    http://www.cs.wisc.edu/~ghost/doc/AFPL/8.00/Ps2pdf.htm

Does this make sense at all?
============================

Maybe ;-)

You should know how printing in MacOS X works. Applications have basically
two ways to create output that will be postprocessed by printer drivers:

- PostScript (as we know it from former MacOS releases)
- PDF (the "standard" way in MacOS X)

As PDF is the basic technology for the Quartz display engine, most apps
simply create printer output by using Quartz. The result is a PDF file
(a mixture between PDF 1.2 and 1.3) that can be opened directly by any
PDF 1.3 aware viewer or renderer.

When printing through CUPS these PDF files will be converted to PostScript
when the specific printer queue has been assigned a PPD file (as it happens
always when you use the PrintCenter for adding new printers). Search for a
line with "cgpdftops" at the top of such PS files, to be sure how it has
been created.

Those applications that produce still PostScript output directly (mostly
from the desktop publishing sector), will write "pictwpstops" instead in the
"%%Creator: " comment.

As you see, normally you will convert PDFs from PDF to PostScript (invoked
by a CUPS filter) and then after leaving the spooling system back to PDF by
a postprocessing mechanism. Doesn't make always sense, except you're using
applications that are able to produce "real" PostScript...

Thomas Kaiser, 2003/03/17