@c $Id: printing.texinfo,v 1.30 2001/05/16 16:57:59 m Exp m $
@node Printing, Platform Conversions, Disk Storage, Productivity
@comment node-name,     next,	previous,	up
@chapter Printing
@cindex printing
@cindex files, printing
@cindex staircase effect
@pindex magicfilter

@flushleft
@sf{Debian}: @file{magicfilter}
@end flushleft
@*
@noindent
The usual way to print on a Linux system is to send a print job to the
printer with @code{lpr}, as described below in @ref{Sending Print Jobs,
, Sending a Print Job to the Printer}.

But you don't always send a file straight to the printer---sometimes you
may want to add special things to it before you print it, such as
headers or graphic trim. For example, you might want to split a text
file into pages and add a header to the top of each page containing the
file name and page number; all of this is described in @ref{Formatting
Text, , Formatting Text}.

Sometimes you may need to convert or otherwise prepare a file so that it
can be printed on your particular printer, since not all print hardware
can print the same kinds of file formats. Recipes in this chapter show
how to do this, such as how to convert PostScript files so that they
will print properly on a non-PostScript printer (@pxref{Print
Preparations, , Preparing Files for Printing}).

This chapter also shows how to format PostScript files for printing. To
convert plain text to PostScript and enhance it for printing, by adding
fonts, graphic headers, and the like, see @ref{Enscript, , Converting
Plain Text for Output}.

And this chapter isn't in the files section, because you can print
things that aren't in a file---for example, you can pipe the output of
another tool or series of tools to @code{lpr}, and it will spool that
command output to the printer. This usage is actually very common.

@sp .25
@noindent
@strong{NOTE:} When a printer is properly configured on Linux, it is a
pleasure to use, but a misconfigured printer can lead to all kinds of
trouble---including the dreaded ``staircase effect,'' where a text file
prints with each subsequent line of output offset to the right by the
length of the previous line.

If print services haven't been configured yet on your system, I strongly
recommend that the @file{magicfilter} package be installed; it includes
filters for the automatic detection of file types---when you print a
file, it automatically converts it to the proper format for your
printer.

Comprehensive details on the setup of printer resources can be found in
both the @cite{Printing HOWTO} and the @cite{Printing Usage HOWTO}
(@pxref{HOWTOs, , Reading System Documentation and Help Files}).

@menu
* Print Jobs::                  Sending a job to the printer.
* Application Printing::        Print services in some applications.
* Print Preparations::          Converting files for your printer.
@end menu


@node Print Jobs, Application Printing, Printing, Printing
@comment  node-name,  next,  previous,  up
@section Making and Managing Print Jobs
@cindex making and managing print jobs
@cindex print jobs, making and managing
@cindex spool queue

@noindent
The traditional way to print on Linux-based systems is to send a
@dfn{print job} for the file or data you want to print to the @dfn{spool
queue} for the printer in question. The spool queue contains all of the
print jobs sent to it by all users; these jobs are released in turn to
the printer device as it becomes available. In this way, Linux can
handle multiple print jobs going to the same printer at once.

The following recipes show how to make and manage print jobs. In
practice, you will probably send print jobs all the time---since this is
the way most printing is done in Linux---and use the tools for listing
or cancelling print jobs rarely. But sometimes things do go wrong, and
it helps to know what to do when that happens.

@menu
* Sending Print Jobs::          Sending a print job.
* Printing Copies::             Printing more than one copy.
* Listing Print Jobs::          Listing your print jobs.
* Cancelling Print Jobs::       Cancelling a print job.
@end menu


@node Sending Print Jobs, Printing Copies, Print Jobs, Print Jobs
@comment  node-name,  next,  previous,  up
@subsection Sending a Print Job to the Printer
@cindex sending a print job to the printer
@cindex print job, sending to the printer
@cindex printing
@cindex line printer
@pindex lpr

@noindent
Use @code{lpr} to send a print job to the printer---give the name of the
file to print as an argument. (You can also pipe the output of a command
to @code{lpr}.)

@code{lpr} writes a copy of the specified file or text to the spool
queue of the specified printer, to be sent to the printer when the
printer becomes available.

@itemize @bullet
@item
To print the file @file{invoice}, type:

@example
$ @kbd{lpr invoice @key{RET}}
@end example

@item
To type a message with @code{banner} and send it to the printer, type:

@example
$ @kbd{banner "Bon voyage!" | lpr @key{RET}}
@end example

@item
To print a verbose, recursive listing of the @file{/usr/doc/HOWTO}
directory, type:

@example
$ @kbd{ls -lR /usr/doc/HOWTO | lpr @key{RET}}
@end example
@end itemize

If you have more than one printer connected to your system, specify the
printer to send to as an argument to the @samp{-P} option. (Printers
have names just as user accounts and hosts do, and it is the
administrator's privilege to name them; the default printer is usually
called @code{lp}, for ``line printer.'')

@itemize @bullet
@item
To send the file @file{nightly-report} to the printer called
@code{bossomatic}, type:

@example
$ @kbd{lpr -P bossomatic nightly-report @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} The name of the @code{lpr} tool comes from ``line
printer,'' which was the kind of printer hardware in popular use back
when this program was first developed. 


@node Printing Copies, Listing Print Jobs, Sending Print Jobs, Print Jobs
@comment  node-name,  next,  previous,  up
@subsection Printing Multiple Copies of a Job
@cindex printing multiple copies of a job
@cindex job, printing multiple copies of a 
@pindex lpr

