path: root/en_US.ISO8859-1/books/handbook/printing/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
    The FreeBSD Documentation Project

    $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="printing">

  <info>
    <title>Printing</title>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Warren</firstname>
	  <surname>Block</surname>
	</personname><contrib>Originally contributed by </contrib>
      </author>
    </authorgroup>
  </info>

  <para>Putting information on paper is a vital function, despite many
    attempts to eliminate it.  Printing has two basic components.  The
    data must be delivered to the printer, and must be in a form that
    the printer can understand.</para>

  <sect1 xml:id="printing-quick-start">
    <title>Quick Start</title>

    <para>Basic printing can be set up quickly.  The printer must be
      capable of printing plain <acronym>ASCII</acronym> text.  For
      printing to other types of files, see
      <xref linkend="printing-lpd-filters"/>.</para>

    <procedure>
      <step>
	<para>Create a directory to store files while they are being
	  printed:</para>

	<screen>&prompt.root; <userinput>mkdir -p /var/spool/lpd/lp</userinput>
&prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/lp</userinput>
&prompt.root; <userinput>chmod 770 /var/spool/lpd/lp</userinput></screen>
      </step>

      <step>
	<para>As <systemitem class="username">root</systemitem>,
	  create <filename>/etc/printcap</filename> with these
	  contents:</para>

	<programlisting>lp:\
	<replaceable>:lp=/dev/unlpt0:\</replaceable>  <co xml:id="printing-qs-co-printcap"/>
	:sh:\
	:mx#0:\
	:sd=/var/spool/lpd/lp:\
	:lf=/var/log/lpd-errs:</programlisting>

	<calloutlist>
	  <callout arearefs="printing-qs-co-printcap">
	    <para>This line is for a printer connected to a
	      <acronym>USB</acronym> port.</para>

	    <para>For a printer connected to a parallel or
	      <quote>printer</quote> port, use:</para>

	    <programlisting>:lp=/dev/lpt0:\</programlisting>

	    <para>For a printer connected directly to a network,
	      use:</para>

	    <programlisting>:lp=:rm=<replaceable>network-printer-name</replaceable>:rp=raw:\</programlisting>

	    <para>Replace
	      <replaceable>network-printer-name</replaceable> with the
	      <acronym>DNS</acronym> host name of the network
	      printer.</para>
	  </callout>
	</calloutlist>
      </step>

      <step>
	<para>Enable <command>lpd</command> by editing
	  <filename>/etc/rc.conf</filename>, adding this line:</para>

	<programlisting>lpd_enable="YES"</programlisting>

	<para>Start the service:</para>

	<screen>&prompt.root; <userinput>service lpd start</userinput>
Starting lpd.</screen>
      </step>

      <step>
	<para>Print a test:</para>

	<screen>&prompt.root; <userinput>printf "1. This printer can print.\n2. This is the second line.\n" | lpr</userinput></screen>

	<tip>
	  <para>If both lines do not start at the left border, but
	    <quote>stairstep</quote> instead, see
	    <xref linkend="printing-lpd-filters-stairstep"/>.</para>
	</tip>

	<para>Text files can now be printed with
	  <command>lpr</command>.  Give the filename on the command
	  line, or pipe output directly into
	  <command>lpr</command>.</para>

	<screen>&prompt.user; <userinput>lpr textfile.txt</userinput>
