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.5 and compatible.

1.2 About this document

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 (and maybe others as well) might 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/local/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/local/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/local/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:

all necessary pre-processing, conversion etc. will be performed as usual
the even pages of the resulting PostScript code are extracted and printed (a blank page is inserted if needed)
apsfilter sends you an email which tells you to flip the sheets and put them back in
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
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/local/etc/apsfilter/, while a local file is located in the printer queue specific directory /usr/local/etc/apsfilter/QUEUE/.

/usr/local/etc/apsfilter/apsfilterrc
/usr/local/etc/apsfilter/QUEUE/apsfilterrc (mandatory)
~/.apsfilter/apsfilterrc.QUEUE (disabled by default due to security issues)
/usr/local/etc/apsfilter/QUEUE/apsfilterrc.USER
/usr/local/etc/apsfilter/restrictions
/usr/local/etc/apsfilter/QUEUE/restrictions
/usr/local/etc/apsfilter/QUEUE/smbclient.conf
/usr/local/etc/apsfilter/QUEUE/netware.conf
/usr/local/etc/apsfilter/QUEUE/lpr.conf
/usr/local/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/local/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/local/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/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>.

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:

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.
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/local/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/local/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/local/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/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: 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/local/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/local/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:

The file /usr/local/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
```
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/local/etc/apsfilter/QUEUE/apsfilterrc to PRINTER=custom (or some other unused name). The last step is to create a new driver script named /usr/local/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/local/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/local/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/local/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/local/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.