![]()
|
Michael Loßin Table of Contents1 Preface 2 Introduction
1 Preface1.1 AbstractThis 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 documentYou are looking at the second edition of the apsfilter handbook. It was written by Michael Loßin <phallobst@web.de> (© 2001,2002) and has been published under the regulations of the GPL. It is available as indexed HTML, PostScript, PDF (with links) and plain text. These editions are generated from a source HTML file by htmldoc and w3m. The colorful apsfilter logo was created by Chris Cox <cjcox@acm.org>. If you feel something important is missing, if you find blatant typos or obsolete information, please contact the mailing-list at <apsfilter-doc@apsfilter.org>. 1.3 ConventionsThroughout this document we'll use the following typographical conventions:
2 Introduction2.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?
So you see: apsfilter is the best sliced bread since... uhm... no, wait... 2.4 Why shouldn't I use it?
2.5 Is it for me?Yes, it is. Maybe. 3 Installation3.1 PreparationSince 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.
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 procedureIf 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 notesHere'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 LinuxSuSE 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 FreeBSDUsers 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 SolarisUsing 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 SetupIf 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 PreparationIn the first couple of screens, various information is gathered in order to adapt SETUP to your system environment. 4.1.1 LicenseThe 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 directoryThe 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 entriesBefore 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 menuThe 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 driversAny 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 documentationIn 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 selectionThis 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 ghostscriptHere 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 hpdjAs 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 OmniThis 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 driversA collection of drivers for a number of HP printers. 4.2.3.9 PPA printerPPA 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 printerSome programmers (not at Lexmark, of course) have created drivers for Lexmark inkjets. 4.2.3.13 miscellaneous other driversThose drivers which don't really fit into the other categories are assembled in this list. 4.2.3.14 non-printer devicesCaution! 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 InterfaceThe 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 connectionYou only need to enter the full path to the device node -- that's it. 4.2.4.2 Serial connectionBesides 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 printerThe 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 / SambaYour 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 AppleTalkThis connection only requires the name of the printer as provided by the Apple server. 4.2.4.6 Novell NetWareContact 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 formatThe 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 qualityThis 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 modeSelecting 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 ResolutionThe 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 methodFor 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 pageTo 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 logAfter 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 AbortIn 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 InstallationIf 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 setupAfter 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:
4.3 Tips and tricksThere'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: This setting won't be used for all other drivers (although it is harmless in those cases).PS_INIT='stcolor.ps' 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 Usage5.1 Normal operationAs 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:
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 featuresA couple of features that are not very common, but provide some comfort to the user, are available with apsfilter. 5.2.1 Fake duplexIf 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:
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:
Duplex printing (real or fake) can be disabled by setting the DISABLE_DUPLEX variable to a non-empty value. 5.2.2 Fast copiesAlmost 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 fileBesides 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 printingIf 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 ConfigurationConfiguring 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 filesThe 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/.
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:
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:
Parameters that are usually only valid for one printer should also go into the local file:
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 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".[ "$ASCII_FILTER" = recode ] || ASCII_FILTER=a2ps 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 optionsSpecifying 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.
6.3 Configuration notes6.3.1 Landscape and N-up printingSince 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 modeIf 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:
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 FAQThis 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"
Q: "can't find configuration"
Q: "unsupported file type 'foobar'" 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'"
Q: "invalid method 'foobar'"
Q: "can't determine the lpd spool directory"
Q: "error creating directory 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"
Q: "driver script 'foo' not yet available"
Q: "missing 'foo'; can't unpack file type 'bar'"
Q: "apsfilter warning: html2ps needs gs for DSC
compliance" 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" 7.2 Printing failures
Q: I just have set up the printers, but the names are not
recognized by my spooler software!
Q: The spooler takes the input file, but there's nothing
coming out of the printer. 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. 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.REMOTE_NAME=remoteprinter@remotehost.somedomain
Q: Why doesn't apsfilter find the conversion programs? I
know that they are installed!
Q: Why is the resolution for dvips wrong?
Q: I get "permission denied" errors for some
file cf...!
Q: I want to print something, but I only see some weird
PostScript code!
Q: My USB-connected Epson Stylus printer won't work with
{Free,Net,Open}BSD! [from the gimp-print FAQ] 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 in the /dev directory.mknod unlpt0 c 113 64 root wheel
Q: For some files I want to print, there are error
messages regarding "DSC" showing up in the log. What's that?
Q: Why can't I print DVI/HTML/Sketch/FIG files with
embedded images etc.? 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: This should print the apsfilter handbook with a nice little logo :^)$ cd /usr/local/share/doc/apsfilter $ aps2file handbook.html | lpr -Zraw
Q: How to persuade apsfilter to attach EOT to PS
jobs not to leave LED blinking on a PS printer? 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. 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?
Q: How do I prevent users from using command line options?
My printer shall always use the same settings.
Q: Printing program listings etc. is dog slow.
Q: I want to print the source code of some PostScript,
HTML, Sketch, ... file, but all I get is the formatted output.
Q: The page margins are not correct. / The printout is
shifted in one direction.
Q: Why are parts of the page missing on my PostScript
printer?
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!
Q: Why is my DVI file messed up? It should be in landscape
mode, but the right border is chopped off! 8 LinksThe 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 softwareHere's an alphabetical list of software packages known to and supported by apsfilter:
Other driver packages that can be made to work with apsfilter include:
8.2 Further informationA 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 Help9.1 You help usThat'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 youThe 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 bugsTo 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 helpIf 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:
There are also two read-only public mailing-lists:
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. |