&prompt.user; <userinput>ls -lh | lpr</userinput></screen>
      </step>
    </procedure>
  </sect1>

  <sect1 xml:id="printing-connections">
    <title>Printer Connections</title>

    <para>Printers are connected to computer systems in a variety of
      ways.  Small desktop printers are usually connected directly to
      a computer's <acronym>USB</acronym> port.  Older printers are
      connected to a parallel or <quote>printer</quote> port.  Some
      printers are directly connected to a network, making it easy for
      multiple computers to share them.  A few printers use a rare
      serial port connection.</para>

    <para>&os; can communicate with all of these types of
      printers.</para>

    <variablelist>
      <varlistentry xml:id="printing-connections-usb">
	<term><acronym>USB</acronym></term>

	<listitem>
	  <para><acronym>USB</acronym> printers can be connected to
	    any available <acronym>USB</acronym> port on the
	    computer.</para>

	  <para>When &os; detects a <acronym>USB</acronym> printer,
	    two device entries are created:
	    <filename>/dev/ulpt0</filename> and
	    <filename>/dev/unlpt0</filename>.  Data sent to either
	    device will be relayed to the printer.  After each print
	    job, <filename>ulpt0</filename> resets the
	    <acronym>USB</acronym> port.  Resetting the port can cause
	    problems with some printers, so the
	    <filename>unlpt0</filename> device is usually used
	    instead.  <filename>unlpt0</filename> does not reset the
	    USB port at all.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="printing-connections-parallel">
	<term>Parallel (<acronym>IEEE</acronym>-1284)</term>

	<listitem>
	  <para>The parallel port device is
	    <filename>/dev/lpt0</filename>.  This device appears
	    whether a printer is attached or not, it is not
	    autodetected.</para>

	  <para>Vendors have largely moved away from these
	    <quote>legacy</quote> ports, and many computers no longer
	    have them.  Adapters can be used to connect a parallel
	    printer to a <acronym>USB</acronym> port.  With such an
	    adapter, the printer can be treated as if it were actually
	    a <acronym>USB</acronym> printer.  Devices called
	    <emphasis>print servers</emphasis> can also be used to
	    connect parallel printers directly to a network.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="printing-connections-serial">
	<term>Serial (RS-232)</term>

	<listitem>
	  <para>Serial ports are another legacy port, rarely used for
	    printers except in certain niche applications.  Cables,
	    connectors, and required wiring vary widely.</para>

	  <para>For serial ports built into a motherboard, the serial
	    device name is <filename>/dev/cuau0</filename> or
	    <filename>/dev/cuau1</filename>.  Serial
	    <acronym>USB</acronym> adapters can also be used, and
	    these will appear as
	    <filename>/dev/cuaU<replaceable>0</replaceable></filename>.</para>

	  <para>Several communication parameters must be known to
	    communicate with a serial printer.  The most important are
	    <emphasis>baud rate</emphasis> or <acronym>BPS</acronym>
	    (Bits Per Second) and <emphasis>parity</emphasis>.  Values
	    vary, but typical serial printers use a baud rate of 9600
	    and no parity.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="printing-connections-network">
	<term>Network</term>

	<listitem>
	  <para>Network printers are connected directly to the local
	    computer network.</para>

	  <para>The <acronym>DNS</acronym> hostname of the printer
	    must be known.  If the printer is assigned a dynamic
	    address by <acronym>DHCP</acronym>, <acronym>DNS</acronym>
	    should be dynamically updated so that the host name always
	    has the correct <acronym>IP</acronym> address.  Network
	    printers are often given static <acronym>IP</acronym>
	    addresses to avoid this problem.</para>

	  <para>Most network printers understand print jobs sent with
	    the <acronym>LPD</acronym> protocol.  A print queue name
	    can also be specified.  Some printers process data
	    differently depending on which queue is used.  For
	    example, a <literal>raw</literal> queue prints the data
	    unchanged, while the <literal>text</literal> queue adds
	    carriage returns to plain text.</para>

	  <para>Many network printers can also print data sent
	    directly to port 9100.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2 xml:id="printing-connections-summary">
      <title>Summary</title>

      <para>Wired network connections are usually the easiest to
	set up and give the fastest printing.  For direct connection
	to the computer, <acronym>USB</acronym> is preferred for speed
	and simplicity.  Parallel connections work but have
	limitations on cable length and speed.  Serial connections are
	more difficult to configure.  Cable wiring differs between
	models, and communication parameters like baud rate and parity
	bits must add to the complexity.  Fortunately, serial printers
	are rare.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="printing-pdls">
    <title>Common Page Description Languages</title>

    <para>Data sent to a printer must be in a language that the
      printer can understand.  These languages are called Page
      Description Languages, or <acronym>PDL</acronym>s.</para>

    <variablelist>
      <varlistentry xml:id="print-pdls-ascii">
	<term><acronym>ASCII</acronym></term>

	<listitem>
	  <para>Plain <acronym>ASCII</acronym> text is the simplest
	    way to send data to a printer.  Characters correspond one
	    to one with what will be printed: an <literal>A</literal>
	    in the data prints an <literal>A</literal> on the page.
	    Very little formatting is available.  There is no way to
	    select a font or proportional spacing.  The forced
	    simplicity of plain <acronym>ASCII</acronym> means that
	    text can be printed straight from the computer with little
	    or no encoding or translation.  The printed output
	    corresponds directly with what was sent.</para>

	  <para>Some inexpensive printers cannot print plain
	    <acronym>ASCII</acronym> text.  This makes them more
	    difficult to set up, but it is usually still
	    possible.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="print-pdls-postscript">
	<term>&postscript;</term>

	<listitem>
	  <para>&postscript; is almost the opposite of
	    <acronym>ASCII</acronym>.  Rather than simple text, a
	    &postscript; program is a set of instructions that draw
	    the final document.  Different fonts and graphics can be
	    used.  However, this power comes at a price.  The program
	    that draws the page must be written.  Usually this program
	    is generated by application software, so the process is
	    invisible to the user.</para>

	  <para>Inexpensive printers sometimes leave out &postscript;
	    compatibility as a cost-saving measure.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="print-pdls-pcl">
	<term><acronym>PCL</acronym> (Printer Command Language)</term>

	<listitem>
	  <para><acronym>PCL</acronym> is an extension of
	    <acronym>ASCII</acronym>, adding escape sequences for
	    formatting, font selection, and printing graphics.  Many
	    printers provide <acronym>PCL5</acronym> support.  Some
	    support the newer <acronym>PCL6</acronym> or
	    <acronym>PCLXL</acronym>.  These later versions are
	    supersets of <acronym>PCL5</acronym> and can provide
	    faster printing.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="print-pdls-host-based">
	<term>Host-Based</term>

	<listitem>
	  <para>Manufacturers can reduce the cost of a printer by
	    giving it a simple processor and very little memory.
	    These printers are not capable of printing plain text.
	    Instead, bitmaps of text and graphics are drawn by a
	    driver on the host computer and then sent to the printer.
	    These are called <emphasis>host-based</emphasis>
	    printers.</para>

	  <para>Communication between the driver and a host-based
	    printer is often through proprietary or undocumented
	    protocols, making them functional only on the most common
	    operating systems.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2 xml:id="print-pdls-table">
      <title>Converting &postscript; to Other
	<acronym>PDL</acronym>s</title>

      <para>Many applications from the Ports Collection and &os;
	utilities produce &postscript; output.  This table shows
	the utilities available to convert that into other common
	<acronym>PDL</acronym>s:</para>

      <table xml:id="print-pdls-ps-to-other-tbl" frame="none">
	<title>Output <acronym>PDL</acronym>s</title>

	<tgroup cols="3" align="left">
	  <thead>
	    <row>
	      <entry align="left">Output
		<acronym>PDL</acronym></entry>
	      <entry align="left">Generated By</entry>
	      <entry align="left">Notes</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><acronym>PCL</acronym> or
		<acronym>PCL5</acronym></entry>
	      <entry><package
		  role="port">print/ghostscript9-base</package></entry>
	      <entry><literal>-sDEVICE=ljet4</literal> for monochrome,
		<literal>-sDEVICE=cljet5</literal> for color</entry>
	    </row>

	    <row>
	      <entry><acronym>PCLXL</acronym> or
		<acronym>PCL6</acronym></entry>
	      <entry><package
		  role="port">print/ghostscript9-base</package></entry>
	      <entry><literal>-sDEVICE=pxlmono</literal> for
		monochrome, <literal>-sDEVICE=pxlcolor</literal> for
		color</entry>
	    </row>

	    <row>
	      <entry><acronym>ESC/P2</acronym></entry>
	      <entry><package
		  role="port">print/ghostscript9-base</package></entry>
	      <entry><literal>-sDEVICE=uniprint</literal></entry>
	    </row>

	    <row>
	      <entry><acronym>XQX</acronym></entry>
	      <entry><package
		  role="port">print/foo2zjs</package></entry>
	      <entry/>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </sect2>

    <sect2 xml:id="print-pdls-summary">
      <title>Summary</title>

      <para>For the easiest printing, choose a printer that supports
	&postscript;.  Printers that support <acronym>PCL</acronym>
	are the next preferred.  With
	<package role="port">print/ghostscript9-base</package>, these
	printers can be used as if they understood &postscript;
	natively.  Printers that support &postscript; or
	<acronym>PCL</acronym> directly almost always support direct
	printing of plain <acronym>ASCII</acronym> text files
	also.</para>

      <para>Line-based printers like typical inkjets usually do not
	support &postscript; or <acronym>PCL</acronym>.  They often
	can print plain <acronym>ASCII</acronym> text files.
	<package role="port">print/ghostscript9-base</package>
	supports the <acronym>PDL</acronym>s used by some of these
	printers.  However, printing an entire graphic-based page on
	these printers is often very slow due to the large amount of
	data to be transferred and printed.</para>

      <para>Host-based printers are often more difficult to set up.
	Some cannot be used at all because of proprietary
	<acronym>PDL</acronym>s.  Avoid these printers when
	possible.</para>

      <para>Descriptions of many <acronym>PDL</acronym>s can be found
	at <link
	  xlink:href="http://www.undocprint.org/formats/page_description_languages"></link>.
	The particular <acronym>PDL</acronym> used by various models
	of printers can be found at <link
	  xlink:href="http://www.openprinting.org/printers"></link>.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="printing-direct">
    <title>Direct Printing</title>

    <para>For occasional printing, files can be sent directly to a
      printer device without any setup.  For example, a file called
      <filename>sample.txt</filename> can be sent to a
      <acronym>USB</acronym> printer:</para>

    <screen>&prompt.root; <userinput>cp sample.txt /dev/unlpt0</userinput></screen>

    <para>Direct printing to network printers depends on the
      abilities of the printer, but most accept print jobs on port
      9100, and &man.nc.1; can be used with them.  To print the
      same file to a printer with the <acronym>DNS</acronym>
      hostname of <replaceable>netlaser</replaceable>:</para>

    <screen>&prompt.root; <userinput>nc <replaceable>netlaser</replaceable> 9100 &lt; sample.txt</userinput></screen>
  </sect1>

  <sect1 xml:id="printing-lpd">
    <title><acronym>LPD</acronym> (Line Printer Daemon)</title>

    <para>Printing a file in the background is called
      <emphasis>spooling</emphasis>.  A spooler allows the user to
      continue with other programs on the computer without waiting for
      the printer to slowly complete the print job.</para>

    <para>&os; includes a spooler called &man.lpd.8;.  Print jobs are
      submitted with &man.lpr.1;.</para>

    <sect2 xml:id="printing-lpd-setup">
      <title>Initial Setup</title>

      <para>A directory for storing print jobs is created, ownership
	is set, and the permissions are set to prevent other users
	from viewing the contents of those files:</para>

      <screen>&prompt.root; <userinput>mkdir -p /var/spool/lpd/lp</userinput>
&prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/lp</userinput>
&prompt.root; <userinput>chmod 770 /var/spool/lpd/lp</userinput></screen>

      <para>Printers are defined in
	<filename>/etc/printcap</filename>.  An entry for each printer
	includes details like a name, the port where it is attached,
	and various other settings.  Create
	<filename>/etc/printcap</filename> with these contents:</para>

      <programlisting>lp:\				<co xml:id="printing-lpd-co-name"/>
	:lp=/dev/unlpt0:\	<co xml:id="printing-lpd-co-device"/>
	:sh:\			<co xml:id="printing-lpd-co-header"/>
	:mx#0:\			<co xml:id="printing-lpd-co-mx"/>
	:sd=/var/spool/lpd/lp:\	<co xml:id="printing-lpd-co-sd"/>
	:lf=/var/log/lpd-errs:	<co xml:id="printing-lpd-co-lf"/></programlisting>

      <calloutlist>
	<callout arearefs="printing-lpd-co-name">
	  <para>The name of this printer.  &man.lpr.1; sends print
	    jobs to the <literal>lp</literal> printer unless another
	    printer is specified with <option>-P</option>, so the
	    default printer should be named
	    <literal>lp</literal>.</para>
	</callout>

	<callout arearefs="printing-lpd-co-device">
	  <para>The device where the printer is connected.  Replace
	    this line with the appropriate one for the connection type
	    shown here.</para>

	  <informaltable xml:id="printing-lpd-co-device-tbl">
	    <tgroup cols="2">
	      <thead>
		<row>
		  <entry>Connection Type</entry>
		  <entry>Device Entry in
		    <filename>/etc/printcap</filename></entry>
		</row>
	      </thead>

	      <tbody>
		<row>
		  <entry><acronym>USB</acronym></entry>
		  <entry><programlisting>:lp=/dev/unlpt0:\</programlisting>

		    <para>This is the
		      <emphasis>non-resetting</emphasis>
		      <acronym>USB</acronym> printer device.  If
		      problems are experienced, use
		      <filename>ulpt0</filename> instead, which resets
		      the <acronym>USB</acronym> port on each
		      use.</para></entry>
		</row>

		<row>
		  <entry>Parallel</entry>
		  <entry><programlisting>:lp=/dev/lpt0:\</programlisting></entry>
		</row>

		<row>
		  <entry>Network</entry>

		  <entry><para>For a printer supporting the
		    <acronym>LPD</acronym> protocol:</para>

		    <programlisting>:lp=:rm=<replaceable>network-printer-name</replaceable>:rp=raw:\</programlisting>

		    <para>For printers supporting port 9100
		      printing:</para>

		    <programlisting>:lp=9100@<replaceable>network-printer-name</replaceable>:\</programlisting>

		    <para>For both types, replace
		      <replaceable>network-printer-name</replaceable>
		      with the <acronym>DNS</acronym> host name of the
		      network printer.</para></entry>
		</row>

		<row>
		  <entry>Serial</entry>
		  <entry><programlisting>:lp=/dev/cuau0:br=9600:pa=none:\</programlisting>

		    <para>These values are for a typical serial
		      printer connected to a motherboard serial port.
		      The baud rate is 9600, and no parity is
		      used.</para></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</callout>

	<callout arearefs="printing-lpd-co-header">
	  <para>Suppress the printing of a header page at the start of
	    a print job.</para>
	</callout>

	<callout arearefs="printing-lpd-co-mx">
	  <para>Do not limit the maximum size of a print job.</para>
	</callout>

	<callout arearefs="printing-lpd-co-sd">
	  <para>The path to the spooling directory for this printer.
	    Each printer uses its own spooling directory.</para>
	</callout>

	<callout arearefs="printing-lpd-co-lf">
	  <para>The log file where errors on this printer will be
	    reported.</para>
	</callout>
      </calloutlist>

      <para>After creating <filename>/etc/printcap</filename>, use
	&man.chkprintcap.8; to test it for errors:</para>

      <screen>&prompt.root; <userinput>chkprintcap</userinput></screen>

      <para>Fix any reported problems before continuing.</para>

      <para>Enable &man.lpd.8; in
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>lpd_enable="YES"</programlisting>

      <para>Start the service:</para>

      <screen>&prompt.root; <userinput>service lpd start</userinput></screen>
    </sect2>

    <sect2 xml:id="printing-lpd-lpr">
      <title>Printing with &man.lpr.1;</title>

      <para>Documents are sent to the printer with
	<command>lpr</command>.  A file to be printed can be named on
	the command line or piped into <command>lpr</command>.  These
	two commands are equivalent, sending the contents of
	<filename>doc.txt</filename> to the default printer:</para>

      <screen>&prompt.user; <userinput>lpr doc.txt</userinput>
