ez-magic printer filter v1.0.5 - By Toby Reed <toby@eskimo.com>
(c)1997 Toby Reed for PorkNET Internet Systems (http://www.porknet.ml.org/)

ez-magic is free software. Once free, now free, always free.
You are given full manipulation rights to this program as long as these
conditions are followed:
	1) Do not redistribute modified versions of this program without
	   my consent.
	2) You may put these files on a CD-ROM, so long as the single
	   CD-ROM you are selling it on costs less than $50. Other media
	   (floppies, tapes, etc) cannot exceed more than $50 over the
	   cost of the media.
	3) Corperations and commerical entities may freely use this
	   program, but it is requested that they notify me by e-mail.
	4) All original documentation and files must be included in ANY
	   redistribution of this software. You may print out
	   documentation, but only in full.

1. INTRODUCTION

  ez-magic was created with the idea that printing under linux should be
much simpler than it currently is. Not to make it so simple it's
impossible to use, but to make it easy to print something quickly,
independant of it's file format. My configuration consists of an HP
Deskjet 870Cse inkjet printer connected to a Windows for Workgroups
machine on my local ethernet. I wanted to print color graphics and
postscript and text and everything else, but I had three problems:

	1) I didn't have any drivers for graphics
	2) I didn't have a way to print to a WFWG machine
	3) It was very complex and time consuming to print just one simple
	   file.

  I solved number 2 with SAMBA, a linux package that lets you use Windows
and Lan Manager server's files and printers. ez-magic assumes you have
this package installed if you wish to use the network printing feature.

  With a little research I found filters like aps, ps-printcap, and
magicfilter. They worked, but not the way I wanted them to. So I examined
their source code and found out how they were writing to the printer.
After tinkering with Ghostscript and some others tools I solved the
drivers problem. Now I set off to write my own filter.

  ez-magic started off as the 'print' command. To use it, you typed "print
file.{ps,txt,gif}. It would automagically convert the file and print it to
the printer with smbclient. Finally, I added more formats and features and
I ran into a problem. Programs like netscape and xv wanted to pipe their
output into a program. So I wrote up a quick fix and called it prcat or
"printer cat". It worked terrific, but yet another problem sprung up.
Another set of programs wanted to print to an lpd printer. I had
previously bypassed lpd and printcap completely and done just fine. So I
poked around and finally made a printcap entry that would work with prcat.
Unfortunately, I don't care enough to make it interpret the complex lpd
option set.

  I heard some people complaining about the lack of a good printer filter
in the linux newsgroups, so I decided to package this up for my fellow
linux users to try. I rewrote 'print' and 'prcat' into one script, called
'magic'. I found a lot of bugs in doing so and worked around them. That's
basically it. On to the installation.

2. INSTALLATION

    * If you want local printing capability:
  You should have the following things set up and working:
  - Linux
  - You should be able to type "echo booger > /dev/lp1" and get it to
    print out. It might be /dev/lp0 or /dev/lp2. Figure it out.

    * If you want network printing capability:
  You should have the following things set up and working:
  - Linux
  - Recent SAMBA version, you should be able to connect to the printer
    like this:
    # smbclient \\\\PSERV\\HP4LJ -P
    smb: \> print filename.txt
    and get SOMETHING out of your printer.

    * If you want to print stuff at all:
  You should have the following things set up and working:
  - Ghostscript (recent version helps)
  - Todos for unix <-> dos text conversion. If you have a printer that
    doesn't have the 'staircase effect' problem, you don't need this, but
    you will have to change some things in the script or you'll get errors
    and won't be able to print text.
  - Netpbm graphics package. This is a must if you want to print any of
    the graphics formats (gif,jpg,bmp,png,pcx,tif)
  - The Libjpeg "DJPEG" demo utility. You need this to print JPEG/JFIF
    files.
  - Image Alchemy v1.8 or so. To print PNG format files.

  Now grab your favorite text editor and edit the "magic" script. The
first section is just pathnames. Find out where you installed the packages
listed (you might try the "locate" command), and put the pathnames here.
JUST THE PATH. Not the filename of the program. For /usr/local/bin/alchemy,
just put "/usr/local/bin". Read the Ghostscript documentation and find out
what printer driver you use and the DPI it supports. If the DPI is
anything but 300 change the "300" in the GSOPTS line to the DPI. And
change the GSDEV to your printer device.

NEAT TRICK ALERT - NEAT TRICK ALERT!
Danger Will Robinson! You can replace GSDEV with "x11" and have it show
the file on your X-Windows display! Pretty cool, but pretty worthless,
too, seeing as how XV will do just as good for reading most of these
formats.

