Apsfilter -STABLE Documentation

# The Apsfilter Documentation Document

Please note: This is about apsfilter-STABLE, the (stable) release version of apsfilter developement. Most of this documentation is still in an early state. 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>.

## Overview

- Preface: Why should I read this?
- Introduction: What do I need to know about apsfilter?
- Installation: Which software do I need to use apsfilter? How do I install it?
- Setup: How are printers set up? What must be done to trick apsfilter into using my printer?
- Usage: How does apsfilter integrate into the printing system? How do I call it?
- Configuration: Which options are available at runtime? How can I influence the printout?
- FAQ: What the FAQ is going on here? Surely nobody else had my problem, right?
- Links: Were do I find all the additional software? Is there supplemental information/documentation available?
- Help: What can I do if nothing works? Where should I send my bug reports or suggestions?
- ToDo: Which missing feature is already on the way? What has been marked as "not too soon"?

## Preface

This document tries to inform you about all relevant aspects of apsfilter. Not many people like to read documentation, even fewer are actually willing to write it (trust me!). At least you were wise enough to have a quick look before doing any damage to your system, I hope.

FIXME: use fixed file locations in examples and explain them here or use path "variables"?

## Introduction

Apsfilter (which means "Andreas' PostScript Filter" or "Another PostScript Filter" or even "Apsolute Filter" :) -- pick one you like) 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 6.1.1 which was released in March 2001. There are also development snapshots and a CVS repository available. Point your web browser to the Apsfilter Homepage at 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.

## Installation

### Preparation

Before installing apsfilter, please make sure your system meets some basic requirements:

- the 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 the "next generation" spooler called LPRng (which is also compatible to the BSD version)
- you need a shell interpreter that is able to handle at least the basic POSIX features, installed as `/bin/sh` if possible;
  working shells include bash, zsh and ksh; problems can arise with older SysV shells
- 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
- 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, transfig, groff, html2ps, Acrobat Reader (acroread), pdftops, sk2ps
- compressed files can be processed as well: gzip, bzip2, compress, freeze and pack are known
- to correctly report error messages and notifications, apsfilter relies on `sendmail` being installed and working on your system

Your printer should basically work (i.e. it accepts data which has been sent directly to the interface) -- apsfilter can't fix hardware problems. 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.) has more information on this topic.

FIXME: add *BSD information sources

Special note for users of older FreeBSD systems (and maybe others as well): to use the advanced features of apsfilter, the BSD-lpr program (not the LPRng version) needs the following patch:

    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 version of lpr.)

### 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.