&prompt.user; <userinput>cat doc.txt | lpr</userinput></screen>

      <para>Printers can be selected with <option>-P</option>.  To
	print to a printer called
	<replaceable>laser</replaceable>:</para>

      <screen>&prompt.user; <userinput>lpr -Plaser doc.txt</userinput></screen>
    </sect2>

    <sect2 xml:id="printing-lpd-filters">
      <title>Filters</title>

      <para>The examples shown so far have sent the contents of a text
	file directly to the printer.  As long as the printer
	understands the content of those files, output will be printed
	correctly.</para>

      <para>Some printers are not capable of printing plain text, and
	the input file might not even be plain text.</para>

      <para><emphasis>Filters</emphasis> allow files to be
	translated or processed.  The typical use is to translate one
	type of input, like plain text, into a form that the printer
	can understand, like &postscript; or <acronym>PCL</acronym>.
	Filters can also be used to provide additional features, like
	adding page numbers or highlighting source code to make it
	easier to read.</para>

      <para>The filters discussed here are
	<emphasis>input filters</emphasis> or
	<emphasis>text filters</emphasis>.  These filters convert the
	incoming file into different forms.  Use &man.su.1; to become
	<systemitem class="username">root</systemitem> before
	creating the files.</para>

      <para>Filters are specified in
	<filename>/etc/printcap</filename> with the
	<literal>if=</literal> identifier.  To use
	<filename>/usr/local/libexec/lf2crlf</filename> as a filter,
	modify <filename>/etc/printcap</filename> like this:</para>

      <programlisting>lp:\
	:lp=/dev/unlpt0:\
	:sh:\
	:mx#0:\
	:sd=/var/spool/lpd/lp:\
	:if=/usr/local/libexec/lf2crlf:\   <co xml:id="printing-lpd-filters-co-if"/>
	:lf=/var/log/lpd-errs:</programlisting>

      <calloutlist>
	<callout arearefs="printing-lpd-filters-co-if">
	  <para><literal>if=</literal> identifies the
	    <emphasis>input filter</emphasis> that will be used on
	    incoming text.</para>
	</callout>
      </calloutlist>

      <tip xml:id="printing-lpd-filters-oneline">
	<para>The backslash <emphasis>line continuation</emphasis>
	  characters at the end of the lines in
	  <filename>printcap</filename> entries reveal that an entry
	  for a printer is really just one long line with entries
	  delimited by colon characters.  An earlier example can be
	  rewritten as a single less-readable line:</para>

	<programlisting>lp:lp=/dev/unlpt0:sh:mx#0:sd=/var/spool/lpd/lp:if=/usr/local/libexec/lf2crlf:lf=/var/log/lpd-errs:</programlisting>
      </tip>

      <sect3 xml:id="printing-lpd-filters-stairstep">
	<title>Preventing Stairstepping on Plain Text Printers</title>

	<para>Typical &os; text files contain only a single line feed
	  character at the end of each line.  These lines will
	  <quote>stairstep</quote> on a standard printer:</para>

	<programlisting>A printed file looks
                    like the steps of a staircase
                                                 scattered by the wind</programlisting>

	<para>A filter can convert the newline characters into
	  carriage returns and newlines.  The carriage returns make
	  the printer return to the left after each line.  Create
	  <filename>/usr/local/libexec/lf2crlf</filename> with these
	  contents:</para>

	<programlisting>#!/bin/sh