Back to the topic at hand....

  The "Printing Options" section is mainly for experienced users.
Disabling PRCAT means that the program will never ask for printer input
from standard input or a pipe. Running "magic" alone will normally tell
you to press CTRL-C to abort, or CTRL-D when you are finished typing. By
disabling PRCAT, you just get an error message instead, and STDIN input is
no longer supported. Disabling messages turns off all the messages that
ez-magic generates. Like "Printing Postscript ..." or the PRCAT message.
Disabling error messages turns off the "file not found" messages.
Disabling the PRCAT messages turns off the "CTRL-C for abort, CTRL-D when
finished" message for programs that don't like it.

  If you are using a local printer, pay attention to this section.
Remember what /dev/lp device you were using and put it in the
"LOCALPRINTER" variable. If you want a special print command other than
"cat > /dev/lp1", put it in the SPECIAL_PRINT_COMMAND variable.

  Network people, talk to your network administrator and get the SMB print
server sharename. This is usually something like "\\EAR\WAX". First make
sure that "ENABLE_NETWORK" is "y". Remember SAMBA? Remember where you
installed it? You'd better. When you find it, stick the path in the
"SMBCLIENT" variable. If your adminstrator told you "\\EAR\WAX", then for
the PRINTSERV variable, put "EAR", and for the PRINTSHARE variable, put
"WAX". If you require a special username for access, put that in NUSER,
otherwise put something fake in. NPASSWORD isn't supported yet because I'm
too lazy to password protect my printer and try it. So you'll have to hack
it in yourself. If you need any other special SMBCLIENT options, stick 'em
in SMBOPTS.

  If you are low on printer paper, you might want to make a script called
"fakeprint" that says "cat > /tmp/ptmp" and make it mode 666 and put
"/path/fakeprint" in the DEBUG_PRINT_COMMAND variable. Now, whatever you
print will end up in /tmp/ptmp in your printer's language. This is good
for debugging only.

  You shouldn't have to touch anything below the "No user-servicable parts
below this line" line. If you're a scripter like me then go for it. Just
remember the legal terms at the top of this file.

  Now save the file and copy it to /usr/local/bin or something. cd to that
directory and type:
  ln -s magic prcat
This should create a symlink (newbies: it looks like a normal file) called
"prcat". When you invoke it as "prcat", ez-magic will know and act
accordingly. The reason you need this is because lpr passes some weird
command line arguments to it and screws things up so if it's invoked as
prcat it ignores these arguments and, well, acts as "prcat".

  If you want printcap capability, add these lines to your /etc/printcap
file:
lp|hp:hpdj:\
        :cm=HP DeskJet 870Cse Printer:\
        :lp=/dev/null:\
        :sd=/var/spool/lpd:\
        :af=/var/spool/lpd/acct:\
        :sh:\
        :mx#0:\
        :if=/usr/local/bin/prcat:

  Make sure that the "if=" line points to the correct directory that has
the "prcat" symlink to the "magic" program. And don't call your printer
"hp" and "hpdj" unless it really is. "cm=" is just a comment, so change
that to something creative.

  Even if you are using local printer, keep "lp=/dev/null" because prcat
takes care of the actual printing for you.

TIP: Type "lpq" to see the print queue, but that's pretty pointless
because it's sent to prcat and the job is ended right away.

3. CONFIGURING YOUR SOFTWARE

  If a program asks for the "LPR Printer Name", put in "lp" or "hp" or
whatever you called it back in the last chapter. It will invoke lpr which
will invoke prcat which will invoke magic which will invoke the conversion
programs and then print it with smbclient or to the local printer.

  If a program asks for a print command, you can usually use "magic". If
it wants to pipe it into something (a lot of programs do this), you can
usually use "magic", but it's safer to use "prcat" in case it passes any
arguments.

  That's it. Everything should work now. If it doesn't, tough. I'm way too
lazy to help you. At least I was nice enough to write and release this.

4. EXTRA JUNK

  Try printing the example files included in test.zip if you can't find a
file in a certain format.

  Adding file formats is fairly easy. Just find something, a signature,
that is consistant through a large batch of unique files in that format,
for GIF it's "GIF" in the first 3 letters. Some formats aren't as easy,
some are. Then use the head and tail commands to get it to display that
signature and make an 'if' command based on the ones in the script already
and create a function and follow the format of the others. Pretty easy
really.

  Type "magic -s" or "magic -sig" to get a list of file extentions, the
signatures that ez-magic looks for in them, and what programs are
required to print them.

  "magic -h" or "magic --help" shows a help screen.

  I need to find someone who will make a good troff manual page for
ez-magic, based on the documentation.

Enjoy!

-Toby Reed
<toby@eskimo.com>
