apsfilter handbook, 2nd ed.
Author: Michael Loßin

#
apsfilter handbook, 2nd ed.

Michael Loßin
(c) 2001,2002 -- distributable under the GPL

# Table of Contents

1 Preface

- 1.1 Abstract
- 1.2 About this document
- 1.3 Conventions

2 Introduction

- 2.1 What is it?
- 2.2 What is it not?
- 2.3 Why should I use it?
- 2.4 Why shouldn't I use it?
- 2.5 Is it for me?

3 Installation

- 3.1 Preparation
- 3.2 Installation procedure
- 3.3 System specific notes
  - 3.3.1 SuSE Linux
  - 3.3.2 FreeBSD
  - 3.3.3 Solaris

4 Setup

- 4.1 Preparation
  - 4.1.1 License
  - 4.1.2 Spool directory
  - 4.1.3 Printcap entries
- 4.2 Main menu
  - 4.2.1 Available drivers
  - 4.2.2 Ghostscript documentation
  - 4.2.3 Driver selection
  - 4.2.4 Interface
  - 4.2.5 Paper format
  - 4.2.6 Printing quality
  - 4.2.7 Color mode
  - 4.2.8 Resolution
  - 4.2.9 Printing method
  - 4.2.10 Test page
  - 4.2.11 Performance log
  - 4.2.12 Abort
  - 4.2.13 Installation
  - 4.2.14 Finish setup
- 4.3 Tips and tricks

5 Usage

- 5.1 Normal operation
- 5.2 Special features
  - 5.2.1 Fake duplex
  - 5.2.2 Fast copies
- 5.3 Printing to a file
- 5.4 Preview before printing

6 Configuration

- 6.1 Configuration files
  - 6.1.1 apsfilterrc (global, local)
  - 6.1.2 apsfilterrc (user specific)
  - 6.1.3 restrictions (global, local)
  - 6.1.4 smbclient.conf (local)
  - 6.1.5 netware.conf (local)
  - 6.1.6 lpr.conf (local)
  - 6.1.7 pap.conf (local)
- 6.2 Command line options
- 6.3 Configuration notes
  - 6.3.1 Landscape and N-up printing
  - 6.3.2 Page order in fake duplex mode

7 FAQ

- 7.1 Error messages
- 7.2 Printing failures
- 7.3 Tuning

8 Links

- 8.1 Third party software
- 8.2 Further information

9 Help

- 9.1 You help us
- 9.2 We help you
  - 9.2.1 Reporting bugs
  - 9.2.2 General help

# 1 Preface

## 1.1 Abstract

This handbook explains how to set up, operate, configure and extend the apsfilter package while providing a step-by-step installation guide. It is focused on apsfilter version 7.2.7 and compatible.

## 1.2 About this document

You are looking at the second edition of the apsfilter handbook. It was written by Michael Loßin <phallobst@web.de> (© 2001,2002) and has been published under the regulations of the GPL.

It is available as indexed HTML, PostScript, PDF (with links) and plain text. These editions are generated from a source HTML file by `htmldoc` and `w3m`.

The colorful apsfilter logo was created by Chris Cox <cjcox@acm.org>.

If you feel something important is missing, if you find blatant typos or obsolete information, please contact the mailing-list at <apsfilter-doc@apsfilter.org>.

## 1.3 Conventions

Throughout this document we'll use the following typographical conventions:

`foobar`
  1. absolute or relative path names
  2. computer input and output
foobar
  1. emphasis
  2. software package names (as opposed to `executables`)
`#`
  the root prompt
`$`
  the user prompt
`$FOOBAR`
  environment variables
`FOOBAR`
  configuration variables

# 2 Introduction

## 2.1 What is it?

Apsfilter is an input filter suitable for most of the printer spoolers found on many UNIX-like operating systems. It is used all over the world in many different environments, from single user desktop computers to large-scale university networks.

The goal of apsfilter is to provide the user and the system administrator with a simple way to maintain, configure and use the printing services of the UNIX system. It's not targeted at one particular flavour or distribution of UNIX -- apsfilter tries to behave as friendly as possible in any environment.

The latest major version of apsfilter is 7.0.0 which was released in December 2001. There are also development snapshots and a CVS repository available. Point your web browser to the Apsfilter Homepage at http://www.apsfilter.org/ for a better overview of the latest releases.

The maintainer and copyright owner of apsfilter is Andreas Klemm <andreas@apsfilter.org>; he coordinates releases, merges patches from contributors and does stuff. Do not send bug reports or help requests to this email address -- there are mailing-lists that will save you (and us) the hassle of long fights with apsfilter.

## 2.2 What is it not?

Apsfilter is not a printer driver collection. It completely relies on ghostscript to provide a driver, since it only prepares the input data, primarily by converting it to PostScript.

It also does not provide a printer spooler system, but instead it utilizes services offered by the BSD spooler or its successor LPRng.

## 2.3 Why should I use it?

- it's free: the GPL ensures that it will always be
- it's flexible: you can print almost any kind of file (with the help of various conversion tools):

  > ASCII (more precisely: all sorts of text), BMP, DVI, FBM, FIG, FITS, GIF, Group 3 fax, HTML, IFF ILBM, JPEG, Kodak Photo CD, MGR, MIFF, PDF, PNG, PNM, PostScript, RLE, SGI, Sketch, Sun raster, Targa, TGIF, TIFF, troff, WMF, WordPerfect graphics, XCF, X pixmap, X window dump

- it works: more precisely, it works right out of the box -- no compilation necessary
- it's extendable: new file formats, new drivers, new converters have always been integrated without much hassle
- it's simple: a couple of printer-independent command line options allow you to control certain aspects of file formatting, visual appearance etc. without having to know which printer or driver you are using
- it uses free components: other programmers already have invented the wheel, so we use their work and do some plumbing to produce The Right Thing
- it's a script: using shell programming tools allows anyone to inspect the source, produce verbose debugging information, test changes quickly and fiddle around to adjust apsfilter to their system

So you see: apsfilter is the best sliced bread since... uhm... no, wait...

## 2.4 Why shouldn't I use it?

- it's simple: restricting the dynamic options to a manageable size automatically leads to driver features being inaccessible (however, we try to offer at least a reasonable selection, and you can always adjust the default options to your needs)
- it's not GUI'd: beginners might be deterred by having to use the command line instead of a visually appealing configuration dialog (anybody willing to write `kapsprint`?)
- it uses external components: you have to install at least a couple of other packages to get a working printing system; these may come with their own bugs, which could make apsfilter look buggy itself -- what a silly idea :)
- it's limited: you can't make coffee with apsfilter, but we're working on it

## 2.5 Is it for me?

Yes, it is.

Maybe.

# 3 Installation

## 3.1 Preparation

Since apsfilter is by no means a self-contained system, you'll have to make sure you have some third-party packages installed. (The links section will refer you to the web pages.)

Your printer spooler must be either the plain BSD-type lpd (which is not only part of the *BSD systems, but also of many Linux distributions) or (highly recommended) the "next generation" spooler called LPRng (which is also compatible to the BSD version). Other spooler types may work, but those are not officially supported by apsfilter.

A very important program is the shell (usually `/bin/sh`), which has to support a couple of POSIX features. If you already have it, bash is a good choice, but recent versions of zsh, pdksh or ash are reported to work as well. You may need to supply the path to a capable shell during installation.

We need awk in a couple of places, so a decent version should be accessible (e.g. GNU awk). The `configure` script has an option for this as well.

If you are not operating a PostScript capable printer, you'll need the free PostScript interpreter ghostscript which has the correct driver for your printer compiled into it. Both the GNU and the AFPL (a.k.a. Aladdin) versions work, although you probably better install the latest version to get full driver support.

The psutils collection is highly recommended to perform non-trivial PostScript processing. Another tool we need is `psset` from the a2ps package; so even if you prefer a different text-to-PostScript converter, you'll have to install it anyway.

For any file format you want to be handled automagically, you'll need a converter, e.g.

- for bitmap images: `convert` (from ImageMagick), `nconvert` (from XnView) or the netpbm tools (a.k.a. pbmplus)
- for text files: `a2ps`, `mpage`, `enscript` or (without fancy formatting features) `recode`
- miscellaneous: `dvips`, `fig2dev` (from transfig), `groff`, `htmldoc`, `html2ps`, `acroread`, `pdftops`, `sk2ps`

Transparent handling of compressed files is supported for the gzip, bzip2, compress, freeze, pack and lzop compression styles.

Error reporting and notification messages need a working sendmail installation, although it is possible to do without it. However, you won't be able to use "fake duplex mode".