CR=$'\r'
/usr/bin/sed -e "s/$/${CR}/g"</programlisting>

	<para>Set the permissions and make it executable:</para>

	<screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/lf2crlf</userinput></screen>

	<para>Modify <filename>/etc/printcap</filename> to use the
	  new filter:</para>

	<programlisting>:if=/usr/local/libexec/lf2crlf:\</programlisting>

	<para>Test the filter by printing the same plain text file.
	  The carriage returns will cause each line to start at the
	  left side of the page.</para>
      </sect3>

      <sect3 xml:id="printing-lpd-filters-enscript">
	<title>Fancy Plain Text on &postscript; Printers with
	  <package>print/enscript</package></title>

	<para><acronym>GNU</acronym>
	  <application>Enscript</application> converts plain text
	  files into nicely-formatted &postscript; for printing on
	  &postscript; printers.  It adds page numbers, wraps long
	  lines, and provides numerous other features to make printed
	  text files easier to read.  Depending on the local paper
	  size, install either
	  <package role="port">print/enscript-letter</package> or
	  <package role="port">print/enscript-a4</package> from the
	  Ports Collection.</para>

	<para>Create <filename>/usr/local/libexec/enscript</filename>
	  with these contents:</para>

	<programlisting>#!/bin/sh
/usr/local/bin/enscript -o -</programlisting>

	<para>Set the permissions and make it executable:</para>

	<screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/enscript</userinput></screen>

	<para>Modify <filename>/etc/printcap</filename> to use the
	  new filter:</para>

	<programlisting>:if=/usr/local/libexec/enscript:\</programlisting>

	<para>Test the filter by printing a plain text file.</para>
      </sect3>

      <sect3 xml:id="printing-lpd-filters-ps2pcl">
	<title>Printing &postscript; to
	  <acronym>PCL</acronym> Printers</title>

	<para>Many programs produce &postscript; documents.
	  However, inexpensive printers often only understand plain
	  text or <acronym>PCL</acronym>.  This filter converts
	  &postscript; files to <acronym>PCL</acronym> before sending
	  them to the printer.</para>

	<para>Install the Ghostscript &postscript; interpreter,
	  <package role="port">print/ghostscript9-base</package>,
	  from the Ports Collection.</para>

	<para>Create <filename>/usr/local/libexec/ps2pcl</filename>
	  with these contents:</para>

	<programlisting>#!/bin/sh
