<!doctype linuxdoc system>
<!--  TODO
	- graphics printing
	- fonts
	- mpage
  -->

<!--	The Linux Printing Usage HOWTO
	v1.1 (c) 1995 Matt Foster
        v1.11-1.2.2 (c) 1996-1998 Mark Komarinski
	Last revised 6-FEB-1998
  -->

<article>
<title>The Linux Printing Usage HOWTO</title>
<author>by Mark Komarinski &lt;markk@auratek.com&gt;</author>
<date>v1.2.2, 6 February 1998

<sect>Introduction
<p>
<nidx>HOWTOs!printing usage</nidx>
<nidx>printing!user-level introduction</nidx>
This document describes how to use the line printer spooling system provided
with the Linux operating system.  This HOWTO is the supplementary document
to the Linux Printing Setup HOWTO, which discusses the installation and
setup of the Linux printing system.  The material presented in this HOWTO
should be equally relevent for all flavors of the BSD operating system in
addition to the Linux operating system.

<sect1>Linux Printing HOWTO History
<p>
Note from Mark Komarinski &lt;markk@auratek.com&gt;:<p>
I'd like to thank Matt Foster for doing a lot of work in the re-write
of this HOWTO.  I'm keeping his style, and adding when necessary to keep
everything updated.
<p>
Note from Matt Foster &lt;mwf@engr.uark.edu&gt;:<p>
This version of the Linux Printing HOWTO is a complete rewrite of the one
originally written by Grant Taylor &lt;grant@god.tufts.edu&gt; and Brian
McCauley &lt;B.A.McCauley@bham.ac.uk&gt;.  I have tried to keep with the
coverage of material presented by Grant and Brian's HOWTO, but I have
drastically modified the style of presentation and the depth of material
covered.  I feel that this makes the HOWTO more complete and easier to
read.  I can only hope that you agree.

<sect1>Version History
<p>
v1.2.2
  <itemize>
    <item>Re-indexed, other changes to fit in the new RedHat docs.  Thanks Ed!
  </itemize>
v1.2.1
  <itemize>
    <item>updates, some changes for Dr. Linux publication
  </itemize> 
v1.2
  <itemize>
    <item>Windows Printers
    <item>Changing max size of print files
  </itemize>
v1.11
  <itemize>
    <item>new maintainter!
    <item>Added lpc info
    <item>Added some info for troubleshooting
    <item>A start on printing graphics files!
  </itemize>

v1.1
  <itemize>
    <item>revised some of the wording
    <item>developed section on PostScript printing
    <item>attempted to clarify some of the examples 8-)
    <item>fleshed the discussion of the basic Linux printing utilities
  </itemize>

v1.0
  <itemize>
    <item>initial public release of the Printing Usage HOWTO
  </itemize>

<sect1>Copyrights and Trademarks
<p>
Some names mentioned in this HOWTO are claimed as copyrights and/or
trademarks of certain persons and/or companies.  These names appear
in full or initial caps in this HOWTO.
<p>
<em>(c) 1995 Matt Foster (mwf@engr.uark.edu)</em><newline>
<em>(c) 1996-1997 Mark F. Komarinski (markk@auratek.com)</em>
<p>
All translations, derivative works, or aggregate works incorporating
any Linux HOWTO documents must be covered under this copyright notice.

That is, you may not produce a derivative work from a HOWTO and impose
additional restrictions on its distribution. Exceptions to these rules
may be granted under certain conditions; please contact the Linux HOWTO
coordinator at the address given below.
<p>
In short, we wish to promote dissemination of this information through as
many channels as possible. However, we do wish to retain copyright on the
HOWTO documents, and would like to be notified of any plans to redistribute
the HOWTOs.

<p>
If you have questions, please contact Tim Bynum, the Linux HOWTO
coordinator, at &lt;linux-howto@sunsite.unc.edu&gt;. You may finger this address
for phone number and additional contact information.