Otherwise, login as the administrator (most probably root) and extract the apsfilter tarball in an appropriate directory (a common location is `/usr/local/share`).

            $ su - root
            Password:
            # cd /usr/local/share
    either  # gzip -cd /path/to/apsfilter-X.Y.Z.tar.gz | tar xf -
                    (if you downloaded the gzip'ped version)
    or      # bzip2 -cd /path/to/apsfilter-X.Y.Z.tar.bz2 | tar xf -
                    (if you downloaded the bzip'ped version)
            # cd apsfilter

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

If your `/bin/sh` shell is not capable of the POSIX features that apsfilter relies on, you'll have to change the path in the first lines of `bin/apsfilter` and `SETUP` to point to a "real" shell. Your system administrator should be able to help you.

Note: The `Makefile` in the apsfilter directory is only used by the FreeBSD ports collection. Other systems will most likely get an error message like `*** missing separator`. But you have already tried that, haven't you? :^)

Note: The installation procedure is bound to be changed in the near future.

## Setup

Setting up the printers is done via the `SETUP` script in the apsfilter installation directory (in our example this would be `/usr/local/share/apsfilter`). If you are paranoid, it is probably safer to make sure the lpd daemon is not running while you set up your printers.

            # /usr/local/share/apsfilter/SETUP

The SETUP program more or less guides you through the whole process; just answer the questions to your best knowledge:

The configuration directory will be used to store global and printer specific configuration files (some in their own subdirectory). It's probably a good idea to enter the path to a directory which will be used exclusively by apsfilter (like in the examples shown on the same screen).

Some installations of lpd tend to have problems with the correct spool dir owner/group/permission settings; this might affect special apsfilter features. In case you use LPRng, you can call the checkpc program which is able to reset all relevant settings to sane defaults that are guaranteed to work. (SETUP does this for each printer after installation.)

With SETUP, you can either overwrite the previous printer entries in `/etc/printcap` that are used by apsfilter or just add one or more printers. In any case, a backup copy will be stored as `/etc/printcap.old`.

Just to make sure you are using the correct ghostscript executable, you can take a look at the devices that are supported by your `gs` (use `<d>` in the main menu). Many of these will probably be devices that actually produce bitmap images, so they are not very useful with printers.

Choosing the right printer driver is important for smooth operation of apsfilter:

- PostScript printers can be used either directly or with the help of the ghostscript drivers "pswrite" (for color output) and "psgray" (for grayscale output); if your printer is only capable of printing PostScript Level 1 data, or if you want to use fonts that the printer doesn't know (but ghostscript does), you'll probably need the special `PSgs_*` drivers
- the ghostscript releases are bundled with many printer drivers (although not all of them are compiled in by default); SETUP calls these "native" drivers
- there are several external drivers to ghostscript available (e.g. gimp-print/stp, the IBM Omni collection or the pcl3 driver mostly used for HP printers); these come with their own installation instructions and most likely provide a patch to ghostscript
- the pnm2ppa conversion tool allows you to operate a couple of HP DeskJet printers that use a closed-source communication protocol called "Printing Performance Architecture" (PPA)

Several printers can be used with more than one driver; you can choose one after another, print the test page and compare the visual quality and even the time needed before actually installing the printer.

If you have a printer which is not supported by any of the drivers, you might want to try a driver that knows similar compatible devices; some fine-tuning may be necessary. However, if you already have a driver for your printer which just doesn't show up in any of the lists, you'll have to install some other driver and change the appropriate configuration file by hand later.

The printer interface decides how to physically connect to the printer. For home installations, this will most probably be a parallel or USB connection (serial printers are becoming rare, but can be used as well). For networks, you can use UNIX-style connections via the lpd on the printer server, samba for printing to Windows servers or AppleTalk for Macs.

The paper size setting is the default for any further printing attempts, but it's possible to adjust it on the command line later on. You must set this.

Some printer drivers don't support any other resolution than their default value; please consult the appropriate documentation.

If you think your settings are correct, you can install the printer (with `<i>`); you will then be asked if you want to install a "raw" printer queue. This provides you with the possibility to directly print the data without any changes or filtering (you can also enable this on the command line with each print job, so you probably only need the "raw" printer if the command line is not always available, e.g. if you get print requests from over the network). You definitely don't need more than one "raw" entry per physical printer.

The printer queue name is the name that you will use to specify a printer other than the default. Use short and simple names that clearly let the users distinguish between the printers; using just letters and numbers is preferred.

Each printer will get its own spool directory (hopefully with the correct permissions set) and configuration subdirectory which will contain all necessary information that apsfilter needs to properly control the printer.

After that you are returned to the main menu so that you can install more printers or finish the setup.

To complete the setup, you'll have to signal the printer spooler that there's a new `printcap` file to be used:

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

Note: The setup procedure is bound to be changed in the near future.

## Usage

### Normal operation

If you try to call the apsfilter script directly, you will get an error message by email and/or on the console -- why doesn't that ?$#!@ thing work?

Well, that's just not the way printer filters are used. Apsfilter 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 (which were missing when you tried to call apsfilter directly).

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` that he wants to print something. However, apsfilter provides some extensions to the plain printing procedure that enables the user to influence the visual appearance of the printout etc.

The way apsfilter gets these additional information depends on the type of spooler 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" (or the equivalent "-o") is preferred:

      	foobar | lpr -Z noheader,enscript -o 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).

To find out which options apsfilter understands, have a look at the configuration section (because these options are actually temporary on-the-fly configuration changes).

### Special features

Apsfilter is able to extend the normal printer spooler operation with non-standard features that provide some comfort to the user.

#### Fake duplex printing

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 (the number of even pages is always less or equal to the number of odd pages; this way, all sheets will be re-used)
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

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

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

#### Fast multiple 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. 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.)

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.

## 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).

### Configuration files

Apsfilter uses a bunch of configuration files:

- `/usr/local/etc/apsfilter/apsfilterrc`: global configuration, all printers are affected
- `/usr/local/etc/apsfilter/QUEUE/apsfilterrc`: only printer named QUEUE is affected; this file is mandatory
- `/usr/local/etc/apsfilter/QUEUE/apsfilterrc.USER`: only if user named USER prints on QUEUE, this file is used as well
- `~USER/.apsfilter/apsfilterrc.QUEUE`: the same as the previous one, but may be disabled due to security concerns

All of these files are ordinary shell scripts. Since the printer daemon (and as a result also apsfilter) may run with high privileges, the user supplied configuration normally is not used. As usual with shell scripts, any environment variable can be changed, any program can be called -- so the apsfilter effective user id (which may even be root) can cause quite some damage.

The following variables directly affect apsfilter; although decent default values for most of these are provided, you should review them anyway.

variable | meaning
--- | ---
PATH | shell search path; should be as restrictive as possible
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 `~USER/.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.)
PRINT_DVI | custom "DVI to printer language" filter (stdin->stdout); if empty, dvips (with possible rendering by ghostscript) will be used
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)
RAW_PROLOGUE RAW_EPILOGUE | printf style escape sequences to be used before/after a "raw" print job
GS_FEATURES | basic features for ghostscript; this variable can be extended with command line options
GS_RESOL | rendering resolution for ghostscript
PS_INIT | ghostscript initialisation file
PS_EXIT | ghostscript "cleanup" file
PPA_OPTS | basic features for pnm2ppa; this variable can be extended with command line options
COLOR | control color or b/w printing, should be "color", "colour" or "mono" (may not work with all printer/driver combinations)
HARDWARE_DUPLEX | set this if your printer and the driver can handle duplex printing by themselves (otherwise it can be "faked") Note: the "pswrite" driver does not preserve the duplex sequences
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 | 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
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")
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
RECODE_OPTS | override the complete recode command line
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 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")
HTML2PS_OPTS | override the complete html2ps command line
PS_BOOK | output pages in "book" format
PS_UTILS | additional PostScript->PostScript filter
the following options are created by SETUP
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
METHOD | either "auto" (automatic file conversion), "ascii" (treat everything as text) or "raw" (pass-through mode)
RESOLUTION | the printing resolution; can be overridden for ghostscript by `GS_RESOL`