/usr/local/bin/gs -dSAFER -dNOPAUSE -dBATCH -q -sDEVICE=ljet4 -sOutputFile=- -</programlisting>

	<para>Set the permissions and make it executable:</para>

	<screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/ps2pcl</userinput></screen>

	<para>&postscript; input sent to this script will be rendered
	  and converted to <acronym>PCL</acronym> before being sent on
	  to the printer.</para>

	<para>Modify <filename>/etc/printcap</filename> to use this
	  new input filter:</para>

	<programlisting>:if=/usr/local/libexec/ps2pcl:\</programlisting>

	<para>Test the filter by sending a small &postscript; program
	  to it:</para>

	<screen>&prompt.user; <userinput>printf "%%\!PS \n /Helvetica findfont 18 scalefont setfont \
72 432 moveto (PostScript printing successful.) show showpage \004" | lpr</userinput></screen>
      </sect3>

      <sect3 xml:id="printing-lpd-filters-smart">
	<title>Smart Filters</title>

	<para>A filter that detects the type of input and
	  automatically converts it to the correct format for the
	  printer can be very convenient.  The first two characters of
	  a &postscript; file are usually <literal>%!</literal>.  A
	  filter can detect those two characters.  &postscript; files
	  can be sent on to a &postscript; printer unchanged.  Text
	  files can be converted to &postscript; with
	  <application>Enscript</application> as shown earlier.
	  Create <filename>/usr/local/libexec/psif</filename> with
	  these contents:</para>

	<programlisting>#!/bin/sh
#
#  psif - Print PostScript or plain text on a PostScript printer
#
IFS="" read -r first_line
first_two_chars=`expr "$first_line" : '\(..\)'`

case "$first_two_chars" in
%!)
    # %! : PostScript job, print it.
    echo "$first_line" &amp;&amp; cat &amp;&amp; exit 0
    exit 2
    ;;
*)
    # otherwise, format with enscript
    ( echo "$first_line"; cat ) | /usr/local/bin/enscript -o - &amp;&amp; exit 0
    exit 2
    ;;
esac</programlisting>

	<para>Set the permissions and make it executable:</para>

	<screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/psif</userinput></screen>

	<para>Modify <filename>/etc/printcap</filename> to use this
	  new input filter:</para>

	<programlisting>:if=/usr/local/libexec/psif:\</programlisting>

	<para>Test the filter by printing &postscript; and plain text
	  files.</para>
      </sect3>

      <sect3 xml:id="printing-lpd-filters-othersmart">
	<title>Other Smart Filters</title>

	<para>Writing a filter that detects many different types of
	  input and formats them correctly is challenging.
	  <package role="port">print/apsfilter</package> from the
	  Ports Collection is a smart <quote>magic</quote> filter that
	  detects dozens of file types and automatically converts them
	  to the <acronym>PDL</acronym> understood by the printer.
	  See <link xlink:href="http://www.apsfilter.org"></link> for
	  more details.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="printing-lpd-queues">
      <title>Multiple Queues</title>

      <para>The entries in <filename>/etc/printcap</filename> are
	really definitions of <emphasis>queues</emphasis>.  There can
	be more than one queue for a single printer.  When combined
	with filters, multiple queues provide users more control over
	how their jobs are printed.</para>

      <para>As an example, consider a networked &postscript; laser
	printer in an office.  Most users want to print plain text,
	but a few advanced users want to be able to print &postscript;
	files directly.  Two entries can be created for the same
	printer in <filename>/etc/printcap</filename>:</para>

      <programlisting>textprinter:\
	:lp=9100@officelaser:\
	:sh:\
	:mx#0:\
	:sd=/var/spool/lpd/textprinter:\
	:if=/usr/local/libexec/enscript:\
	:lf=/var/log/lpd-errs:

