cups-programme
==============
http://felics.kettenbruch.de/software/cups-print-to-programme/
This is a filter for CUPS -- the [Common Unix Printing System][1] --
that will allow to create virtual printers to open the printed file in
an application.
The use case it was created for: The author of this software has a
printer which can only print black and white, and grayscales get
pixeladet due to dithering. Having small fonts in not 100% black makes
the text hardly readable because not all pixels are printed. With this
CUPS filter, the author can print from any application into The Gimp --
[GNU Image Manipulation Program][2] -- make exactly black & white there,
and print from The Gimp to the real printer.
Installation
------------
Install the printer backend executable to the path where CUPS stores
it's backends, and name it as the executable reports in the second
word when called with no arguments (=`cups-programme`). Under Arch Linux
and probably most other UNIX systems CUPS printer backends are in
`/usr/lib/cups/backend`, so you would install this print backend to
`/usr/lib/cups/backend/cups-programme`. Make sure it is executable by
at least the user `cupsd` runs as (e.g. `lp`), but beeing executable by
all is just fine. Make sure it is only writable by `root`, otherwise
CUPS will refuse to start the filter.
Install the configuration file to `/etc/cups/cups-programme.conf`, and
make sure it is readable at least by the user `cupsd` runs as.
Adding printers
---------------
This printer can be added using the CUPS webinterface with probably one
manual intervention.
When the backend has been properly installed, CUPS will show it under
"Local Printers" when you click "Add Printer" in the webinterface.
Select the printer. In the field "Connection", you need to specify the
Device URI. This is the part where the cups-programme printer get's
it's information which programme to execute.
The Device URI to print to The Gimp is, for example:
cups-programme:/usr/bin/gimp?u=.CUPSUSER&DISPLAY=%C0.0&%s
where `.CUPSUSER` will be replaced by the user who invoked the CUPS
print job (if CUPS can infer; otherwise most probably it will be the
user CUPS runs it's backends as, e.g. `lp`) ind will be the user `gimp`
should be run as. If `u=[...]` is not specified, it will be run as the
user CUPS is running it's backends as, which might not be desired. The
`DISPLAY=%C0.0` specifies the X11 display to use. In most cases, `:0.0`
is correct (`%C` will be replaced by `:`).
See section "Device URI syntax" for a full description of the Device
URI.
After the Device URI has been entered, select a name and optionally a
description and a location note for the printer. Then you are presented
with a list of printer manufacturers and models to choose from. Select
the manufacturer `Generic` and any generic PostScript printer. (This
selects a PPD file for the printer. Since we just want to open (or later
convert -- see section "Configuration File") the raw CUPS PostScript
output, just select any PostScript printer and then ignore the printer
options is fine.)
Adding the printer might fail with an error like
Bad device-uri "cups-programme:/usr/bin/gimp?[...]"
In this case, when specifying the Device URI, just type in
`cups-programme:` (e.g.
`cups-programme:/usr/bin/gimp`) and add the printer as described. After
the printer has been added, stop CUPS (e.g. by entering
`systemctl cupsd stop` or `/etc/init.d/cupsd stop` as root on the
command line) and edit the file `/etc/cups/printers.conf`. Find the
printer you just added and complete the Device URI manually by editing
the entry starting with `DeviceURI`. Save your edits, and start CUPS
again (e.g. by typing `systemctl start cupsd` or
`/etc/init.d/cupsd start`).
Now the virtual printer should be functional.
Device URI syntax
-----------------
In general, the syntax for the Device URI is:
cups-programme:?
where:
* Only the charaters out of the set
[][)(}{äÄöÖüÜß.:,;_@^°§%&/=?+*~a-zA-Z0-9-]
are allowed. (Use `%`-replacements, if you need some of forbidden,
characters, see below. For example, the characters ` `, `"`, `'`,
`` ` ``, `$`, `!`, `#`, `<`, `>`, `|`, `\` are forbidden.)
* `` needs to be an absolute path, starting with `/`
(otherwise CUPS will complain that it is not a correct URI; it expects
a `/` after the `:`),
* `?` is optional and has the syntax
`?