And most importantly: if you don't just want to use the "print to file" feature, you'll need a working printer (don't laugh) -- apsfilter can't fix hardware problems. Please have a look at your system documentation (e.g. Printing-HOWTO, Linux documentation of the parport device, man pages to stty and setserial in case of a serial printer etc.) to ensure your printer reacts properly on data sent directly to the interface.

## 3.2 Installation procedure

If your OS vendor is able to provide you with an apsfilter package of some kind, get that and install it the usual way. Please bear in mind that support for those packages is only available from the package maintainers.

Otherwise follow these steps:

>     $ gzip -cd /path/to/apsfilter-X.Y.Z.tar.gz | tar xf -
>             (if you downloaded the gzip'ped version)
>     $ bzip2 -cd /path/to/apsfilter-X.Y.Z.tar.bz2 | tar xf -
>             (if you downloaded the bzip'ped version)
>     $ cd apsfilter
>     $ ./configure
>     	(you might want to give options; see "./configure --help")
>     $ su -
>     Password:
>     # make install

You can optionally copy the contributed uniprint profiles into your ghostscript "lib" directory -- if you don't intend to use the uniprint driver, or use a different printer, these won't help you. Recent packages of ghostscript may already contain them.

>     # cp uniprint/*.upp /path/to/ghostscript/version/lib

## 3.3 System specific notes

Here's a list of known limitations, bugs and incompatibilities of various UNIX systems. If you happen to know problems with these or other system types which are not addressed here, please contact us at <apsfilter-hackers@apsfilter.org>.

### 3.3.1 SuSE Linux

SuSE ships with a modified version of apsfilter which is derived from an earlier release (of the 4.x series). These are incompatible in installation and usage, and support for their version is only available from SuSE.

However, you can uninstall the SuSE package and install the original tarball without any problems. In this case, installing printers is only possible with the `SETUP` script, not via `yast` or other SuSE configuration tools.

### 3.3.2 FreeBSD

Users of older FreeBSD systems (3.4 and earlier) need to apply the following patch to the plain BSD-lpr program (not the LPRng version) to use the advanced features of apsfilter:

    Index: lpr.c
    ===================================================================
    RCS file: /home/ncvs/src/usr.sbin/lpr/lpr/lpr.c,v
    retrieving revision 1.32
    diff -u -r1.32 lpr.c
    --- lpr.c	2000/01/19 14:25:08	1.32
    +++ lpr.c	2000/04/05 09:36:01
    @@ -320,7 +320,7 @@
     	seteuid(uid);
     	card('H', host);
     	card('P', person);
    -	if (hdr && !pp->no_header) {
    +	if (hdr) {
     		if (jobname == NULL) {
     			if (argc == 0)
     				jobname = "stdin";

This patch may have already been applied to newer versions of `lpr`.

### 3.3.3 Solaris

Using apsfilter under Solaris will not work with the bundled printer spooler system (`lpadmin`, `lpsched` et al.), so you'll have to install LPRng instead.

The default Solaris shell `/bin/sh` is an old release of the Korn shell which unfortunately doesn't work with apsfilter. Please call the `configure` script with the "--with-shell=..." option if a POSIX compliant shell can't be detected.

The same applies to `awk`. If a suitable version can't be found, you can pass the path via the "--with-awk=..." option.

Solaris' own `file` command might not be able to recognize all supported file types correctly. In case of problems, get the free implementation.

# 4 Setup

If you are of the paranoid kind, you might want to disable the currently running `lpd` before you change your spooler setup. Please consult the appropriate system documentation to see what steps are required to do this.

The `SETUP` is a shell script which resides in the top-level apsfilter installation directory. To start, please execute the script via the (absolute or relative) path name:

>     # /usr/pkg/share/apsfilter/SETUP

No graphics-intensive magic is needed -- a 80x25 text console should suffice to proceed through the setup.

For listings that are likely to need more screen estate, the environment variable `$PAGER` will supply the default pager program -- if it is unset or empty, `more` will be used.

## 4.1 Preparation

In the first couple of screens, various information is gathered in order to adapt `SETUP` to your system environment.

### 4.1.1 License

The current apsfilter license requires you to send a postcard to Andreas Klemm. You can get his snail-mail address by sending an e-mail to apsfilter-snailmail@apsfilter.org, which you can do directly during the SETUP process, or later (e.g. if `sendmail` is not available).

### 4.1.2 Spool directory

The printer spooler daemon uses an additional directory (one for each printer) to buffer the files which are about to be printed, along with various administration data (e.g. log files). It is important that the owner, group and permission settings of this spool directory match the requirements of the spooler -- if in doubt, consult the documentation.

Do not use a directory on a shared or networked filesystem for this purpose!

LPRng users can simply accept all settings, since the `checkpc` program will be called later to ensure everything is correct.

### 4.1.3 Printcap entries

Before you can do harm to your `/etc/printcap`, a backup copy will be saved to `/etc/printcap.old` and (if it doesn't already exist) to `/etc/printcap.orig`.

If you want to overwrite the previous entries in `/etc/printcap`, `SETUP` will delete all apsfilter-related items, but won't touch anything else. It is not (yet) possible to overwrite just one entry.

Normally you'd want to choose to add another printer, so this is also the default.

## 4.2 Main menu

The main menu is the central screen during the setup -- here you can see the current settings (in square brackets), adjust them, install printers, print test pages etc. Enter one of the keys displayed in parentheses to change certain values or perform actions.

### 4.2.1 Available drivers

Any printer driver (with the single exception of a true PostScript printer) needs to be included in the ghostscript binary `gs` in order to be usable. Some drivers are part of the ghostscript distribution, but are not compiled into `gs` by default, while others produce raster images (e.g. JPEG, TIFF, PNG, PNM) which are not suitable for direct printer input. You can also use a number of third-party drivers.

To see which drivers are known to `gs`, and also which version you are using, enter `d` at the prompt. The list is alphabetically sorted.

### 4.2.2 Ghostscript documentation

In case you haven't already read the ghostscript documentation, a text-only rendering of `Devices.htm` suitable for your `gs` release can be viewed. Select `r` to read it.

### 4.2.3 Driver selection

This is the most important part of `SETUP`, since the correct driver is the key component to ensure smooth interaction of apsfilter and your printer. Choosing a driver which is not supported by `gs` will be intercepted by `SETUP`.

Usually, you will be presented a list of printer models, preceded by a number. Just enter this number at the prompt, or `0` to select a different type of driver, or just press `RETURN` to see the list again.

If you see a comment in the list of the form `{foo+bar}` it means that the ghostscript driver named foo is used to create an intermediate data stream which the external tool bar converts into a format suitable for the printer.

#### 4.2.3.1 PostScript printer (generic)

This is the only "driver" that will actually bypass ghostscript, so we assume the printer is able to understand PostScript Level 2 (which is what most applications and converters produce).

This kind of queue is also useful if you want to post-process the output from apsfilter with a third-party printer driver. These packages usually expect PostScript files to arrive at their own printer filter, so that they can call `gs` and/or their driver.

#### 4.2.3.2 PostScript printer (with ghostscript drivers)

This is similar to the "generic" driver, but the input will be passed through ghostscript's special "pswrite", "psgray" or "psmono" devices. This allows you to set options for `gs`, use disk based fonts etc.

#### 4.2.3.3 printer driver natively supported by ghostscript

Here you can see a list of drivers that are part of the original ghostscript package (matching the version on your system).

Note: Not all drivers are compiled into `gs` by default; you might have to adjust the ghostscript `Makefile` to get full support for all drivers, then re-compile.

#### 4.2.3.4 gimp-print (stp or ijs driver)

This high-quality driver supports many inkjet printers and is especially targeted at photo printers.

You have two choices for gimp-print: the classic ghostscript interface via the "stp" driver or the client for the new "ijs" server within ghostscript. The features are the same for these two, but the interfaces need different parameters internally.

#### 4.2.3.5 hpdj

As the name might give away, this driver mostly supports DeskJet printers by HP. You might succeed to operate compatible printers as well.

This driver has been superseded by pcl3, written by the same author.

#### 4.2.3.6 pcl3 (successor to hpdj)

Since the hpdj driver has been discontinued, you should try its successor. The pcl3 driver knows a wider range of HP models, and other PCL-aware printers may also work.

#### 4.2.3.7 IBM Omni

This driver collection emerged from the OS/2 driver support and covers a very wide range of inkjet and dot matrix printers.

#### 4.2.3.8 various HP Deskjet drivers

A collection of drivers for a number of HP printers.

#### 4.2.3.9 PPA printer

PPA is a closed source printing protocol used under some other operating system. It had to be reverse-engineered to provide support for these HP printers. You'll need `pnm2ppa` to automatically convert the data stream into a usable format for them.

#### 4.2.3.10 HP DeskJet printer (official drivers)

These drivers, based on the "Inkjet Server" technology, are already part of the latest ghostscript releases, but can be built into older versions manually.

There's one list for the older ghostscript interface ("hpijs", version 0.97 and earlier) and one for its successor ("ijs", version 1.0 and later).

#### 4.2.3.11 Epson printer (official drivers)

The Epson laser printer drivers are available as an add-on to ghostscript, while the pips driver collection consists of tools that convert PNG data into the printer language.

#### 4.2.3.12 Lexmark inkjet printer

Some programmers (not at Lexmark, of course) have created drivers for Lexmark inkjets.

#### 4.2.3.13 miscellaneous other drivers

Those drivers which don't really fit into the other categories are assembled in this list.

#### 4.2.3.14 non-printer devices

Caution! These devices do not produce data which is suitable for any printer (unless you have a really special kind). They are only useful in a printer queue which is exclusively used by "printing to file" (`aps2file`), since the output file will be either PDF or an image format.

If you want to use one of these drivers, it's highly recommended that you install the queue as a normal local printer (with a parallel interface connection), but set the device node to `/dev/null` to avoid unpleasant surprises if some user accidentally wants to print to this queue in the usual way. Note that using `/dev/null` has no impact on the functionality of `aps2file`.

Another way of restricting the use of the printer queue is to disable it on the spooler level -- `aps2file` bypasses the spooler mechanism and only needs access to the configuration files. In this case the user will get an error message for any print attempt to that queue. However, it's necessary to make sure that the queue is not re-enabled (e.g. at system reboot).

### 4.2.4 Interface

The physical connection to the printer can either be local (via the parallel, USB or serial cable) or through the network. In the latter case, you can choose between normal UNIX-style connections (lpd on the remote host), SAMBA to talk to Windows-served printers (SMB protocol), AppleTalk for Mac-based printers (via netatalk/pap) or Novell NetWare printer servers (with ncprint or nprint).

#### 4.2.4.1 Parallel or USB connection

You only need to enter the full path to the device node -- that's it.

#### 4.2.4.2 Serial connection

Besides the device node name, we also need a couple of protocol specifications here: baud rate, handshaking (flow control) and the data word format.

#### 4.2.4.3 Unix network printer

The remote printer name (FQDN or IP address) and the remote queue name are needed for `lpd`-type network printers, including printer servers built into (or attached to) the printer itself.

Users of JetDirect interface cards must use "raw" as the queue name; other queues (such as "text" or "ascii") are not useful.

#### 4.2.4.4 Windows / Samba

Your Windows administrator should be able to provide you with the various SMB/samba settings. If you choose to use a real user name (plus password), the configuration file will not be world-readable (to protect the innocent).

#### 4.2.4.5 AppleTalk

This connection only requires the name of the printer as provided by the Apple server.

#### 4.2.4.6 Novell NetWare

Contact your local NetWare guru to get the correct connection parameters for the server, queue and user name. If you don't need a password, just leave it empty.

Note: Both `ncprint` (for BSD) and `nprint` (for Linux) are supported for NetWare connections.

### 4.2.5 Paper format

The default paper size can be overridden by the user on the command line, but you definitely should set it to the paper format which is most likely to be used. There are far more paper formats known to mankind, but A4, A3, Letter, Legal, Tabloid and Ledger are the ones that are supported by the majority of conversion tools used by apsfilter.

Note: There seems to be quite some confusion about the correct handling of "ledger" vs. "tabloid" vs. "11x17". The most common usage seems to be that ledger is 17''x11'' and tabloid is 11''x17'' (some tools, including ghostscript, even call it 11x17). So we use ledger as the landscape mode of tabloid (and vice versa).

### 4.2.6 Printing quality

This is another setting which merely provides a default value for the user; a different printing quality can be passed on the command line. However, "medium" should be suitable for most printing tasks.

Please bear in mind that those categories don't represent absolute values -- they are driver specific, and relative to its abilities. So "photo" quality on a cheap dot matrix printer might still be worse than "draft" on a high-class laser printer.

### 4.2.7 Color mode

Selecting the correct color mode does not only influence the dithering of color in the output, but has also an impact on the processing speed: many converters run faster if they are told to produce monochrome or grayscale output.

Since this default setting can also be overridden by the user, it's probably best to set it to "full color", just to be sure. Only if your printer has no color ability, it makes sense to use "gray" or "mono".

### 4.2.8 Resolution

The printing resolution (in dots per inch) is only needed to provide a default for drivers that don't derive it from the quality setting. Currently this includes PostScript printers (with or without the use of ghostscript) and uniprint profiles, besides others.

However, it is recommended to set it to a reasonable value anyway, since this setting will also appear (as a comment) in the `/etc/printcap` database and in listings produced by `lpq`.

### 4.2.9 Printing method

For most cases, the printing method will be set to the default value "auto"; this will cause apsfilter to check the type of any input file and convert it to the correct printer language automagically.

However, if you want data to be passed unmodified (e.g. if you get printing requests over the network), you must set it to "raw"; you can also set it to "ascii" to trick apsfilter into thinking that everything is a text file.

The default printing method can be overwritten with a command line option.

### 4.2.10 Test page

To test the current settings, you can send a test page to the printer. This will not use the `lpd` mechanism, but rather contact the printer directly (unless you print to a UNIX-style network printer).

If your current driver selection requires an additional external filter to be used (e.g. `pnm2ppa`), it must be accessible in the `PATH`. In case of an error, please install the appropriate filter program or adjust the `PATH` setting at the top of the `SETUP` script.

Note: You need to set up your printer type, interface and paper size to be able to print a test page.

### 4.2.11 Performance log

After you have printed at least one test page, you can check how long it took to (a) create and (b) actually print the data. Thus you can adjust the default quality and color settings to decent values, and even use a different driver.

Note: You need to set up your printer type, interface and paper size to be able to print a test page and view the performance log.

### 4.2.12 Abort

In case of a panic attack, just leave `SETUP` with no further changes to your system. This is basically the same as pressing `Ctrl-c`.

### 4.2.13 Installation

If you think all settings are correct, you can install the printer; this will create an entry in `/etc/printcap`, add the spool directories and put one or more configuration files into the queue configuration directory.

But first you are prompted for a queue name; this will be used to select the correct printer queue, if you happen to have more than one. The default name is `lp` (if possible) or `apsN` (where `N` is a number). This is guaranteed to be free to use.

If you are using the LPRng spooler, a system cleanup will be performed by calling `checkpc`, which will ensure that all permissions are correct and all necessary files are in place.

Note: You need to set up your printer type, interface and paper size to be able to install the printer entry.

### 4.2.14 Finish setup

After your printers are installed, all parameter settings from `SETUP` are saved to `/usr/pkg/etc/apsfilter/SETUP.cfg`; these will be re-read the next time you want to install a printer.

At this point `/etc/printcap` has changed, so you have to tell your spooler daemon to use the new values. Please use the command corresponding to your spooler type:

LPRng
  `lpc reread`
BSD-lpd
  `lpc restart all`
others
  `/etc/rc.d/init.d/lpd restart`
  (adjust this to your OS)

## 4.3 Tips and tricks

There's only little magic attached to the printer driver name. If you need some other driver which isn't listed, simply install a different driver and change the setting in `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc` manually. However, it is necessary to provide a driver script if you want to use advanced features of your driver.

The stcolor driver is the only one that causes `SETUP` to write an additional configuration variable into the local file:

>     PS_INIT='stcolor.ps'

This setting won't be used for all other drivers (although it is harmless in those cases).

`SETUP` creates a comment for all entries in `/etc/printcap` which will be displayed by `lpq`. It shows the default settings for quality, resolution etc., but you can change it to whatever fits you. For non-printer devices, it might be useful to explicitly state that the printer queue is primarily targeted at "print-to-file" mode.

# 5 Usage

## 5.1 Normal operation

As every input filter for printer spoolers, apsfilter is not really designed to be called directly on the command line, but it rather links itself into the lpd mechanism for print job processing via the `/etc/printcap` database. For every print job, the printer daemon prepares the data, gathers some additional information and calls the filter with a couple of parameters. Then apsfilter processes the input data stream according to the configuration settings and basically spews the printer data out (but there's lots of magic in between).

So the user doesn't actually get in touch with apsfilter, but rather tells the printer daemon via `lpr` (or sometimes via `lp`) that he wants to print something. To influence the visual appearance or printer dependent processing features, there must be a way to pass parameters to apsfilter: either via configuration files or on the command line.

Passing command line options depends on the spooler type which is installed on the system:

- BSD-type spoolers don't provide a direct interface for additional filter options, so the so-called "class" attribute for print jobs had to be misused for this purpose:

  >     lpr -C border:duplex:4pps somefile.txt

  This has lead to the term "class options", although it's not very accurate, since the class attribute is actually used for priority matters.
- LPRng is compatible to the BSD variants, so "-C" can be used as well; however, the use of the correct option "-Z" is preferred:

  >     foobar | lpr -Z noheader,enscript,letter

- LPRng also provides an interface called `lp` which resembles the SysV print tool; this one uses "-o" for options:

  >     lp -o recode -o ascii source.ps

Apsfilter options can be separated by ":" or ","; LPRng can also take more than one "-Z" or "-o" block (and will effectively concatenate them). See below for a listing of known command line options for apsfilter.

## 5.2 Special features

A couple of features that are not very common, but provide some comfort to the user, are available with apsfilter.

### 5.2.1 Fake duplex

If your printer is not able to handle duplex printing by itself (most inkjets can't do it), apsfilter can "fake" it for you. When you use the command line option "duplex", your file will be printed this way:

1. all necessary pre-processing, conversion etc. will be performed as usual
2. the even pages of the resulting PostScript code are extracted and printed (a blank page is inserted if needed)
3. apsfilter sends you an email which tells you to flip the sheets and put them back in
4. you also get some more-or-less secret key ("password") with the email which you should echo into an internal communication file (a "named pipe" for the experts) when the paper and the printer is ready
5. the odd pages are printed on the backsides of the even pages

The `DUPLEX_ODD_FIRST` variable can be set so that the odd pages are printed first. There are also two variables called `DUPLEX_REVERSE_EVEN` and `DUPLEX_REVERSE_ODD` which can be used to have those pages printed in reverse order. (Read the notes for details.)

Please note:

- fake duplex printing does not work if you directly print to a network printer server, since the named pipe must be on the same host as the user who started the print job; but you can set up your printer spooler so that all pre-processing is done on the local host and the resulting printer data is sent via the network
- after the even pages are printed, apsfilter waits for the password, thus effectively blocking the printer spooler; however, print jobs of other users should not be delayed longer than necessary, so please don't be nasty
- `sendmail` must be present for notification delivery (you can also create a wrapper script which translates the options for your mailer application)

Duplex printing (real or fake) can be disabled by setting the `DISABLE_DUPLEX` variable to a non-empty value.

### 5.2.2 Fast copies

Almost all printer spoolers offer the possibility to print multiple copies of a document without having to enter the print command multiple times. However, from apsfilter's point of view, there is no difference -- it simply gets the same request over and over again.

With the "copies=N" option you can print N copies of the same document, but much faster (or rather: much less CPU-intensive). Instead of performing all the pre-processing and rendering stages again for each request, apsfilter does the hard work once, then prints the resulting "raw" printer data N times. (This also works with the fake duplex mode.)

In case your printer already knows how to handle multiple copies, the driver can be adjusted in the driver script to use that feature. You should set `HARDWARE_COPIES` to a non-empty value to enable this behaviour.

If this conflicts with other services on your system (e.g. accounting), you can disable it by setting `MAXCOPIES=1` in one of the configuration files.

## 5.3 Printing to a file

Besides feeding data to the printer via the spooler, sometimes it might also be necessary or desired to direct apsfilter's output to a file.

This is not possible by directly calling apsfilter on the command line, since it makes some presumptions about its parameters and environment. But there is a script called `aps2file` which sets up the environment so that apsfilter thinks it's running under LPRng.

Enter `aps2file -h` on the command line to see what options are available. You'll mostly need "-P" to specify the printer queue and "-Z" for parameters. If you want to debug apsfilter, the "-D" option creates a log on stderr.

Using `aps2file` has the additional advantage to enable user supplied configuration files, since we don't have to care about security issues here.

Note: The output will always be directed to a file, even if you configured the queue to use the network.

## 5.4 Preview before printing

If you are of the paranoid kind, you might want to preview the output before it's sent to your printer. Now this is easily possible with apsfilter.

The script `apspreview` internally creates a PostScript file with the help of `aps2file` and sends it to your PostScript viewer program (`gv`, `kghostview` or `ghostview`). If you are satisfied with the result, you can simply print that file from the viewer (or even specific pages, if your application supports it).

To control the output, `apspreview` accepts basically the same options as `aps2file`; entering `apspreview -h` will give you a short overview.

Note: Command line options related to duplex printing (duplex, simplex, shortbind, longbind) should be used when actually printing the file -- they don't make sense for previewing. Also be careful if you convert the stuff with "multiple pages per sheet" as a default option -- while printing it must not be done again, so use the "1pps" option there.

# 6 Configuration

Configuring apsfilter can be done in two separate ways: either the administrator supplies specific values to configuration variables, or the user provides options to the `lpr` or `lp` program. Command line options usually have greater priority, unless some service has been disabled entirely (e.g. duplex printing).

## 6.1 Configuration files

The following configuration files are listed in the same order as they are used by apsfilter; these are all ordinary shell scripts.

A global configuration file resides in the global directory `/usr/pkg/etc/apsfilter/`, while a local file is located in the printer queue specific directory `/usr/pkg/etc/apsfilter/QUEUE/`.

1. `/usr/pkg/etc/apsfilter/apsfilterrc`
2. `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc` (mandatory)
3. `~/.apsfilter/apsfilterrc.QUEUE` (disabled by default due to security issues)
4. `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc.USER`
5. `/usr/pkg/etc/apsfilter/restrictions`
6. `/usr/pkg/etc/apsfilter/QUEUE/restrictions`
7. `/usr/pkg/etc/apsfilter/QUEUE/smbclient.conf`
8. `/usr/pkg/etc/apsfilter/QUEUE/netware.conf`
9. `/usr/pkg/etc/apsfilter/QUEUE/lpr.conf`
10. `/usr/pkg/etc/apsfilter/QUEUE/pap.conf`

### 6.1.1 `apsfilterrc` (global, local)

These two are the most important source of information for apsfilter, since they define the basic options.

Typical settings you want to change in the global file include:

`PATH` | shell search path; should be as restrictive as possible
`AWK` | properly working "awk" executable (e.g. GNU awk)
`NOTIFY` | user name of the person in charge for printer errors
`TMPDIR` | directory for temporary files; apsfilter actually creates a subdirectory of its own for better security
`USE_USER_CODE` | if set, enables the user specific file `$HOME/.apsfilter/apsfilterrc.QUEUE` as a configuration source DANGEROUS! -- you probably don't want to set it (it is unset by default)
`TEXINPUTS` | search path for dvips (PostScript pictures etc.)
`HAVE_MAKETEXPK` | if set, enables dvips to create fonts on the fly (this functionality is broken on more systems than you would imagine)
`DVIPS_RES_DorP` | dvips resolution switch; should be "-D" or "-P" (consult your dvips man page)
`GS_FONTPATH` `GS_LIB` | environment variables for `gs`, used to find fonts and support PostScript files (the ghostscript documentation has more information on this)
`IGNORE_LPD_RAW` | set this if your print jobs (most likely from remote machines) are sent in "raw" mode, causing them to be passed through apsfilter with no filtering whatsoever
`MAXCOPIES` | maximum numbers of copies created with apsfilter's internal copying mechanism
`ASCII_FILTER` | filter to convert text files to PostScript (one of "a2ps", "mpage", "enscript"), or to directly print text files with possible charset and end-of-line conversion ("recode")
`ASCII_HEADER` | set this if you want header lines in the formatted text output (no effect with "recode")
`ASCII_BORDER` | set this if you want borders in the formatted text output (no effect with "recode")
`PS_NUP` | multiple pages per sheet (must be one of 1, 2, 4, 8)
`ASCII_PPS` | the same, but just for text (no effect with "recode")
`LANDSCAPE` | set this if you want landscape orientation
`ASCII_LANDSCAPE` | the same, but just for text (no effect with "recode")
`PS_BOOK``` | if set: output pages in "book" format (i.e. 2pps, duplex, special printing order)
`PS_UTILS` | additional PostScript->PostScript filter

Unlike others, the local configuration file (which overrides any global options) is required by apsfilter and thus is created during `SETUP`. Initial values (which should not be deleted) are given for these variables:

`PRINTER` | specifies the driver (and for some drivers the printer model as well)
`PAPERSIZE` | the paper size used for practically every program that needs to handle PostScript code; currently possible values are "a4", "a3", "letter", "legal", "tabloid" and "ledger"
`METHOD` | either "auto" (automatic file conversion), "ascii" (treat everything as text) or "raw" (pass-through mode)
`QUALITY` | the printing quality (one of "draft", "low", "medium", "high", "photo"); the driver script will translate this into a decent resolution value
`COLOR` | control color or b/w printing, should be "color", "gray" or "mono" (may not work with all printer/driver combinations)
`RESOLUTION` | the printing resolution default (will most likely be overwritten by the `QUALITY` setting)

Parameters that are usually only valid for one printer should also go into the local file:

`MEDIA` | paper type; one of "plain" (normal paper; default), "coated" (inkjet quality), "glossy" (photo quality paper), "premium" (very high quality) and "trans" (transparencies)
`SWEEP` | whether printing should be unidirectional ("uni") or bidirectional ("bi")
`PRINT_DVI` | custom "DVI to printer language" filter (stdin->stdout); if empty, dvips (with possible rendering by ghostscript) will be used
`RAW_PROLOGUE` `RAW_EPILOGUE` | printf style escape sequences to be used before/after a "raw" print job
`RECODE_PROLOGUE` `RECODE_EPILOGUE` | printf style escape sequences to be used before/after text printed with recode
`BLANK_PAGE` | printer codes to be sent if a single blank page is needed (for "fake duplex" mode)
`GS_FEATURES` | basic features for ghostscript; this variable can be extended with command line options
`PS_INIT` | ghostscript initialisation file
`PS_EXIT` | ghostscript "cleanup" file
`POST_FILTER_OPTS` | basic features for the (optional) post-ghostscript filter `POST_FILTER` (which itself should only be set in the driver script)
`HARDWARE_COPIES` | set this if your printer and the driver can handle multiple copies by themselves (otherwise the copies will be sent manually)
`REMOTE_COPIES` | set this if multiple copies should be done at the remote printer server rather than locally (enabled by default; used by lpd and NetWare connections)
`HARDWARE_DUPLEX` | set this if your printer and the driver can handle duplex printing by themselves (otherwise it can be "faked")
`DISABLE_DUPLEX` | set this to completely forbid duplex printing; must be set on a network print server that operates printers which would need "fake" duplexing
`DUPLEX_REVERSE_EVEN` `DUPLEX_REVERSE_ODD` `DUPLEX_ODD_FIRST` | these control the page order for "fake duplex" printing; read the notes for details
`DUPLEX` | set this if you always want duplex prints
`BINDING` | which edge of the paper the binding should be (one of "short", "long")
`PAPERTRAY` | integer value to select the correct paper feed tray
`A2PS_BASIC` | basic features for a2ps
`A2PS_PAPERSIZE` | override the paper size for use with a2ps
`A2PS_OPTS` | override the complete a2ps command line
`MPAGE_BASIC` `MPAGE_PAPERSIZE` `MPAGE_OPTS` | the same for mpage
`ENSCRIPT_BASIC` `ENSCRIPT_PAPERSIZE` `ENSCRIPT_OPTS` | the same for enscript
`PRETTY_PRINTING` | highlight level used for pretty-printing (0=none, 1=normal, 2=heavy)
`RECODE_OPTS` | override the complete recode command line
`HTMLDOC_OPTS` | override the complete htmldoc command line
`HTML2PS_OPTS` | override the complete html2ps command line

The template `apsfilterrc` file is the definite source for these configuration possibilities, and shows the default value as well.

### 6.1.2 `apsfilterrc` (user specific)

These are two files that should be considered relics of the times when there were no command line options to apsfilter and printing to a file via a locally installed apsfilter was impossible.

The user can provide arbitrary settings in a file in his home directory, specifically `~/.apsfilter/apsfilterrc.QUEUE` for the printer named `QUEUE`. However, since apsfilter might run under a privileged account (e.g. daemon or even root), this is considered harmful (far worse than a `goto` statement) and needs to be activated by the administrator by explicitly setting `USE_USER_CODE`. You don't want to do that.

A secure, but less flexible way to have users supply their favourite options is the file `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc.USER` which is read when user `USER` prints on `QUEUE`. The downside is that the admin is supposed to change the file according to the user's wishes, which is probably not useful in practice. Do not let users edit their files -- this would open the same security hole as mentioned above.

However, if you use apsfilter via the `aps2file` or `apspreview` scripts, user-supplied configuration files are always used, since they can't do any harm to the system in this case (apsfilter will not run under a privileged account).

### 6.1.3 `restrictions` (global, local)

If the administrator wants to restrict certain options for all printer queues and/or for just a single queue, the global and local `restrictions` scripts will enable him to do that.

For example, if only a2ps and recode are installed, but mpage and enscript are missing, a simple line like

>     [ "$ASCII_FILTER" = recode ] || ASCII_FILTER=a2ps

will ensure text files are printed via a2ps, unless recode has been requested. This way users won't be annoyed by an error mail if they accidentally chose "mpage" or "enscript".

If you just want to set certain options if apsfilter is called via `aps2file`, you can test `APS2FILE_CONTEXT` for a non-empty value; e.g.

>     if [ "$APS2FILE_CONTEXT" ]; then
>         unset DUPLEX; COPIES=1
>     fi

Let's say your PostScript printer knows duplex, but fscks up the paper orientation -- it's tumbled where it shouldn't have been, and vice versa. The solution is to simply switch the `BINDING` values:

>     if [ "$BINDING" = short ]; then
>         BINDING=long
>     else
>         BINDING=short
>     fi

Here's an example which sets some attributes, e.g. for the stp driver: low-quality printing modes should use less ink.

>     case "$QUALITY" in
>         draft)  GS_FEATURES="$GS_FEATURES -dDensity=0.5" ;;
>         low)    GS_FEATURES="$GS_FEATURES -dDensity=0.8" ;;
>     esac

Or maybe you want to ensure the pages-per-sheet and paper orientation values are in sync for printing text files:

>     case "$ASCII_PPS" in
>         1|4)    unset ASCII_LANDSCAPE ;;
>         2|8)    ASCII_LANDSCAPE=set ;;
>     esac

### 6.1.4 `smbclient.conf` (local)

`SETUP` will create this file for you if you are using a remote printer on a Windows host via `smbclient`.

The variables in here are `SMB_SERVER`, `SMB_IP`, `SMB_PRINTER`, `SMB_WORKGROUP` and (optionally) `SMB_USER` and `SMB_PASSWD`. The values have the same meaning as shown in the `SETUP` dialog. Additional variables are `SMB_BUFFER` (default: 1400) and `SMB_FLAGS` (default: "-N").

If the file contains a user (other than guest) and password, it will be read protected, so only the account used for printing by `lpd` is granted access to it.

### 6.1.5 `netware.conf` (local)

`SETUP` will create this file for you if you are using a remote printer on a Novell NetWare printer server via `ncprint` or `nprint`.

The variables in this file are the same that `SETUP` allows you to change: `NCP_SERVER`, `NCP_PRINTER`, `NCP_USER` and `NCP_PASSWD`.

Similar to `smbclient.conf`, if you entered a password, read access to `netware.conf` will be limited.

### 6.1.6 `lpr.conf` (local)

If your printer spooler does not allow input filters for remote printer queues, you'll have to create this file manually. The only useful variable in there is `REMOTE_NAME`, which contains the remote queue name in the form `printername` (local queue), `printername@hostname` (queue on remote host) or `printername@hostname%port` (socket connection on remote host). Consult your spooler documentation about possible values.

This configuration file is not created by `SETUP`.

### 6.1.7 `pap.conf` (local)

For AppleTalk printers, this file provides apsfilter with the command line options for `pap`. It is created by `SETUP` and only contains the remote printer name in the `PAP_NBPNAME` variable.

## 6.2 Command line options

Specifying command line options to apsfilter is the easiest way to control the printout. The parameters are driver independent and case sensitive. Options are always valid for all files on the same command line; later options in the parameter list override previous values of the same kind.

Note that not all printer/driver combinations support all options -- the appropriate driver script in `/usr/pkg/share/apsfilter/driver/` will tell you more.

option | meaning | variable
--- | --- | ---
draft lo / low med / medium hi / high photo | draft quality low quality medium quality high quality photo quality | QUALITY
uni bi | uni-/bi-directional sweeps | SWEEP
plain coated glossy premium trans | plain paper coated (inkjet) paper glossy paper premium (photo) paper transparencies | MEDIA
color / colour gray / grey mono | color mode | COLOR
auto ascii raw | automatic data conversion forced text mode pass-through mode | METHOD
a3 / a4 / legal / letter / ledger / tabloid | paper size | PAPERSIZE
a2ps / mpage / enscript / recode | text file filter | ASCII_FILTER
tray0 ... tray9 | paper feed tray number | PAPERTRAY
pretty=N | highlight level for pretty-printing (N=0,1,2) | PRETTY_PRINTING
header / noheader | whether you want headers with your text prints | ASCII_HEADER
border / noborder | whether you want borders with your text prints | ASCII_BORDER
1pps / 2pps / 4pps / 8pps | pages per sheet | PS_NUP, ASCII_PPS
landscape / portrait | paper orientation | LANDSCAPE, ASCII_LANDSCAPE
book | output pages in "book" format implies "2pps,duplex,shortbind" | PS_BOOK, PS_NUP, ASCII_PPS, DUPLEX, BINDING
duplex / simplex | whether to use duplex mode | DUPLEX
shortbind / longbind | paper binding edge | BINDING
copies=N | number of copies | COPIES

## 6.3 Configuration notes

### 6.3.1 Landscape and N-up printing

Since some combinations of apsfilter options are not too intuitive, let me share some thoughts on combining "landscape" page orientation with "n-up" printing (i.e. multiple pages per sheet).

Usually, you get one of the following layouts:

    .-------.                 .-------.  .-------.
    |       |                 |   |   |  |   |   |
    |       |  .-----------.  | 1 | 2 |  | 1 | 3 |  .-----------.  .-----------.
    |       |  |     |     |  |   |   |  |   |   |  |1 |2 |3 |4 |  |1 |3 |5 |7 |
    |   1   |  |  1  |  2  |  |---+---|  |---+---|  |--+--+--+--|  |--+--+--+--|
    |       |  |     |     |  |   |   |  |   |   |  | 5| 6| 7| 8|  | 2| 4| 6| 8|
    |       |  `-----------´  | 3 | 4 |  | 2 | 4 |  `-----------´  `-----------´
    |       |                 |   |   |  |   |   |
    `-------´                 `-------´  `-------´

So n-up printing always means "scale the pages with the correct x:y ratio and distribute them on the sheet"; but it assumes the pages to be in portrait mode in any case, since the psutils (here: `psnup`) can't know about the "logical" page orientation.

If you additionally use "landscape" mode, there might be some strange results, according to the converter's rotation direction, but we try to ensure that all tools cooperate with `psnup` w.r.t rotation.

Fortunately, with most (even moderately sophisticated) text-to-PostScript filters (e.g. a2ps, mpage and enscript), you'll get decent results most of the time, since these are able to rotate and scale the pages in one go.

### 6.3.2 Page order in fake duplex mode

If you are a lazy user, you might want to reduce the effort of page shuffling, flipping and re-ordering which is required when printing in fake duplex mode.

To keep the "reverse" operation(s) of psselect to a minimum, here are some hints as to use the correct set of options, adjusted to the various paper feeding mechanisms:

- top loader (e.g. Epson Stylus series):

  >     DUPLEX_ODD_FIRST=set

- front loader, output face down (e.g. HP LaserJet series):

  >     DUPLEX_REVERSE_EVEN=set

- front loader, output face up (e.g. HP DeskJet series):

  >     DUPLEX_REVERSE_ODD=set

If you happen to use the `PS_UTILS` variable to reverse the page order for simplex printing, you might want to ensure that these settings don't influence each other. In this case, you don't enter those values in the `apsfilterrc` file, but rather add a block to the `restrictions` file for that printer:

>     if [ "$DUPLEX" ]; then
>         # your settings as described above, e.g.
>         DUPLEX_REVERSE_EVEN=set
>     else
>         PS_UTILS='psselect -r'
>     fi

Note: Please make sure that the setting of `BLANK_PAGE` (default: `'\012\014'`, i.e. one LF followed by one FF) does indeed create an empty page, otherwise documents with an odd number of pages might not be printed as expected.

# 7 FAQ

This section covers the most frequently asked questions, or what we think should be questions frequently asked if they were asked at all :)

If you dare to ask one of this questions on the mailing-lists, you will be laughed at!

## 7.1 Error messages

Q: "can't find apsfilter basedir"
A: The SETUP (besides other things) creates a link `/usr/pkg/etc/apsfilter/basedir` that points to the actual directory where apsfilter was installed. This link has been either mangled or deleted entirely. Try to run SETUP again.

Q: "can't find configuration"
A: The only configuration file that positively has to be found for each `QUEUE` is `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc`, because this file defines the most important variables (driver and printer model, paper size, printing method). SETUP should have created that file... strange.

Q: "unsupported file type 'foobar'"
A: The `file` command has identified your input file, but apsfilter doesn't know how to print it. If you know a converter for this type of file which works on the command line (preferably to PostScript or PNM, but others might work as well), please contact us at <apsfilter-hackers@apsfilter.org>.

This could also be caused by a wrong guess by file(1) -- the input data might match a "magic number" by accident. In this case you can use the "ascii" option (if the file contains only text), or you must convert it yourself.

Q: "missing 'foo'; can't convert file type 'bar'"
A: In this case apsfilter knows the file type, but is unable to locate any filter which may be used for further processing. This might be solved by adjusting the `PATH` setting in the global `apsfilterrc`, but most likely you don't have a converter for that type installed. For several file formats there's more than one possible filter (not just the one that is called "missing"; in most cases, it's the "last resort").

Q: "invalid method 'foobar'"
A: This is another "can't happen" error, because the only chance to get this error message is when some person fiddled with the printer queue specific `apsfilterrc` file -- and it surely wasn't you, was it? Anyway, the `METHOD` setting must be one of "auto" (this is probably what you want), "ascii" or "raw".

Q: "can't determine the lpd spool directory"
A: This error may have two different reasons:

1. You want to print directly to a remote printer queue, but your spooler can't handle it. In this case you either can install LPRng or you need a bounce queue.
2. You are using a BSD style spooler, but have removed the "accounting file" specification in `/etc/printcap` (the ":af=..." line). Even if you don't want accounting, you must leave that line in there, because that's the only chance for apsfilter to get hold of the spool directory location (which is also the directory the accounting file is in).

Q: "error creating directory for temporary files"
A: The temporary file directory `TMPDIR` used by apsfilter can be set in `apsfilterrc`; the default is `/tmp`. The permission bits of this directory should be 1777 (rwxrwxrwt), so that apsfilter can create its own subdirectory which will be used for temporary files.

Another reason for this error is a denial-of-service effect which occurs if the name `apsfilter$$` (where $$ is the process ID) is already used in `TMPDIR` and the mktemp program cannot be found. If you install mktemp, you most likely won't ever see this error message again.

Note: In this case, apsfilter exits with a non-fatal error code. Depending on your printer spooler type, lpd might want to retry to print the file, since the error condition is not persistent (e.g. the next run will have a different $$ value).

Q: "driver script 'foo' for 'bar' not found"
A: The driver you selected for your printer (bar) was supposed to be configured by the shell script `/usr/pkg/share/apsfilter/driver/foo`, but this script wasn't found. This shouldn't have happened!

Q: "driver script 'foo' not yet available"
A: Similar to the message above, this warning says that no script has yet been written for your particular driver. If you are willing to create one (it's not too difficult), have a look at `/usr/pkg/share/apsfilter/driver/README`. In case the driver doesn't support options other than its defaults, you can just create an empty file (`touch /usr/pkg/share/apsfilter/driver/foo`); this way, you won't get annoyed by this message anymore.

Q: "missing 'foo'; can't unpack file type 'bar'"
A: The file you wanted to print was compressed, but the decompressing tool was not found in the `PATH`. Install it, or adjust the `PATH` setting in the global `apsfilterrc` configuration file.

Q: "apsfilter warning: html2ps needs gs for DSC compliance"
A: When converting HTML files to PostScript, the html2ps converter relies on ghostscript to create DSC compliant PostScript documents; this is needed for any further processing via the psutils (n-up printing, duplex etc.). The gs executable was not found in the `PATH`; however, since it might be okay to create non-DSC documents, apsfilter just prints a warning to the log/status file.

Note: Since html2ps can have its own `PATH` setting in the configuration file `html2psrc`, this warning may even be unnecessary.

Q: "apsfilter warning: duplex fifo couldn't be created"
A: For fake duplex printing to work, apsfilter needs to set up a named pipe (a.k.a. fifo) which enables the user to send the release-key to apsfilter. This pipe/fifo is created with the `mkfifo` command, which failed in this case -- apsfilter then prints the file in simplex mode.

## 7.2 Printing failures

Q: I just have set up the printers, but the names are not recognized by my spooler software!
A: Are you sure you have restarted the printer daemon? As SETUP alters the central configuration file `/etc/printcap`, the spooler must be told to use the new version. The setup instructions tell you what to do.

Q: The spooler takes the input file, but there's nothing coming out of the printer.
A: Are you sure you're talking to the correct printer? If your `/etc/printcap` already contained a printer called lp, it's likely that you tried to use that printer queue. Some lpd packages "feature" a sample lp entry in `/etc/printcap` which is suitable for a generic, mostly text-only printer. Try using the "-P my_printer" command line option to lpr (for the lp interface it's "-d my_printer"). If that works, either set the environment variable `PRINTER=my_printer` or change `/etc/printcap` manually, so that lp is an alias for the correct queue.

However, this could also be a processing error, maybe even a syntax error in the filter script. Please have a look at the help chapter to find out how to enable debugging. If the debug output is not helpful to you, please send us a bug report.

Q: I want to print to a remote printer, but my spooler doesn't allow input filters for remote printers in `/etc/printcap`.
A: This might be solved by using a so-called "bounce queue". You must edit `/etc/printcap` to change the `:lp=` entry for the printer to be `:lp=/dev/null:`; then you create a simple text file called `lpr.conf` in the appropriate configuration directory, e.g. `/usr/pkg/etc/apsfilter/QUEUE/`, that consists just of one line:

>     REMOTE_NAME=remoteprinter@remotehost.somedomain

If the printer is on the same host, you can leave out the trailing @remotehost.somedomain part. Remember to restart the daemon in any case.

Q: Why doesn't apsfilter find the conversion programs? I know that they are installed!
A: By default apsfilter uses a restricted `PATH` for security reasons. You can alter the `PATH` in `/usr/pkg/etc/apsfilter/apsfilterrc` (global) or in the printer specific `apsfilterrc`.

Q: Why is the resolution for dvips wrong?
A: For whatever reason, there are different dvips version out there which use either "-D" or "-P" as the command line switch to set the resolution. Consult your dvips manpage and set `DVIPS_RES_DorP` in the main configuration file.

Q: I get "permission denied" errors for some file `cf...`!
A: That's a classic FAQ :) Far too many lpd installations suffer from wrong permissions or non-matching user/group ID settings which prevent apsfilter from reading that control file. All I can say is: LPRng doesn't have that problem.

Q: I want to print something, but I only see some weird PostScript code!
A: There are a couple of reasons for this (too common) error:

- You used an option for `lpr` or `apsfilter` which causes the data to be printed in "raw" (i.e. unfiltered) mode. This can be the result of a `METHOD=raw` setting in one of the config files, the "-l" or "-b" switch to `lpr` or the `raw` command line option to apsfilter.

  The latter case happens with gimp in connection with PostScript output on a non-PostScript printer (maybe via an apsfilter queue). The default options include "raw"; remove that in the "Setup" dialog. (Please bear in mind that printing like this is only useful if your printer is not supported by gimp-print, since the plug-in is able to handle the options much better than apsfilter, and it avoids PostScript as an intermediate format.)

  Another reason could be remote clients for a printer server that send the print jobs in "raw" mode. If the spooler on the client can't be configured to disable that behaviour, you can include a line `IGNORE_LPD_RAW=set` into the appropriate `apsfilterrc` file. If you still want to print files in "raw" mode with this queue, you can use the `raw` command line option to apsfilter -- this one won't be ignored.

- The input file might be PostScript code, but it is not recognized as such. In this case, it is taken as normal text. Check the file's first line to be at least `%!` or `%!PS` -- this should convince your `file` command to correctly report the file type.

  Some files in the ghostscript distribution need this kind of help.

- The printer type for this particular queue might be set to `PS` or `PSgs`, although you don't have a PostScript printer. Check the configuration file `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc`.

Q: My USB-connected Epson Stylus printer won't work with {Free,Net,Open}BSD! [from the gimp-print FAQ]
A: By default, the BSD device driver for the USB printer device (usually `ulpt0`) does a prime, or USB bus reset, when the device is opened. This causes the printer to reset itself (one can hear the print head moving back and forth when this happens) and lose sync. After this the printer won't go into graphics mode and instead spews characters all over your expensive photo paper. This has been observed on the Stylus Photo 870; it likely exists with other USB-connected Epson Stylus printers.

The fix is to use the `unlpt0` device instead of `ulpt0`. The driver doesn't perform the USB prime when `unlpt0` is opened. If this device doesn't exist on your system you can create it with

>     mknod unlpt0 c 113 64 root wheel

in the `/dev` directory.

Q: For some files I want to print, there are error messages regarding "DSC" showing up in the log. What's that?
A: DSC (Document Structuring Conventions) is the format specification for PostScript data files. These error messages probably say that the application which produces the PostScript data is buggy. You may be able to fix that by saving the PostScript data to a file first, then using the "fixps" tool (or some variant) to get it working.

Q: Why can't I print DVI/HTML/Sketch/FIG files with embedded images etc.?
A: That depends on the file format and the way the images are embedded. For inline images, i.e. images that are literally included in the file, there shouldn't be any problems. If the image is referenced by a filename, it must not only be found but it must also be accessible.

Relative pathnames are very hard for the filter to expand, since it would have to know a directory (or a set of directories) to search in. Absolute pathnames are more pleasant, but you still have to make sure that the referenced file is readable by anyone and every directory down the path is executable by anyone.

The easiest way to print the file correctly might be to use `aps2file` inside the correct "document root" directory, so that all relative paths are actually referring to the right files, and then pipe the output through a "raw" queue. For example:

>     $ cd /usr/pkg/share/doc/apsfilter
>     $ aps2file handbook.html | lpr -Zraw

This should print the apsfilter handbook with a nice little logo :^)

Q: How to persuade apsfilter to attach EOT to PS jobs not to leave LED blinking on a PS printer?
A: Use the printcap capability "tr". That string is sent after each job. Add ":tr=\004:" to your printers entry in /etc/printcap. This has been reported to work with a LJ 1200.

## 7.3 Tuning

Q: My printer needs special treatment to reset it before any print job, set the codepage, enable the correct end-of-line mode, add an extra formfeed afterwards etc.
A: Grab your printer documentation to look for the escape sequences needed and enter these into the configuration variables `RAW_PROLOGUE` and `RAW_EPILOGUE` (remember to use octal values). To send a reset sequence of "ESC c" before and an additional formfeed after the raw print job, use

>     RAW_PROLOGUE='\033c'
>     RAW_EPILOGUE='\014'

You can also set command line options for recode in the variable `RECODE_OPTS` if you want fast text listings; a simple conversion from the latin1 charset with UNIX-style `LF` line endings to codepage 437 with `CR+LF` line endings would be enabled by

>     RECODE_OPTS='latin1..cp437/crlf'

The `RECODE_PROLOGUE` and `RECODE_EPILOGUE` variables are used in addition to the `RAW_...` stuff whenever recode does text conversion.

Q: I have a PostScript Level 1 printer. How can I tell apsfilter to produce correct output?
A: You must use the special `PSgs` driver which uses the "pswrite", "psgray" and "psmono" ghostscript devices. Then add "-dLanguageLevel=1" to the `GS_FEATURES` variable for that printer.

Q: How do I prevent users from using command line options? My printer shall always use the same settings.
A: There are two different approaches to this problem:

1. The file `/usr/pkg/etc/apsfilter/QUEUE/restrictions` can be used to reset options to their default, e.g.

   >     QUALITY=medium
   >     MEDIA=plain
   >     COLOR=full
   >     PAPERSIZE=a4
   >     unset DUPLEX

2. Instead of using your normal driver, you can create a custom driver script. First you have to install the correct driver for your printer, e.g. pcl3/hpdj690c. Then you change the `PRINTER=pcl3/hpdj690c` line in `/usr/pkg/etc/apsfilter/QUEUE/apsfilterrc` to `PRINTER=custom` (or some other unused name). The last step is to create a new driver script named `/usr/pkg/share/apsfilter/driver/custom` which includes all your variables like `GS_FEATURES` and `RESOLUTION` and their desired values, plus a line `PRINTER=pcl3/hpdj690c` to ensure the original driver name is used properly.

Q: Printing program listings etc. is dog slow.
A: If you use a2ps (the default), mpage or enscript to print text files, these are converted to PostScript first. For plain text printings you can use recode as the filter (either set `ASCII_FILTER=recode` or use the "recode" command line option). However, you lose all the spiffy features like borders, headers, multiple pages per sheet and fake duplex mode.

Q: I want to print the source code of some PostScript, HTML, Sketch, ... file, but all I get is the formatted output.
A: You have to tell apsfilter not to automagically convert the file, but rather treat is as normal text; use the "ascii" command line option.

Q: The page margins are not correct. / The printout is shifted in one direction.
A: Although this is not actually an apsfilter problem, here are some hints:

- a2ps, mpage and enscript have options for the command line and/or in the configuration files that enable you to set the correct page margins; see the appropriate documentation for details
- ghostscript drivers may have a mechanism to adjust page margins; e.g. the uniprint profiles usually contain a line like

  >     -dupMargins="{9.0 39.96 9.0 9.0}"

  which define the left, bottom, right and top margins in points (1pt = 1/72in); other drivers may have different options, if they support this at all
- you can use the ghostscript test file `align.ps` to measure the page drift and margins in points; then create a world-readable file (e.g. `/usr/pkg/etc/apsfilter/QUEUE/margin.ps`) that looks similar to this:

  >     %!
  >     % Example: Epson Stylus Color 640
  >     << /.HWMargins [-8.504 9.921 0 0] /Margins [-42.52 -2.835] >> setpagedevice

  and set `PS_INIT=/usr/pkg/etc/apsfilter/QUEUE/margin.ps`; if you already have a `PS_INIT` file, just add the correct line to it.

  Note: You may need to use the command

  >     { echo '%!' ; cat /path/to/align.ps ; } | lpr

  to print the test file correctly. Please remember that `align.ps` resets those values to zero, so you won't see any change if you print it again with a `PS_INIT` file like the one above.

Q: Why are parts of the page missing on my PostScript printer?
A: Pages in higher resolutions or with complex content need plenty of RAM to be rendered. For some printers the standard amount of memory which is built in just isn't enough. You can either put more RAM into your printer or reduce the rendering resolution (to probably half the amount). Using the special `PSgs` driver might help as well.

Q: When I print more than one file at a time, the headers for text files are wrong; they still show the name of the first file!
A: This ever-annoying problem only occurs with BSD spoolers which just don't give enough information about a print job to the filter. The solution is to install LPRng, or print just one file at a time, or disable headers completely.

Q: Why is my DVI file messed up? It should be in landscape mode, but the right border is chopped off!
A: The problem is that dvips doesn't know if the file is in landscape mode or not. You have to explicitly use the "landscape" command line option.

# 8 Links

The first and most important link is of course the Apsfilter Homepage at http://www.apsfilter.org/. This is the definite source of information about apsfilter, most prominently the download section.

To keep up with the latest apsfilter changes, you can use the anonymous CVS server as described on the support page or browse the repository.

## 8.1 Third party software

Here's an alphabetical list of software packages known to and supported by apsfilter:

a2ps
  http://www.inf.enst.fr/~demaille/a2ps/
acroread
  http://www.adobe.com/products/acrobat/readermain.html
ar (part of binutils)
  http://sourceware.cygnus.com/binutils/
bzip2
  http://www.muraroa.demon.co.uk/
cabextract
  http://www.kyz.uklinux.net/cabextract.php3
convert (part of ImageMagick)
  http://www.imagemagick.org/
cpio
  http://www.gnu.org/software/cpio/
dvips (part of teTeX)
  http://www.tug.org/teTeX/
enscript
  http://www.ngs.fi/mtr/genscript/index.html
Epson printer drivers
  http://www.epkowa.co.jp/english/linux_e/pips_e.html ("pips")
  http://www.epkowa.co.jp/english/linux_e/lpd_e.html (laser printers)
fig2dev (part of transfig)
  http://www.xfig.org/
file
  ftp://ftp.astron.com/pub/file/
freeze
  ftp://ftp.std.com/src/util/freeze2.5/
ghostscript
  http://www.cs.wisc.edu/~ghost/ (homepage)
  http://ghostscript.sourceforge.net/ (project page)
  http://www.ghostscript.com/ (commercial site)
gimp-print (a.k.a. stp)
  http://gimp-print.sourceforge.net/
groff
  http://www.gnu.org/software/groff/
gzip
  http://www.gnu.org/software/gzip/gzip.html
HP inkjet drivers (official)
  http://hpinkjet.sourceforge.net/
hpdj
  http://home.t-online.de/home/Martin.Lottermoser/pcl3dist/
html2ps
  http://www.tdb.uu.se/~jan/html2ps.html
htmldoc
  http://www.easysw.com/htmldoc/
IBM Omni drivers
  http://oss.software.ibm.com/developer/opensource/linux/projects/omni/
lha
  http://www2m.meshnet.or.jp/~dolphin/lha/lha-unix.htm
lpd (BSD-style)
  http://sourceforge.net/projects/lpr/
LPRng
  http://www.lprng.com/
lzop
  http://wildsau.idv.uni-linz.ac.at/mfx/lzop.html
mktemp
  http://www.courtesan.com/mktemp/
mpage
  http://www.mesa.nl/pub/mpage/
nconvert (part of XnView)
  http://www.xnview.com/
ncprint (part of ncplib)
  http://rbp.chat.ru/ncplen.html
netpbm tools (a.k.a. pbmplus)
  http://sourceforge.net/projects/netpbm/
nprint (part of ncpfs)
  ftp://ftp.platan.vc.cvut.cz/pub/linux/ncpfs/
pap (part of netatalk)
  http://www.umich.edu/~rsug/netatalk/
pcdtoppm (part of xpcd)
  http://bytesex.org/xpcd.html
pcl3
  http://home.t-online.de/home/Martin.Lottermoser/pcl3.html
pdftops (part of xpdf)
  http://www.foolabs.com/xpdf/
pnm2ppa
  http://sourceforge.net/projects/pnm2ppa/
psutils
  http://www.dcs.ed.ac.uk/home/ajcd/psutils/
rar, unrar
  http://www.rarsoft.com/
recode
  http://www.iro.umontreal.ca/contrib/recode/HTML/
rpm
  http://www.rpm.org/
sendmail
  http://www.sendmail.org/
sk2ps (part of sketch)
  http://sketch.sourceforge.net/
smbclient (part of samba)
  http://www.samba.org/
tar
  http://www.gnu.org/software/tar/tar.html
tgif
  http://bourbon.cs.umd.edu:8001/tgif/
wmf2eps (part of libwmf)
  http://www.wvware.com/libwmf.html
unarj
  http://testcase.newmail.ru/
unzip
  http://www.info-zip.org/UnZip.html

Other driver packages that can be made to work with apsfilter include:

turboprint
  http://www.turboprint.de/
xw-tools
  http://xwtools.automatix.de/

## 8.2 Further information

A good overview of printers, drivers and printing systems can be found on http://www.linuxprinting.org/. Don't be misled by the name, most of the information is valid on any UNIX-like system.

The Linux Printing HOWTO at http://www.linuxprinting.org/howto/ is a must read for all Linux administrators (and probably others as well) -- preferably before you try to set up your printer. Users might also profit from the Linux Printing Usage HOWTO at http://www.linuxdoc.org/HOWTO/Printing-Usage-HOWTO.html.

Even if you don't want to use LPRng (which is hard to believe), the LPRng-HOWTO at http://www.lprng.com/LPRng-HOWTO.html is a rich source of everything related to printer daemons, protocols, filters and stuff.

# 9 Help

## 9.1 You help us

That's not what you wanted to read, is it? Anyway, we are in a constant need of bug reports, new ideas, suggestions -- but also "real value" support in form of hardware or software donations, job offerings or just pure hard ca$h.

The easiest way to contribute to apsfilter is probably to improve the driver scripts, especially the one(s) for your printer(s). Have a look at `/usr/pkg/share/apsfilter/driver/README` for more information. If your preferred driver does not have a script yet, you'd really help us if you'd try to write and test one -- it isn't too difficult. Maybe the driver is already mapped to some other script (with basically the same settings) via `/usr/pkg/share/apsfilter/driver/MAPPING`, but you can simply create an appropriately named script; this will override the `MAPPING` entry.

## 9.2 We help you

The first step to solve any apsfilter problems is to make sure it actually is not some kind of other defect on your system (hardware, spooler software, cables, ...). If you are absolutely sure that your problem is not already covered in the FAQ or in other parts of this documentation, read on.

There's also a mailing-lists archive which you can browse and search. Maybe your problem has already been solved, or even classified as a feature ;)

### 9.2.1 Reporting bugs

To prepare a bug report, it's absolutely necessary to create a log of the failed printing attempt (unless you have problems that occur before even having a chance to print). You can (and should) use the `aps2file` tool with the "-D" option. It is a good idea to use the same printer queue and command line options as before when the printing attempt failed. You can pass the options to apsfilter via `aps2file` by using the "-P" and "-Z" switches.

The log will be created on stderr, so you might want to redirect it to a file by appending `2>log.txt`. You can see a detailed trace of what apsfilter tried to do; if that doesn't help you, just save the file for inclusion into the bug report. If you can, please use bash as your shell, since the log will be much more verbose.

Since many bug reports we received were not exactly helpful, we now supply a script that generates a half-automatic bug report which you just have to fill out. Call `apsfilter-bug` on the command line and your favourite editor should present you the template text.

The first thing you should edit is the `From:` field; please enter your correct e-mail address there. Do not change the `To:` field line, unless you positively know better.

Then just read the comments and fill in any information requested there. All lines starting with a `#` character are comments and will be removed automatically before the bug report is sent.

When you're done, save the text under its original name and exit the editor. Exiting without saving will cause the bug report to be discarded.

We hope that we can help you!

### 9.2.2 General help

If you need general help with apsfilter (i.e. if it's not even possible to produce a bug report), there are some more mailing-lists available:

- <apsfilter-help@apsfilter.org>: general help forum
- <apsfilter-hilfe@apsfilter.org>: general help forum in German (try to avoid this if possible)
- <apsfilter-hackers@apsfilter.org>: technical discussion, code submissions, ideas and suggestions
- <apsfilter-printing@apsfilter.org>: tips and tricks, problems and solutions
- <apsfilter-doc@apsfilter.org>: everything concerning documentation
- <apsfilter-chat@apsfilter.org>: everything which doesn't fit to the other lists

There are also two read-only public mailing-lists:

- <apsfilter-announce@apsfilter.org>: release announcements
- <apsfilter-cvs@apsfilter.org>: commit messages for CVS repository

The lists are controlled by majordomo; to get more information, send an email to <majordomo@apsfilter.org> with the body `help`.

To subscribe to a mailing-list, send an email to <majordomo@apsfilter.org> with the body `subscribe apsfilter-xyz`.

To unsubscribe, send an email to <majordomo@apsfilter.org> with the body `unsubscribe apsfilter-xyz`.

You have reached the official end of the apsfilter handbook.
It is now safe to switch off your computer.