psprinter:\
	:lp=9100@officelaser:\
	:sh:\
	:mx#0:\
	:sd=/var/spool/lpd/psprinter:\
	:lf=/var/log/lpd-errs:</programlisting>

      <para>Documents sent to <literal>textprinter</literal> will be
	formatted by the
	<filename>/usr/local/libexec/enscript</filename> filter shown
	in an earlier example.  Advanced users can print &postscript;
	files on <literal>psprinter</literal>, where no filtering is
	done.</para>

      <para>This multiple queue technique can be used to provide
	direct access to all kinds of printer features.  A printer
	with a duplexer could use two queues, one for ordinary
	single-sided printing, and one with a filter that sends the
	command sequence to enable double-sided printing and then
	sends the incoming file.</para>
    </sect2>

    <sect2 xml:id="printing-lpd-monitor">
      <title>Monitoring and Controlling Printing</title>

      <para>Several utilities are available to monitor print jobs and
	check and control printer operation.</para>

      <sect3 xml:id="printing-lpd-monitor-lpq">
	<title>&man.lpq.1;</title>

	<para>&man.lpq.1; shows the status of a user's print
	  jobs.  Print jobs from other users are not shown.</para>

	<para>Show the current user's pending jobs on a single
	  printer:</para>

	<screen>&prompt.user; <userinput>lpq -P<replaceable>lp</replaceable></userinput>
Rank   Owner      Job  Files                                 Total Size
1st    jsmith     0    (standard input)                      12792 bytes</screen>

	<para>Show the current user's pending jobs on all
	  printers:</para>

	<screen>&prompt.user; <userinput>lpq -a</userinput>
lp:
Rank   Owner      Job  Files                                 Total Size
1st    jsmith     1    (standard input)                      27320 bytes

laser:
Rank   Owner      Job  Files                                 Total Size
1st    jsmith     287  (standard input)                      22443 bytes</screen>
      </sect3>

      <sect3 xml:id="printing-lpd-monitor-lprm">
	<title>&man.lprm.1;</title>

	<para>&man.lprm.1; is used to remove print jobs.  Normal users
	  are only allowed to remove their own jobs.
	  <systemitem class="username">root</systemitem> can remove
	  any or all jobs.</para>

	<para>Remove all pending jobs from a printer:</para>

	<screen>&prompt.root; <userinput>lprm -P<replaceable>lp</replaceable> -</userinput>
dfA002smithy dequeued
cfA002smithy dequeued
dfA003smithy dequeued
cfA003smithy dequeued
dfA004smithy dequeued
cfA004smithy dequeued</screen>

	<para>Remove a single job from a
	  printer.  &man.lpq.1; is used to find the job number.</para>

	<screen>&prompt.user; <userinput>lpq</userinput>
Rank   Owner      Job  Files                                 Total Size
1st    jsmith     5    (standard input)                      12188 bytes
&prompt.user; <userinput>lprm -P<replaceable>lp</replaceable> <replaceable>5</replaceable></userinput>
dfA005smithy dequeued
cfA005smithy dequeued</screen>
      </sect3>

      <sect3 xml:id="printing-lpd-monitor-lpc">
	<title>&man.lpc.8;</title>

	<para>&man.lpc.8; is used to check and modify printer status.
	  <literal>lpc</literal> is followed by a command and an
	  optional printer name.  <literal>all</literal> can be used
	  instead of a specific printer name, and the command will be
	  applied to all printers.  Normal users can view status with
	  &man.lpc.8;.  Only
	  <systemitem class="username">root</systemitem> can use
	  commands which modify printer status.</para>

	<para>Show the status of all printers:</para>

	<screen>&prompt.user; <userinput>lpc status all</userinput>
lp:
	queuing is enabled
	printing is enabled
	1 entry in spool area
	printer idle
laser:
	queuing is enabled
	printing is enabled
	1 entry in spool area
	waiting for laser to come up</screen>

	<para>Prevent a printer from accepting new jobs, then begin
	  accepting new jobs again:</para>

	<screen>&prompt.root; <userinput>lpc disable <replaceable>lp</replaceable></userinput>
lp:
	queuing disabled
&prompt.root; <userinput>lpc enable <replaceable>lp</replaceable></userinput>
lp:
	queuing enabled</screen>

	<para>Stop printing, but continue to accept new jobs.  Then
	  begin printing again:</para>

	<screen>&prompt.root; <userinput>lpc stop <replaceable>lp</replaceable></userinput>
lp:
	printing disabled
&prompt.root; <userinput>lpc start <replaceable>lp</replaceable></userinput>
lp:
	printing enabled
	daemon started</screen>

	<para>Restart a printer after some error condition:</para>

	<screen>&prompt.root; <userinput>lpc restart <replaceable>lp</replaceable></userinput>
lp:
	no daemon to abort
	printing enabled
	daemon restarted</screen>

	<para>Turn the print queue off and disable printing, with a
	  message to explain the problem to users:</para>

	<screen>&prompt.root; <userinput>lpc down <replaceable>lp</replaceable> Repair parts will arrive on Monday</userinput>
lp:
	printer and queuing disabled
	status message is now: Repair parts will arrive on Monday</screen>

	<para>Re-enable a printer that is down:</para>

	<screen>&prompt.root; <userinput>lpc up <replaceable>lp</replaceable></userinput>