The template apsfilterrc file is the definite source for these configuration possibilities, and shows the default value as well. There are more variables that can affect apsfilter's behaviour; see the next section.

### Command line options

First of all, all command line options are case insensitive. So here are the options that work independently of the driver, plus the configuration variable that they affect.

option | meaning | variable
--- | --- | ---
ascii / auto / raw | printing method | METHOD
a3 / a4 / legal / letter / ledger | paper size | PAPERSIZE
color / colour / mono | control color or b/w printing | COLOR
a2ps / mpage / enscript / recode | set the text file filter | ASCII_FILTER
tray0 ... tray9 | paper feed tray number | PAPERTRAY
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 | 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

The following command line options are driver specific; different drivers for the same printer model may or may not support them.

#### stcolor

option | meaning | variable
--- | --- | ---
low / medium / high | printing resolution of 180 / 360 / 720dpi | GS_RESOL
uni | use unidirectional output | GS_FEATURES
microweave / noweave / softweave | weaving mode | GS_FEATURES
gscmyk / gsmono / gsrgb / fsmono / fsrgb / fsx4 / fscmyk / hscmyk / fs2 | dithering algorithm | GS_FEATURES
1bpp / 3bpp / 8bpp / 16bpp / 24bpp / 30bpp / 32bpp | color depth | GS_FEATURES
flag0 | use "-dFlag0" | GS_FEATURES
plain / runlength / deltarow | compression algorithm | GS_FEATURES

#### cdj500, pjtest, declj250

option | meaning | variable
--- | --- | ---
low / medium / high | printing resolution of 150 / 300 / 600dpi | GS_RESOL
plain / bond / special / glossy / transparency | paper type | GS_FEATURES
draft / normal / presentation | output quality | GS_FEATURES
1bpp / 3bpp / 8bpp / 16bpp / 24bpp | color depth | GS_FEATURES

#### cdj550

option | meaning | variable
--- | --- | ---
32bpp | color depth | GS_FEATURES

This driver also knows the cdj500 options.

#### cdj880

option | meaning | variable
--- | --- | ---
30bpp | color depth | GS_FEATURES