@noindent
To print more than one copy of a print job, give the number of copies to
print as an argument to the @samp{-#} option of @code{lpr}.

@itemize @bullet
@item
To print a dozen copies of the file @file{nightly-report}, type:

@example
$ @kbd{lpr -#12 nightly-report @key{RET}}
@end example
@end itemize


@node Listing Print Jobs, Cancelling Print Jobs, Printing Copies, Print Jobs
@comment  node-name,  next,  previous,  up
@subsection Listing Your Print Jobs
@cindex listing your print jobs
@cindex print jobs, listing your
@cindex active job
@pindex lpq

@noindent
To list your print jobs, use @code{lpq}, the ``line printer queue''
tool. It outputs a list of all print jobs currently in the default
printer's spool queue---each on a line of its own---giving its rank in
the queue, the username who sent the job, the print job number, the file
names in the job, and the size of the data to be printed, in bytes. 

@itemize @bullet
@item
To view the spool queue for the default printer, type:

@example
@cartouche
$ @kbd{lpq @key{RET}}
lp is ready and printing
Rank   Owner      Job  Files                            Total Size
active groucho   83   cigar.ps                       1739030 bytes
1st    harpo     84   harp.ps                            499 bytes
2nd    chico     85   love.ps                          45576 bytes
$
@end cartouche
@end example
@end itemize

In this example, there are three jobs queued for the default
printer---one by user @code{groucho}, for the file @file{cigar.ps}, one
by user @code{harpo}, for the file @file{harp.ps}, and one by user
@code{chico}, who has printed a file called @file{love.ps}.

The job by user @code{groucho} is the @dfn{active job}; this is the job
that is currently printing on the printer. The other jobs must wait
until this file is finished printing, and then they print in rank order.

As with @code{lpr}, you can specify the name of a printer as an argument
to the @samp{-P} option. 

@itemize @bullet
@item
To view the spool queue for the printer called @code{bossomatic}, type:

@example
$ @kbd{lpq -P bossomatic @key{RET}}
@end example
@end itemize

To only list the jobs for a particular user, give the name of the user as
an argument. 

@itemize @bullet
@item
To list the print jobs for user @code{harpo}, type:

@example
$ @kbd{lpq harpo @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} When there are no print jobs, @code{lpq} outputs the text
@samp{no entries}.


@node Cancelling Print Jobs, , Listing Print Jobs, Print Jobs
@comment  node-name,  next,  previous,  up
@subsection Cancelling a Print Job
@cindex cancelling a print job
@cindex print job, cancelling a
@pindex lprm

@noindent
To cancel a print job and remove it from the spool queue, use
@code{lprm}, the ``line printer remove'' tool. Give as an argument the
number of the print job to remove.

@itemize @bullet
@item
To cancel print job 83, type:

@example
$ @kbd{lprm 83 @key{RET}}
@end example
@end itemize

To cancel @emph{all} of your print jobs in the spool queue, use a hyphen
instead of the number of a print job.

@itemize @bullet
@item
To cancel all of your print jobs, type:

@example
$ @kbd{lprm - @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} If you try to cancel an active job---one that has already
been spooled to the printer---don't be alarmed if some pages still
print; the printer probably has some of the job in its internal print
buffer. To stop the printing in a case like this, take the printer
offline, reset it, and then put it back online again (usually, the
printer will have buttons for these commands on its front control
panel).


@node Application Printing, Print Preparations, Print Jobs, Printing
@comment  node-name,  next,  previous,  up
@section More Recipes for Printing
@cindex more recipes for printing
@cindex printing, more recipes for
@pindex lpr
@pindex LyX

@noindent
Another way of printing besides making a print job is to print from
within an application.

Not all applications have print controls, but some of them
do---including Emacs and LyX (@pxref{LyX, , LyX Document
Processing}). Their print commands essentially send the print job to the
printer via @code{lpr}, after possibly formatting or otherwise preparing
the data to print. If you are working in such an application and want to
print your work, using the built-in print control can be easier than
having to go to a shell to run @code{lpr}.

For example, to print the current document in the LyX document
processing application, choose @code{Print} from the @code{File} menu;
it creates the proper output for your printer and makes a print job
containing this output (@pxref{LyX, , LyX Document Processing}).

Some tools, such as @code{dvips} and @code{enscript} (@pxref{Enscript, ,
Converting Plain Text for Output}), are also configured to spool output
to the printer.

You can view these print jobs in the spool queue and you can cancel
them, just as you could any print job.

@menu
* Emacs Printing::              Printing in Emacs.
* Dvips Printing::              Printing with dvips.
* Xterm Printing::              Printing an xterm window.
@end menu


@node Emacs Printing, Dvips Printing, Application Printing, Application Printing
@comment  node-name,  next,  previous,  up
@subsection Printing in Emacs
@cindex printing in Emacs
@cindex Emacs, printing in
@pindex Emacs

@noindent
To print the current buffer in Emacs, choose @code{Print Buffer} from
the @code{Print} submenu, found off the @code{Tools} menu on the menu
bar. Another option on the print submenu is @code{Print Region}, which
just prints the text between point and the mark (@pxref{Emacs Intro, ,
Getting Acquainted with Emacs}). Both commands print the hardcopy output
separated into pages, and with headers at the top of each page, showing
the file name and current page number.

To generate and print a PostScript image of the buffer, use the
@code{ps-print-buffer} function, which is also available on the
@code{Print} submenu. A related function, @code{ps-print-region},
prints a PostScript image of the region. These commands are useful for
sending the text of a buffer to a PostScript printer.

You can also run any of these functions by specifying them with the
@kbd{M-x} command; additionally, the @code{lpr-buffer} and
@code{lpr-region} functions send the buffer and region to @code{lpr}
without paginating the text or inserting headers.

@itemize @bullet
@item
To print the current buffer with page numbers and headers, type:

@example
@kbd{M-x print-buffer @key{RET}}
@end example

@item
To print the current buffer with no additional print formatting done to
the text, type:

@example
@kbd{M-x lpr-buffer @key{RET}}
@end example

@item
To print a PostScript image of the current buffer, type:

@example
@kbd{M-x ps-print-buffer @key{RET}}
@end example
@end itemize


@node Dvips Printing, Xterm Printing, Emacs Printing, Application Printing
@comment  node-name,  next,  previous,  up
@subsection Printing with Dvips
@cindex printing with Dvips
@cindex Dvips, printing with
@cindex DVI files, printing
@cindex envelopes, printing
@pindex dvips
@pindex lpr

@noindent
You can print a DVI file directly with the @code{dvips} tool---omit the
@samp{-o} option that is used to specify an output file, and it will
send the PostScript output directly to the spool queue of the default
printer.

@itemize @bullet
@item
To print the DVI file @file{list.dvi}, type:

@example
$ @kbd{dvips list.dvi @key{RET}}
@end example
@end itemize

The following table lists some of @code{dvips}'s various options for
controlling print output.

@multitable @columnfractions .30 .70
@item @sc{Option}
@tab @sc{Description}
@item @code{-A}
@tab Print only odd-numbered pages (DVI file must have been generated by
@TeX{}).

@item @code{-B}
@tab Print only even-numbered pages (DVI file must have been generated
by @TeX{}).

@item @code{-b @var{copies}}
@tab Specify the number of copies to print---useful for printing
multiple copies of flyers, posters, signs, and the like.

@item @code{-k}
@tab Print crop marks.

@item @code{-l @var{last}}
@tab Specify the last page number to print.

@item @code{-m}
@tab Use the manual feed tray.

@item @code{-p @var{first}}
@tab Specify the first page to begin printing from.

@item @code{-r}
@tab Reverse the order of the pages.

@item @code{-t @var{format}}
@tab Specify paper size and format; valid options include @samp{letter},
@samp{legal}, @samp{a4}, and @samp{landscape}. (You can use this option
twice, say to specify both @samp{legal} and @samp{landscape}).
@end multitable

Using the @file{-m} option and specifying landscape as the paper format
with the @samp{-t} option is very useful for printing on envelopes.

@itemize @bullet
@item
To print the file @file{envelope.dvi} on an envelope loaded in the
manual feed tray of the default printer, type:

@example
$ @kbd{dvips -m -t landscape envelope.dvi @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} You can also print DVI files with @code{lpr} using the
@samp{-d} option.


@node Xterm Printing, , Dvips Printing, Application Printing
@comment  node-name,  next,  previous,  up
@subsection Printing the Contents of an Xterm Window
@cindex printing the contents of an Xterm window
@cindex Xterm window, printing the contents of an
@pindex xterm

@noindent
To print the contents of an @code{xterm} window, press and hold
@key{CTRL} and left-click anywhere inside the window, and choose the
@code{Print Window} option. This command will send a copy of all the
text in the current window to the default printer.


@node Print Preparations, , Application Printing, Printing
@comment  node-name,  next,  previous,  up
@section Preparing Files for Printing
@cindex preparing files for printing
@cindex printing, preparing files for
@cindex files, preparing for printing

@noindent
Not all printers recognize all output formats, so it's sometimes
necessary to convert files before you print them.

Normally, you can print plain text on any printer. However, most
graphics or image files must be converted to PostScript or EPS
(``Encapsulated PostScript''). Some applications---such as
@TeX{}---produce DVI output; in this case, you convert that to
PostScript for printing.

If you have a PostScript printer, you can print PostScript files
directly to it. If not, you'll need to convert the PostScript output to
a format your printer uses. Filter programs like @file{magicfilter} make
the conversion easier by doing this work for you, but they're not a
panacea, since your system may use one of a great many filters. Hence,
the need for the following recipes.

@menu
* Preparing PS::               Preparing PostScript for printing.
* Preparing DVI::              Preparing DVI for printing.
* Preparing PDF::              Preparing PDF for printing.
* Preparing Man::              Preparing man pages for printing.
@end menu


@node Preparing PS, Preparing DVI, Print Preparations, Print Preparations
@comment  node-name,  next,  previous,  up
@subsection Preparing a PostScript File for Printing
@cindex preparing a PostScript file for printing
@cindex PostScript file, preparing for printing
@pindex gs

@flushleft
@sf{Debian}: @file{gs}
@sf{WWW}: @url{ftp://www.gnu.org/pub/gnu/ghostscript/}
@end flushleft
@*
@noindent
If you don't have a PostScript printer, you can use Ghostscript,
@code{gs}, to convert PostScript to an output format that your printer
understands.

Use the @samp{-?} option to list the printers that the version of
@code{gs} installed on your system can write output for.

@itemize @bullet
@item
To list the available printer formats, type:

@example
@cartouche
$ @kbd{gs -? @key{RET}}
GNU Ghostscript 5.10 (1998-12-17)
@var{...more output messages...}
Input formats: PostScript PostScriptLevel1 PostScriptLevel2 PDF
Available devices:
   x11 x11alpha x11cmyk x11gray2 x11mono lvga256 vgalib 
   t4693d8 tek4696 appledmp ccr lp2563 lbp8 lips3 m8510 
   oki182 okiibm la50 la70 la75 la75plus sxlcrt deskjet
   djet500 laserjet ljetplus ljet2p ljet3 ljet4 declj250
   cdeskjet cdjcolor cdjmono cdj550 cdj500 djet500c 
   hpdj uniprint epson eps9mid eps9high epsonc lq850
   ap3250 ibmpro bj10e bj200 bjc600 bjc800 ljet3d faxg3
   faxg32d faxg4 dfaxhigh dfaxlow pcxmono pcxgray pbm 
   pbmraw pgm pgmraw pgnm pgnmraw pnm pnmraw ppm ppmraw
   pkm pkmraw tiffcrle tiffg3 tiffg32d tiffg4 psmono
   psgray jpeg
@var{...more output messages...}
$
@end cartouche
@end example
@end itemize

A typical @code{gs} installation can write to more than 100 different
print devices, including HP LaserJet 4 printers (@samp{ljet4}), HP Color
DeskJets (@samp{cdeskjet}), and Group 4 fax (@samp{tiffg4}). Newer
versions of @code{gs} will have better support for newer printers, so
make sure that you have a recent version installed if you have a new
model printer.

@code{gs} takes the file to convert as an argument; give the device to
write output for as an argument to the @samp{-sDEVICE=} option, and give
the name of the file to write to as an argument to the
@samp{-sOutputFile=} option.

Two additional options are commonly used: @samp{-dSAFER}, which prevents
the accidental deleting or overwriting of files, and @samp{-dNOPAUSE},
which turns off the pause between pages.

When the conversion is complete, you will be at the @code{gs} prompt;
type @kbd{quit} to exit.

@itemize @bullet
@item
To convert the file @file{tiger.ps} to a format suitable for printing on
an HP Color DeskJet 500 printer, type:

@example
$ @kbd{gs -sDEVICE=cdj500 -sOutputFile=tiger.dj -dSAFER -dNOPAUSE
tiger.ps < /dev/null @key{RET}} 
@end example
@end itemize

This command writes the output to a file, @file{tiger.dj}, which you can
spool as a print job with @code{lpr} to print.


@node Preparing DVI, Preparing PDF, Preparing PS, Print Preparations
@comment  node-name,  next,  previous,  up
@subsection Preparing a DVI File for Printing
@cindex preparing a DVI file for printing
@cindex DVI file, preparing for printing
@cindex PDF, converting to

@flushleft
@sf{Debian}: @file{tetex-bin}
@sf{WWW}: @url{http://www.radicaleye.com/dvips/}
@end flushleft
@*
@noindent
To convert a file from DVI format to PostScript, use @code{dvips}. It
takes the file to convert as an argument; give the name of the
PostScript file to write to as an argument to the @samp{-o} option.

@itemize @bullet
@item
To convert the file @file{abstract.dvi} to PostScript, type:

@example
$ @kbd{dvips -o abstract.ps abstract.dvi @key{RET}}
@end example
@end itemize

This command reads the DVI file @file{abstract.dvi} and writes a
PostScript version of it to the file @file{abstract.ps}; the original
file is not altered.

To write only certain pages of a DVI file to the PostScript output, give
the page or pages as arguments to the @samp{-pp} option.

@itemize @bullet
@item
To output only pages 14 and 36 from file @file{abstract.dvi} to a
PostScript file, @file{abstract.ps}, type:

@example
$ @kbd{dvips -pp14,36 -o abstract.ps abstract.dvi @key{RET}}
@end example

@item
To output pages 2 through 100 from file @file{abstract.dvi} to a
PostScript file, @file{abstract.ps}, type:

@example
$ @kbd{dvips -pp2-100 -o abstract.ps abstract.dvi @key{RET}}
@end example

@item
To output page 1 and pages 5 through 20 from file @file{abstract.dvi} to
a PostScript file, @file{abstract.ps}, type: 

@example
$ @kbd{dvips -pp1,5-20 -o abstract.ps abstract.dvi @key{RET}}
@end example
@end itemize

To specify an output paper size, give it as an argument to the @samp{-t}
option; if you have a PostScript printer, you can also send the output
directly to the printer (@pxref{Dvips Printing, , Printing with
Dvips}). 

@itemize @bullet
@item
To output the file @file{abstract.dvi} as a PostScript file,
@file{abstract.ps}, with a paper size of @samp{legal}, type: 

@example
$ @kbd{dvips -t legal -o abstract.ps abstract.dvi @key{RET}}
@end example

@item
To print the file @file{abstract.dvi} to the default printer in
landscape mode, type: 

@example
$ @kbd{dvips -t landscape abstract.dvi @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} This conversion is not only useful for print
preparation. Once the DVI file is converted to PostScript, you can then
convert the PostScript to other formats, such as plain text or PDF---see
@ref{PS Conversions, , Converting PostScript}.

Use the @samp{-P} option with @code{dvips} to specify the printer name
to write output to---use this option to make output for non-PostScript
printers. For example, to convert @TeX{} and LaTeX files to PDF, use
@code{dvips} and give @samp{pdf} as an argument to the @samp{-P} option.

@itemize @bullet
@item
To generate a PDF file from the DVI file @file{abstract.dvi}, type:

@example
$ @kbd{dvips -Ppdf -o abstract.pdf abstract.dvi @key{RET}}
@end example
@end itemize

This command writes a new file, @file{abstract.pdf}, in PDF format.


@node Preparing PDF, Preparing Man, Preparing DVI, Print Preparations
@comment  node-name,  next,  previous,  up
@subsection Preparing a PDF File for Printing
@cindex preparing a PDF file for printing
@cindex PDF file, preparing for printing
@cindex PDF, converting from
@pindex xpdf
@pindex lpr
@pindex pdf2ps
@pindex gs

@flushleft
@sf{Debian}: @file{xpdf}
@sf{Debian}: @file{gs}
@sf{WWW}: @url{http://www.aimnet.com/~derekn/xpdf/}
@sf{WWW}: @url{http://www.cs.wisc.edu/~ghost/}
@end flushleft
@*
@noindent
There are at least two ways to convert and print a file that's in
Adobe's Portable Document Format (PDF), usually marked with a
@file{.pdf} file name extension.

The first way is to view the file in @code{xpdf} (the PDF file viewer),
and then left-click the printer icon. This won't actually send the file
to the printer, but it writes a PostScript file in the same directory,
with the same base file name as the PDF file but with a @file{.ps}
extension. You can then print this file with @code{lpr} or convert it to
another format (@pxref{Preparing PS, , Preparing a PostScript File for
Printing}).

The second way is to use @code{pdf2ps}, part of the @file{gs} package,
to convert the PDF file to PostScript (then print the PostScript output
as described for @code{xpdf} above). @code{pdf2ps} takes two arguments:
the name of the PDF file to convert, and the name of the PostScript file
to write to.

@itemize @bullet
@item
To convert the PDF file @file{pricelist.pdf}, type:

@example
$ @kbd{pdf2ps pricelist.pdf pricelist.ps @key{RET}}
@end example
@end itemize

This command writes a PostScript file @file{pricelist.ps} in the current
directory.


@node Preparing Man, , Preparing PDF, Print Preparations
@comment  node-name,  next,  previous,  up
@subsection Preparing a Man Page for Printing
@cindex preparing a man page for printing
@cindex man pages, preparing for printing
@pindex man
@pindex gs
@pindex lpr

@noindent
To convert a @code{man} page to output that is suitable for printing,
use the @samp{-t} to output PostScript, and either pipe the output to
@code{lpr} (if you have a PostScript printer), or save it to a file that
you can then convert for your printer.

@itemize @bullet
@item
To output the @code{man} page for @code{psbook} as PostScript and send
it as a print job to the default printer, type:

@example
$ @kbd{man -t psbook | lpr @key{RET}}
@end example

@item
To output the @code{man} page for @code{psbook} to the file
@file{psbook.ps}, type: 

@example
$ @kbd{man -t psbook > psbook.ps @key{RET}}
@end example
@end itemize

In the preceding example, you can then use @code{gs} to convert the file
to a format your non-PostScript printer understands (@pxref{Preparing
PS, , Preparing a PostScript File for Printing}).

@sp .25
@noindent
@strong{NOTE:} A manual ``page'' can actually contain more than one
physical page; the output will have as many pages as necessary to print
it.