<sect1>Downloading the Linux Printing HOWTOs
<p>
<nidx>printing!downloading HOWTOs</nidx>
I recommend that if you want to print a copy of this HOWTO that you
download the PostScript version.  It is formatted in a fashion that is
aesthetically appealing and easier to read.  You can get the PostScript
version from one of the many Linux distribution sites (such as SunSITE
<url url="ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/">).

<sect1>Feedback
<p>
Questions, comments, or corrections for this HOWTO may be directed to
&lt;markk@auratek.com&gt;.

<sect1>Acknowledgments
<p>
Thanks go out to all of the people who took the time to read the alpha
version of this HOWTO and respond with many helpful comments and
suggestions---some of you may see your comments reflected in the version.
<p>
I'd also like to thank Matt Foster who did the original re-write.

<sect>Printing Under Linux
<p>
This section discusses how to print files, examine the print queue, remove
jobs from the print queue, format files before printing them, and configure
your printing environment.

<sect1>History of Linux Printing
<p>
<nidx>printing!history of</nidx>
The Linux printing system---the <em>lp</em> system---is a port of the source
code written by the Regents of the University of California for the Berkeley
Software Distribution version of the UNIX operating system.

<sect1>Printing a File Using <em>lpr</em>
<p>
<nidx>printing!using lpr command</nidx>
<nidx>lpr command!usage example</nidx>
By far, the most simplistic way to print in the Linux operating system is
to send the file to be printed directly to the printing device.  One way
to do this is to use the <em>cat</em> command.  As the <tt>root</tt> user,
one could do something like

<tscreen><verb>
# cat thesis.txt > /dev/lp
</verb></tscreen>

In this case, <tt>/dev/lp</tt> is a symbolic link to the actual printing
device---be it a dot-matrix, laser printer, typesetter, or plotter.  (See
<em>ln</em>(1) for more information on symbolic links.)
<p>
For the purpose of security, only the <tt>root</tt> user and users in the
same group as the print daemon are able to write directly to the printer.
This is why commands such as <em>lpr</em>, <em>lprm</em>, and <em>lpq</em>
have to be used to access the printer.
<p>
Because of this, users have to use <em>lpr</em> to print a file.  The
<em>lpr</em> command takes care of all the initial work needed to print
the file, and then it hands control over to another program, <em>lpd</em>,
the line printing daemon.  The line printing daemon then tells the printer
how to print the file.
<p>
When <em>lpr</em> is executed, it first copies the specified file to a
certain directory (the spool directory) where the file remains until
<em>lpd</em> prints it.  Once <em>lpd</em> is told that there is a file to
print, it will spawn a copy of itself (what we programmers call forking). 
This copy will print our file while the original copy waits for more
requests.  This allows for multiple jobs to be queued at once.
<p>
The syntax of <em>lpr</em>(1) is a very familiar one,

<tscreen><verb>
$ lpr [ options ] [ filename ... ]
</verb></tscreen>