This driver also knows the cdj550 options.

#### cdj670, cdj850, cdj890, cdj1600, cdj970

option | meaning | variable
--- | --- | ---
reton / retoff | whether to use C-RET (FIXME: C-RET = color correction?) | GS_FEATURES

These drivers also know the cdj880 options.

#### pjxl300, pjxltest

option | meaning | variable
--- | --- | ---
low / medium / high | printing resolution of 150 / 300 / 600dpi | GS_RESOL
plain / bond / special / glossy / transparency | paper type | GS_FEATURES
draft / normal / presentation | output quality | GS_FEATURES
render0 ... render10 | rendering type | GS_FEATURES
1bpp / 3bpp / 8bpp / 16bpp / 24bpp / 32bpp | color depth | GS_FEATURES

#### bjc600, bjc800

option | meaning | variable
--- | --- | ---
low / medium / high | printing resolution of 150 / 300 / 600dpi | GS_RESOL
low / draft / normal / presentation | printing quality | GS_FEATURES
plain / coated / transparency / envelope / card / other | media type | GS_FEATURES
1bpp / 4bpp / 8bpp / 16bpp / 24bpp / 32bpp | color depth | GS_FEATURES

#### hpdj, pcl3

option | meaning | variable
--- | --- | ---
low / medium / high | printing resolution of 150 / 300 / 600dpi | GS_RESOL
500 / 500c / 510 / 520 / 540 / 550c / 560c / 850c / 855c / unspec | printer model | PRINTER
mono / cmy / cmyk / cmy+k | color mode | COLOR, GS_FEATURES
draft / normal / presentation | printing quality | GS_FEATURES
plain / bond / premium / glossy / transparency / photo | media type | GS_FEATURES

#### pnm2ppa

option | meaning | variable
--- | --- | ---
uni / bi | unidirectional/bidirectional printing | PPA_OPTS
eco | economy mode | PPA_OPTS
noblack | do not use the black ink cartridge | PPA_OPTS

If your printer/driver does not have any options defined yet, or if you want more/different options for a specific driver, please don't hesitate to contact us at <apsfilter-hackers@apsfilter.org>.

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

### Apsfilter error messages

Q: "can't find apsfilter basedir"
A: The SETUP (besides other things) creates a link `/usr/local/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/local/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>.

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").

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" (see below).
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: "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 to 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.

### Printing errors

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 `printcap` which is suitable for a generic, mostly text-only printer. Try using the "-P my_printer_name" command line option to lpr (for the lp interface it's "-d my_printer_name"). If that works, either set the environment variable `PRINTER=my_printer_name` 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 section 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/local/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/local/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: 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 must 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 convert it to PostScript manually (maybe the application has an export option, otherwise have a look at the apsfilter script to get a hint what to do) and then print it the usual way.

### 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 "LF -> CR+LF" conversion using the latin1 charset would be enabled by

    	RECODE_OPTS='l1..l1/crlf'

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

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 apsfilter test page or the ghostscript test file `align.ps` to measure the page drift in points, then add

      	-dMargins="{X Y}"

  to the apsfilter configuration variable `GS_FEATURES` (where X and Y are the horizontal and vertical difference)

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_*` devices 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 explicitely use the "landscape" command line option.

Q: My printer/driver can only produce grayscale output. So it doesn't matter what value `COLOR` has, right?
A: Wrong. For example, a2ps uses colors to render headers, do pretty-printing etc. These colors look different on a grayscale printer than the gray levels used when `COLOR=mono` is set. Additionally, some converters use special algorithms when they are told to produce grayscale output; this might improve the result. They usually run faster in this mode, as well.

## Links

The first and most important link is of course The Apsfilter Homepage. This is the definite source of information about apsfilter, most importantly the download section.

To keep up with the latest apsfilter changes, you can use the CVS server as decribed here or browse the repository.

### Software packages

If you experience problems with the plain BSD spooler, you might want to check out LPRng which has many more features, is more secure and flexible and less buggy.

It's a good idea to keep up with latest releases of ghostscript, be it the free GNU version version or the commercial one.

External drivers for ghostscript are available:

- the GIMP project was the starting point for the high quality gimp-print driver (a.k.a. stp) which is distributed along with the gimp-print plugin
- the older hpdj driver is being replaced by the new pcl3 driver, so you should try that one
- IBM released their collection of the Omni printer drivers which are dynamically loaded when ghostscript is used

