The Apsfilter Documentation Document

• 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"?

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"?

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.

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";

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.

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)

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.

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

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.

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

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

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

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

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.

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.

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)

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

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

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.

• 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)

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