If <tt>filename</tt> is not specified, <em>lpr</em> expects input to come
from standard input (usually the keyboard, or another program's output). 
This enables the user to redirect a command's output to the print spooler. 
As such,

<tscreen><verb>
$ cat thesis.txt | lpr
</verb></tscreen>

or,

<tscreen><verb>
$ pr -l60 thesis.txt | lpr
</verb></tscreen>

The <em>lpr</em> command accepts several command-line arguments that allow a
user to control how it works.  Some of the most widely used arguments are:
-<bf/P/printer specifies the printer to use, -<bf/h/ suppresses printing of
the burst page, -<bf/s/ creates a symbolic link instead of copying the file
to the spool directory (useful for large files), and -<bf/&num;/num
specifies the number of copies to print.  An example interaction with
<em>lpr</em> might be something like

<tscreen><verb>
$ lpr -#2 -sP dj thesis.txt
</verb></tscreen>

This command will create a symbolic link to the file <tt>thesis.txt</tt> in
the spool directory for the printer named <em>dj</em>, where it would be
processed by <em>lpd</em>.  It would then print a second copy of
<tt>thesis.txt</tt>.
<p>
For a listing of all the options that <em>lpr</em> will recognize, see
<em>lpr</em>(1).

<sect1>Viewing the Print Queue with <em>lpq</em>
<p>
<nidx>printing!using lpq command</nidx>
<nidx>lpq command!usage example</nidx>
To view the contents of the print queue, use the <em>lpq</em> command. 
Issued without arguments, it returns the contents of the default printer's
queue.
<p>
The returned output of <em>lpq</em> can be useful for many purposes.

<tscreen><verb>
$ lpq
lp is ready and printing
Rank   Owner      Job  Files                            Total Size
active mwf	  31   thesis.txt			682048 bytes
</verb></tscreen>

<sect1>Canceling a Print Job Using <em>lprm</em>
<p>
<nidx>printing!using lprm command</nidx>
<nidx>lprm command!usage example</nidx>
Another useful feature of any printing system is the ability to cancel a job
that has been previously queued.  To do this, use <em>lprm</em>.

<tscreen><verb>
$ lprm -
</verb></tscreen>

The above command cancels all of the print jobs that are owned by the user
who issued the command.  A single print job can be canceled by first getting
the job number as reported by <em>lpq</em> and then giving that number to
<em>lprm</em>.  For example,

<tscreen><verb>
$ lprm 31
</verb></tscreen>

would cancel job 31 (<tt>thesis.txt</tt>) on the default printer.

<sect1>Controlling the lpd program with <em>lpc</em>
<p>
<nidx>printing!using lpc command</nidx>
<nidx>lpc command!usage example</nidx>
The <em>lpc</em>(8) program is used to control the printers that lpd serves. 
you can enable or disable a printer or its queues, rearrange entries within
a queue, and get a status report on the printers and their queues.
Lpc is mostly used in a setup where there are multiple printers hanging off
one machine.

<tscreen><verb>
$ lpc
</verb></tscreen>

The above will start the lpc program.  By default, this enters you into
an interactive mode, and you can begin issuing commands.  The other option
is to issue an lpc command on the command line.

<tscreen><verb>
$ lpc status all
</verb></tscreen>

A list of the available commands are in the <em>lpd</em> man page, but here
are a few of the major commands you'll want to know about.  Any commands
marked with <em>option</em> can either be a printer name (lp, print, etc) or
the keyword <tt>all</tt>, which means all printers. 

<itemize>
  <item> disable <em>option</em> -  prevents any new printer job from being entered
  <item> down <em>option</em> - disables all printing on the printer
  <item> enable <em>option</em> - allow new jobs to enter the print queue
  <item> quit (or exit) - leave lpc
  <item> restart <em>option</em> - restarts lpd for that printer
  <item> status <em>option</em> - print status of printer
  <item> up <em>option</em> - enable everything and start a new lpd
</itemize>

<sect1> The RedHat printtool
<p>
<nidx>printing!using Red Hat printool</nidx>
<nidx>Red Hat Linux!printool</nidx>
<nidx>printool utility</nidx>
Just a quick note here on RedHat's amazing printtool program.  It seems
to do everything that a magicfilter would do.  RedHat already installs many
of the programs to do the filtering.  Here's how I have my printer set up
under RH 4.0 with an HP LJ 4L connected to my parallel port (should be
the same for other versions of RH as well).
<itemize>
  <item>Become root and fire up printtool (if you su'ed, you remembered to
    SETENV DISPLAY :0.0 and xhost +, right?)
  <item>Click "Add", and hit "OK" for a local printer.
  <item>Fill in the printer device (/dev/lp1 for me)
  <item>Fill in the input filter - Select a printer type, resolution, and paper
    size (ljet4, 300x300, and letter)
  <item>Hit "OK" all the way back, and restart the lpd.
</itemize>
Just like rolling an /etc/printcap file by hand, you can have multiple
printer definitions for each physical printer.  One for different paper
sizes, resolutions, etc.

<sect>Printing files
<p>
<nidx>printing!by file type</nidx>
This section covers printing the kinda of files that you'll run across in a
Linux setup.

<sect1>Printing graphics files
<p>
<nidx>printing!graphics files</nidx>
Printing graphics files through a printer usually depends on the kind of
graphics you're converting, and the kind of printer you want to send to. Dot
matrix is usually out of the question due to differences in the way
dot-matrix handles graphics.  Your best bet in this situation is to see if
your printer is compatable with an Epson or an IBM ProPrinter, then convert
the graphics file to PostScript, then use Ghostscript (see next section) to
print the graphics.
<p>
If you have a laser printer, things are a bit easier since many are
compatable with PCL.  This now gives you a few options.  Some programs may
output directly in PCL.  If not, programs like <em>NetPBM</em> can convert
into PCL.  Last option is to use ghostscript (see next section).
<p>
Your absolutely best option is to install packages like NetPBM and Ghostscript
then installing a magic filter to process the graphics files automagically.

<sect1>Printing PostScript files
<p>
<nidx>printing!Postscript files</nidx>
<nidx>Postscript!printing</nidx>
Printing PostScript files on a printer that has a PostScript interpreter
is simple; just use <em>lpr</em>, and the printer will take care of all
of the details for you.  For those of us that don't have printers with
PostScript capabilities, we have to resort to other means.  Luckily, there
are programs available that can make sense of PostScript, and translate
it into a language that most printers will understand.  Probably the most
well known of these programs is Ghostscript.
<p>
Ghostscript's responsibility is to convert all of the descriptions in a
PostScript file to commands that the printer will understand.  To print
a PostScript file using Ghostscript, you might do something like

<tscreen><verb>
$ gs -dSAFER -dNOPAUSE -sDEVICE=deskjet -sOutputFile=\|lpr thesis.ps
</verb></tscreen>

Notice in the above example that we are actually piping the output of
Ghostscript to the <em>lpr</em> command by using the -<bf/sOutputFile/
option.

Ghostview is an interface to Ghostscript for the X Window System.  It allows
you to preview a PostScript file before you print it.  Ghostview and
Ghostscript can both be swiped from <url url="ftp://prep.ai.mit.edu/pub/gnu/">.

<sect1>Printing PDF files
<p>
<nidx>printing!PDF files</nidx>
<nidx>printing!Acrobat files</nidx>
<nidx>PDF files!printing</nidx>
<nidx>Acrobat files!printing</nidx>
Adobe has released an Acrobat reader for Linux, and it's available on the
Adobe home page <url url="http://www.adobe.com">.  Its predecessor, xpdf, is
also available.  Both should print to a postscript device.

<sect1>Printing TeX files
<p>
<nidx>printing!TeX files</nidx>
<nidx>TeX files!printing</nidx>
One of the easiest ways to print TeX files is to convert them to PostScript
and then print them using Ghostscript.  To do this, you first need to
convert them from TeX to a format known as DVI (which stands for
device-independent). You can do this with the <em>tex</em>(1) command.  Then
you need to convert the DVI file to a PostScript file using <em>dvips</em>. 
All of this would look like the following when typed in.

<tscreen><verb>
$ tex thesis.tex
$ dvips thesis.dvi
</verb></tscreen>

Now you are ready to print the resulting PostScript file as described above.

<sect1>Printing <tt>troff</tt> formatted files
<p>
<nidx>printing!troff files</nidx>
<nidx>troff files!printing</nidx>

<tscreen><verb>
$ groff -Tascii thesis.tr | lpr
</verb></tscreen>

or, if you prefer,

<tscreen><verb>
$ groff thesis.tr > thesis.ps
</verb></tscreen>

and then print the PostScript file as described above.

<sect1>Printing <tt>man</tt> pages
<p>
<nidx>printing!man pages</nidx>
<nidx>man pages!printing</nidx>

<tscreen><verb>
$ man man | col -b | lpr
</verb></tscreen>

The man pages contain pre-formatted <tt>troff</tt> data, so we have to strip
out any highlighting, underlines, etc.  The 'col' program does this just 
nicely, and since we're piping data, the <tt>man</tt> program won`t use
<tt>more</tt>.
<sect> Miscellaneous Items
<p>
This covers topics not in any of the others.

<sect1>Formatting Before Printing
<p>
<nidx>printing!formatting files before</nidx>
Since most ASCII files are not formatted for printing, it is useful to
format them in some way before they are actually printed.  This may include
putting a title and page number on each page, setting the margins, double
spacing, indenting, or printing a file in multiple columns.  A common way to
do this is to use a print preprocessor such as <em>pr</em>.

<tscreen><verb>
$ pr +4 -d -h"Ph.D. Thesis, 2nd Draft" -l60 thesis.txt | lpr
</verb></tscreen>

In the above example, <em>pr</em> would take the file <tt>thesis.txt</tt>
and skip the first three pages (+4), set the page length to sixty lines
(-l60), double space the output (-d), and add the phrase "Ph.D. Thesis, 2nd
Draft" to the top of each page (-h).  <em>Lpr</em> would then queue
<em>pr</em>'s output.  See its on-line manual page for more information on
using <em>pr</em>.

<sect1>The PRINTER Environment Variables
<p>
<nidx>printing!PRINTER environment variable</nidx>
<nidx>PRINTER environment variable</nidx>
All of the commands in the Linux printing system accept the -<bf/P/ option.
This option allows the user to specify which printer to use for output.  If
a user doesn't specify which printer to use, then the default printer will
be assumed as the output device.
<p>
Instead of having to specify a printer to use every time that you print, you
can set the PRINTER environment variable to the name of the printer that you
want to use.  This is accomplished in different ways for each shell.  For
<em>bash</em> you can do this with

<tscreen><verb>
$ PRINTER="printer_name"; export PRINTER
</verb></tscreen>

and <em>csh</em>, you can do it with

<tscreen><verb>
% setenv PRINTER "printer_name"
</verb></tscreen>

These commands can be placed in your login scripts (.profile for <em>bash</em>,
or .cshrc for <em>csh</em>), or issued on the command-line.  (See
<em>bash</em>(1) and <em>csh</em>(1) for more information on environment
variables.)


<sect>Answers to Frequently Asked Questions
<nidx>printing!frequently asked questions</nidx>
<nidx>printing!FAQ</nidx>
<nidx>FAQ!printing usage</nidx>
<p><p>
Q1.  How do I prevent the staircase effect?
<nidx>printing!staircase effect</nidx>
<p>
A1.  The staircase effect is caused by the way some printers expect lines to
be terminated.  Some printers want lines that end with a
carriage-return/line-feed sequence (DOS-style) instead of the line-feed
sequence used for UNIX-type systems.  The easiest way to fix this is to see
if your printer can switch between the two styles somehow---either by
flipping a DIP switch, or by sending an escape sequence at the start of each
print job.  To do the latter, you need to create a filter (see Q2).

A quick fix is to use a filter on the command-line.  An example of this
might be

<tscreen><verb>
$ cat thesis.txt | todos | lpr
</verb></tscreen>

<p>
Q2.  What is a filter?
<nidx>printing!filter</nidx>
<p>
A2.  A filter is a program that reads from standard input (<em>stdin</em>),
performs some action on this input, and writes to standard output
(<em>stdout</em>).  Filters are used for a lot of things, including text
processing.
<p><p>
Q3.  What is a <em>magic</em> filter?
<nidx>printing!magic filter</nidx>
<p>
A3.  A magic filter is a filter that performs an action based on a file's
type.  For example, if the file is a plain, text file, it would simply print
the file using the normal methods.  If the file is a PostScript file, or any
other format, it would print it using another method (ghostscript).  Two
examples of this is magicfilter and APSfilter.  One caveat of these filters
is that the appropriate programs have to be installed before you install
the filter.
<p>
The reason for this is that when the magicfilter gets installed, it queries
your system for specific programs (such as ghostscript - if it finds it, then
it knows it can handle PostScript data), then builds itself based on what it
finds.  To handle all the printer files, you should probably have at least
the following installed:
<itemize>
<item>GhostScript
<item>TeX
<item>NetPBM
<item>jpeg utilities
<item>gzip
</itemize>
<p><p>
Q4.  What about the Windows Printing System?  Will Linux work with that?
<nidx>printing!Windows Printing System (WPS)</nidx>
<p>
A4.  Maybe.  Printers that accept only the WPS commands will not
work with Linux.  Printers that accept WPS and other commands
(such as the Canon BJC 610) will work, as long as they're set to
something other than WPS format.  Other printers, such as some HP DeskJet
820Cxi/Cse, will *not* work with Linux.  That being said, Linux can act
as a print server (See Samba) for Win95 machines, since Win95 has drivers
for those printers.
<p><p>
Q5.  What kinda cheey system is this?  I can't print more than 6 pages
or else I get a "file too large" error.
<nidx>printing!file too large error</nidx>
<p>
A5.  One of the options in the /etc/printcap file relates to the maximum
size of a print file.  The default is 1000 disk blocks (about 500k?).  For
PostScript files and the like, this will give you maybe 6-8 pages with
graphics and all.  Be sure to add the following line in the printer
definition:
<tscreen><verb>
mx=0
</verb></tscreen>
The primary reason for this is to keep the spool partition from getting
filled.  There is another way to do it, by making lpr create a soft
link from the spool directory to your print file.  But you have to remember to
add the <tt>-s</tt> option to lpr every time.
<p>
<sect>Troubleshooting
<p>
<nidx>printing!troubleshooting</nidx>
This section covers some common things that can go wrong with your printing
system.
<p>
If your printer doesn't work:
<itemize>
   <item>Do other print jobs work? (application problem?)
   <item>Is lpd running? (check it using lpc) (print controller?)
   <item>Can root send something directly to the printer? (print services?)
   <item>Can you print from DOS? (cable/printer problem?)
</itemize>
Answering these questions can help find a solution.

Send other suggestions for this section to &lt;markk@auratek.com&gt;.

<sect>References
<p>
<nidx>printing!reference material</nidx>
This is a section of references on the Linux printing system.  I have
tried to keep the references section of this HOWTO as focused as
possible.  If you feel that I have forgotten a significant reference
work, please do not hesitate to contact me.
<p>
Before you post your question to a USENET group, consider the following:
<itemize>
  <item>Is the printer accepting jobs?  (Use <em>lpc</em>(8) to verify.)
  <item>Is the answer to your question covered in this HOWTO or Grant
Taylor's Printing HOWTO?
</itemize>
<p>
If any of the above are true, you may want to think twice before you post
your question.  And, when you do finally post to a newsgroup, try to include
pertinent information.  Try not to just say something like, "I'm having
trouble with lpr, please help." These types of posts will most definitely be
ignored by many.  Also try to include the kernel version that you're
running, how the error occured, and, if any, the specific error message that
the system returned.

<descrip>
<tag>On-Line Manual Pages</tag>
<nidx>printing!related man pages</nidx>
  <itemize>
    <item><em>cat</em>(1)  concatenate and print files
    <item><em>dvips</em>(1)  convert a TeX DVI file to PostScript
    <item><em>ghostview</em>(1)  view PostScript documents using Ghostscript
    <item><em>groff</em>(1)  front-end for the groff document formatting system
    <item><em>gs</em>(1)  Ghostscript interpreter/viewer
    <item><em>lpc</em>(8)  line printer control program
    <item><em>lpd</em>(8)  line printer spooler daemon
    <item><em>lpq</em>(1)  spool queue examination program
    <item><em>lpr</em>(1)  off-line printer
    <item><em>lprm</em>(1)  remove jobs from the line printer spooling queue
    <item><em>pr</em>(1)  convert text files for printing
    <item><em>tex</em>(1)  text formatting and typesetting
  </itemize>
<p>
<tag>USENET newsgroups</tag>
<nidx>printing!relates newsgroups</nidx>
  <itemize>
    <item><tt>comp.os.linux.*</tt>  a plethora of information on Linux
    <item><tt>comp.unix.*</tt>  discussions relating to the UNIX operating system
  </itemize>
</descrip>
</article>