lp:
	printing enabled
	daemon started</screen>

	<para>See &man.lpc.8; for more commands and options.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="printing-lpd-shared">
      <title>Shared Printers</title>

      <para>Printers are often shared by multiple users in businesses
	and schools.  Additional features are provided to make sharing
	printers more convenient.</para>

      <sect3 xml:id="printing-shared-aliases">
	<title>Aliases</title>

	<para>The printer name is set in the first line of the
	  entry in <filename>/etc/printcap</filename>.  Additional
	  names, or <emphasis>aliases</emphasis>, can be added after
	  that name.  Aliases are separated from the name and each
	  other by vertical bars:</para>

	<programlisting>lp|<replaceable>repairsprinter</replaceable>|<replaceable>salesprinter</replaceable>:\</programlisting>

	<para>Aliases can be used in place of the printer name.  For
	  example, users in the Sales department print to their
	  printer with</para>

	<screen>&prompt.user; <userinput>lpr -P<replaceable>salesprinter</replaceable> <replaceable>sales-report.txt</replaceable></userinput></screen>

	<para>Users in the Repairs department print to
	  <emphasis>their</emphasis> printer with</para>

	<screen>&prompt.user; <userinput>lpr -P<replaceable>repairsprinter</replaceable> <replaceable>repairs-report.txt</replaceable></userinput></screen>

	<para>All of the documents print on that single printer.  When
	  the Sales department grows enough to need their own printer,
	  the alias can be removed from the shared printer entry and
	  used as the name of a new printer.  Users in both
	  departments continue to use the same commands, but the Sales
	  documents are sent to the new printer.</para>
      </sect3>

      <sect3 xml:id="printing-shared-headers">
	<title>Header Pages</title>

	<para>It can be difficult for users to locate their documents
	  in the stack of pages produced by a busy shared printer.
	  <emphasis>Header pages</emphasis> were created to solve this
	  problem.  A header page with the user name and document name
	  is printed before each print job.  These pages are also
	  sometimes called <emphasis>banner</emphasis> or
	  <emphasis>separator</emphasis> pages.</para>

	<para>Enabling header pages differs depending on whether the
	  printer is connected directly to the computer with a
	  <acronym>USB</acronym>, parallel, or serial cable, or
	  is connected remotely over a network.</para>

	<para>Header pages on directly-connected printers are enabled
	  by removing the <literal>:sh:\</literal> (Suppress Header)
	  line from the entry in <filename>/etc/printcap</filename>.
	  These header pages only use line feed characters for new
	  lines.  Some printers will need the
	  <filename>/usr/share/examples/printing/hpif</filename>
	  filter to prevent stairstepped text.  The filter configures
	  <acronym>PCL</acronym> printers to print both carriage
	  returns and line feeds when a line feed is received.</para>

	<para>Header pages for network printers must be configured on
	  the printer itself.  Header page entries in
	  <filename>/etc/printcap</filename> are ignored.  Settings
	  are usually available from the printer front panel or a
	  configuration web page accessible with a web browser.</para>
      </sect3>
      <!-- conversion filters?,
	restricting printer usage?, accounting? -->
    </sect2>

    <sect2 xml:id="printing-lpd-references">
      <title>References</title>

      <para>Example files: <filename
	  role="directory">/usr/share/examples/printing/</filename>.</para>

      <para>The <emphasis>4.3BSD Line Printer Spooler
	  Manual</emphasis>,
	<filename>/usr/share/doc/smm/07.lpd/paper.ascii.gz</filename>.</para>

      <para>Manual pages: &man.printcap.5;, &man.lpd.8;, &man.lpr.1;,
	&man.lpc.8;, &man.lprm.1;, &man.lpq.1;.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="printing-other">
    <title>Other Printing Systems</title>

    <para>Several other printing systems are available in
      addition to the built-in &man.lpd.8;.  These systems
      offer support for other protocols or additional features.</para>

    <sect2 xml:id="printing-other-cups">
      <title><acronym>CUPS</acronym> (Common &unix; Printing
	System)</title>

      <para><acronym>CUPS</acronym> is a popular printing system
	available on many operating systems.  Using
	<acronym>CUPS</acronym> on &os; is documented in a separate
	article:<link xlink:href="&url.articles.cups;"></link></para>
    </sect2>

    <sect2 xml:id="printing-other-hplip">
      <title>HPLIP</title>

      <para>Hewlett Packard provides a printing system that supports
	many of their inkjet and laser printers.  The port is
	<package role="port">print/hplip</package>.  The main web page
	is at <link
	  xlink:href="http://hplipopensource.com/hplip-web/index.html"></link>.
	The port handles all the installation details on &os;.
	Configuration information is shown at <link
	  xlink:href="http://hplipopensource.com/hplip-web/install/manual/hp_setup.html"></link>.</para>
    </sect2>

    <sect2 xml:id="printing-other-lprng">
      <title>LPRng</title>

      <para><application>LPRng</application> was developed as an
	enhanced alternative to &man.lpd.8;.  The port is
	<package role="port">sysutils/LPRng</package>.  For details
	and documentation, see
	<link xlink:href="http://www.lprng.com/"></link>.</para>
    </sect2>
  </sect1>
</chapter>