The following packages are not supported directly by apsfilter, but they can be used with the help of bounce queues which are tricked into thinking there's a PostScript printer, but are redirected to the real printer queue.

- the turboprint driver collection is said to offer high quality output; it will be distributed commercially in the nearest future
- xw-tools is a commercial package as well, but you can test a demo version

If you are unlucky to own a PPA printer by Hewlett-Packard, you must install the pnm2ppa conversion tool.

If you want to print bitmap images directly, you must install one of the packages that provide the right filters: ImageMagick, XnView or the netpbm tools. These differ in the number of supported file formats, however.

For easy manipulation of PostScript files, the psutils package will provide you with the necessary tools.

Text-to-Postscript converters are available here: a2ps, mpage, enscript. For fast text output and charset conversion, you can use recode.

Here's a list of other known conversion tools:

- dvips
- transfig is a companion to xfig
- groff
- html2ps
- Acrobat Reader (acroread) from Adobe
- pdftops is part of xpdf
- sk2ps is part of sketch

### Further information

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

The Linux Printing 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.

## Help

### 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. So check out this to get there :^)

### 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, power lines, ...). 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 ;)

#### Reporting bugs

To prepare a bug report, it's absolutely necessary to create a log of the failed printing attempt. Note: LPRng users should enable the `filter_stderr_to_status_file` option in `/etc/lpd.conf`, otherwise the log will be very hard to read.

First edit the `/usr/local/share/apsfilter/bin/apsfilter` script and search for occurences of "[DEBUG]":

- right after the header there's a line with "`#set -x`" -- change that to "`set -x`"
- at the end of the script there are three lines that contain commented code; just remove the `#` signs before `trap`, `print_data()` and `print_ps()` (although the latter change might actually mask out the error location in the script; you might need to comment that line again)

(Remember to change everything back later on, otherwise the printer will continue to produce debugging output.)

After that, print the file again (try to take the same steps as before when the print attempt failed). Then there should be a log of the last apsfilter session in the `log` or `status` file which resides in the spool directory of the printer queue you used (usually `/var/spool/lpd/QUEUE/`).

The log shows 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.

Please follow these instructions to create a bug report that will actually be meaningful to everyone who tries to help you (did I mention that we don't get any money for that?).

A decent bug report contains:

- full name and valid email address
- your operating system plus version (if applicable: distribution plus version)
- the apsfilter version plus any patches that you applied
- the printer spooler type (BSD, LPRng) plus version
- ghostscript version (if used)
- your printer model and the driver you used
- if you suspect a hardware problem: the interface settings
- any strange messages on the console/xconsole and in the system log files
- the apsfilter log of exactly one failed print session (please include this as an attachment, not inline; compression would be nice)
- the `/etc/printcap` entry which caused the trouble (in case of a "bounce queue": both entries)
- the file type of the file in question (uncompressed)
- any changes to the configuration file which may cause the failure

You might wonder if that is really necessary, but since there are so many factors that might be the cause of the problem, a bug report like this will be the fastest way to find the error.

Now that you have assembled all the information -- where to send it? It is basically a very bad idea to send it directly to one of the maintainers (not even with CC). The people who can actually help you read the mailing-lists that have been established for just this purpose:

- <apsfilter-stable@apsfilter.org>: bug reports for stable releases
- <apsfilter-current@apsfilter.org>: bug reports for development releases

We hope that we can help you!

#### 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 subject help.

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

## ToDo

Several ideas have already been collected, but nobody has started to implement them -- either because it would require too much work, or the demand is just too low, or there's an ongoing discussion.

- secure printing with a setuid-root wrapper that changes its UID to the user who started the print job, then calls apsfilter
- watermark backgrounds that can be created dynamically
- apsfilter burn-in test to check which file formats can be converted/printed (this requires a simple fake spooler which repeatedly calls apsfilter with the correct parameters and different input files)
- apsfilter-aware printer management tools (GUI and/or command line)

More ideas should be sent to <apsfilter-hackers@apsfilter.org>.

Apsfilter Prints So Fine, It Leads To Extraordinary Results

This document is © 2001 Michael Loßin <phallobst@web.de>
distribution of this file is permitted under the regulations of the GPL