=head1	NAME

yanolc - Yet ANOther Lprng/lpr Client

=head1	SYNOPSIS

  klpr     [<options>] [<file(s)>]
  klpq     [<options>] [<job(s)>]
  klprm    [<options> [<job(s)>]
  klpc     [<klpc-arguments>]
  klpinfo  [<options>]
  snmpyalc [<options>]

=head1	DESCRIPTION

The yanolc package provides clones for the lpr, lpq, lprm and lpc programs
found in LPRng and other print systems. Additionally there are two
programs to retrieve printer status information using SNMP.

This package is intended for use on systems without the complete set
of lpr/lpq/lprm/lpc, i.e. Windows.

=head1	KLPR/KLPQ/KLPRM OPTIONS

=over	6

=item	B<-P> I<printer>

specifies the printer to use (klpr, klpq, klprm, klpinfo, snmpyalc).

Long option: B<--printer=>I<printer>

=item	B<-H> I<server>

specifies the print server to contact (klpr, klpq, klprm, klpinfo, snmpyalc)).

Alternative option: B<-S> I<server>

Long option: B<--server=>I<server>

=item	B<-U> I<user>

specifies a user name for the operation (klpr, klprm).

Long option: B<--username=>I<user>

=item	B<-C> I<class>

specifies the print job class (klpr). I have never used this.

Long option: B<--class=>I<class>

=item	B<-C> I<community>

specifies the SNMP community (klpinfo, snmpyalc).

Long option: B<--community=>I<community>

=item	I<File type> (klpr)

The print server can run conversion filters automatically to convert
input to printable output.

For security reasons sites may decide to disable automatic filtering and
require users to produce printable output theirselves. I strongly recommend
to do so.

I suggest to send only literally/binary files which do not require any
filtering by the print system.

For most of the file types I have no idea about the meaning. The lpr
program simply passes this information to the server.
For completeness I list the file types here:

=over 12

=item	B<-l>

Binary (literally) file, print as is without any filtering.

Long option: B<--literally>

=item	B<-c>

Cifplot output file.

Long option: B<--cifplot>

=item	B<-d>

DVI file from TeX/LaTeX.

Long option: B<--dvi>

=item	B<-g>

Plot file.

Long option: B<--plot>

=item	B<-n>

Device independent troff file.

Long option: B<--dvi-troff>

=item	B<-t>

Troff file.

Long option: B<--troff>

=item	B<-r>

Raster file.

Long option: B<--raster>

=back

=item	B<-e>

Enable header printing (klpr).
This option is disabled by default.

Long option: B<--header=>I<boolean>

=item	B<-j> I<width>

specifies the indent width in columns (klpr).

Long option: B<--indent=>I<width>

=item	B<-J> I<name>

specifiest the job name for printing (klpr).

Long option: B<--jobname=>I<name>

=item	B<-K> I<number>

specifies the number of copies (klpr).

Alternative option: B<-#> I<copies>

Long option: B<--copies=>I<copies>

=item	B<-m> I<address>

specifies a mail address for notifications (klpr).

Long option: B<--mail=>I<address>

=item	B<-T> I<title>

specifies the job title (klpr).

Long option: B<--jobtitle=>I<title>

=item	B<-T> I<snmp-type>

chooses the SNMP type name as specified in the snmpyalc.cfg
file (snmpyalc).

=item	B<-w> I<width>

specifies the output width for text in columns (klpr).

Long option: B<--width=>I<width>

=item	B<-o> I<options>

passes the options to the filters (klpr).

=item	B<-V>

sets verbose mode (klpr).

Long option: B<--verbose=>I<boolean>

=item	B<-V> I<protocol>

specifies the SNMP protocol version (klpinfo, snmpyalc),
can be ``1'', ``2'', ``2c'', ``2p'' or ``3''.

Long option: B<--version=>I<protocol>


=item	B<-Q> I<queue>

is not implemented here. On LPRng systems this option can be used to
name the original queue (klpr).

Long option: B<--original-queue=>I<queue>

=item	B<-R> I<user>

is not implemented here. On LPRng systems this option can be used
to specify the user who is charged for the print job (klpr).

Long option: B<--bill=>I<user>

=item	B<-a>

shows information about all queues (klpq) or
removes all accessable print jobs (klprm).

Long option: B<--all>

=item	B<-s>

generates a short status message only (klpq).

Long option: B<--status>

=item	B<-s>

runs silently (klpinfo, snmpyalc).

Long option: B<--silently>

=item	B<-l>

sets long output format (klpq, klpinfo).

Long option: B<--long-output>

=item	B<-L>

sets very long output format (klpq).

Long option: B<--very-long-output>

=item	B<-f>

removes filter status lines (klpq).

Long option: B<--remove-filter-status>

=item	B<-f>

forces output (klpinfo, snmpyalc).
If no status can be obtained klpinfo print ``-''.

Long option: B<--force>


=item	B<-d>

removes ``done'' jobs from output list (klpq).

=item	B<-t> I<seconds>

runs periodically (klpq).

Long option: B<--repeat=>I<seconds>

=item	B<-i>

ignores the exit code and enforces exit status 0 (klpinfo, snmpyalc).

Long option: B<--ignore-exit-code>


=back

=head1	KLPC COMMAND LINE ARGUMENTS

=item	B<-H> I<server>

chooses the server to connect to.

=item	B<klpc start> I<queue>

starts a print queue.

=item	B<klpc stop> I<queue>

stops a print queue.

=item	B<klpc enable> I<queue>

enables spooling to a queue.

=item	B<klpc disable> I<queue>

disables spooling to a queue.

=item	B<klpc abort> I<queue>

aborts (kills) the current active job in the queue.

=item	B<klpc kill> I<queue>

restarts a queue.

=item	B<klpc topq> I<queue> I<job>

moves the job to the top of queue (next job printed).

=item	B<klpc status> I<queue>

displays daemon and queue status.

=item	B<klpc hold> I<queue> I<job(s)>

holds the specified jobs (keeps them in the queue but does not print
them).

=item	B<klpc holdall> I<queue>

holds all jobs in the queue.

=item	B<klpc release> I<printer> I<job(s)>

releases the jobs (allow processing).

=item	B<klpc move> I<job(s)> I<queue>

moves the jobs to another queue.

=item	B<klpc active> I<queue>

checks a print queue response.

=item	B<klpc lpd> I<queue>

prints the PID of the LPRng/LPD process managing the queue.

=over	6

=back

=head1	RETURN VALUE

The programs return exit status code 0 on success, any other value indicates
an error.

=head1	ENVIRONMENT AND PREFERENCES

=head2	Default printer

If no queue is specified on the command line the default printer
information is searched in the following places:

=over	6

=item	B</yanolc/default-printer>

command line preference.

=item	B<NGPRINTER>

environment variable.

=item	B<NPRINTER>

environment variable.

=item	B<LPDEST>

environment variable.

=item	B<PRINTER>

environment variable.

=item	B</yanolc/default-printer>

user-specific preference.

=item	B</default-printer>

entry in the HKCU\Software\DKrause\Yanolc registry key.

=item	B</yanolc/default-printer>

system preference.

=item	B<default-printer>

entry in the HKLM\Software\DKrause\Yanolc registry key.

=item	B<first alias>

found in the configuration file.

=item	B<first queue>

found in the configuration file.

=back

=head2	Default host

If the print queue name contains ``@'' or ``%'' the host name is obtained
from the print queue. If it doesn't yanolc attempts to resolve the queue
name as an alias.

If no print host name was found, information is searched in the following
places:

=over	6

=item	B<PRINTHOST>

environment variable.

=item	B</yanolc/print-host>

user preference.

=item	B</print-host>

entry in the HKCU\Software\DKrause\Yanolc registry key.

=item	B</yanolc/print-host>

system preference.

=item	B</print-host>

entry in the HKLM\Software\DKrause\Yanolc registry key.

=item	B<first host>

listed in the configuration file.

=back

=head1	FILES

There are two configuration files, yanolc.cfg (used by all program from
the yanolc package) and snmpyalc.cfg (used by snmpyalc only).
The files are found in ${sysconfdir}/yanolc (i.e. /etc/yanolc or
/usr/local/etc/yanolc) on UNIX/Linux or in %WINDIR%\Yanolc on Windows.

=head2	yanolc.cfg

The yanolc.cfg file consists of a ``[hosts]'', ``[devices]'' and
``[aliases]'' section.

The hosts section consists of a list of hosts descriptions.

Each host description is introduced by the host name standing
alone of a line.

The remaining lines in a host description are key/value pairs, key
and value are separated by ``=''.

The following key can be used:

=over	6

=item	type

print system type, one from ``lprng'' (LPRng print server), ``bsd''
(BSD print server) or ``raw'' (direct TCP/IP connection).

=item	xusers

lists usernames which are allowed to use the ``-U'' option to switch to
another user name. The names are separated by spaces.

=item	timeout.lpr

specifies the timeout in seconds for lpr requests.

=item	timeout.lpq

specifes the timeout in seconds for lpq requests.

=item	timeout.lpc

specifies the timeout in seconds for lpc requests.

=item	timeout.lprm

specifies the timeout in seconds for lprm requests.

=back

The devices section consists of a list of device descriptions.

Each device description is introduced by a queue name 
(queue@host) standing alone on a line.

The remaining lines are key/value pairs, key and value are separated
by ``=''. The keys are the same as in the hosts section.

The aliases section contains key/value pairs, key and value are separated
by ``=''. The key is a short name (i.e. ``pr1''), the value is a
full print queue name (queue@host) which should be configured in the
devices section.

=head2	snmpyalc.cfg

The snmpyalc.cfg file lists SNMP device types, each type is specified
in one section.
The section is started by the type name in square brackets.
The section lists the OIDs to inspect (OID must start in column 0)
and applies attributes (written indented).

The following attributes can be used:

=over	6

=item	B<type =>I<type>

specifies the data type stored in the OID, either ``display'' (OID
is of type ASN_OCTET_STRING, the value can be displayed directly),
``boolean'' (the OIDs type is ASN_INTEGER, ASN_COUNTER, ASN_GAUGE or
ASN_TIMETICKS, the boolean value is true if the OID value is not 0)
or ``iboolean'' (OID type is ASN_INTEGER, ASN_COUNTER, ASN_GAUGE or
ASN_TIMETICKS, the boolean value is if the OID value is 0).

=item	B<text=>I<text>

specifies the text to be shown instead of the OIDs value.
This allows to convert boolean or iboolean OIDs values to text readable
by the user.

=back

=head1	SEE ALSO

http://dktools.sourceforge.net/yanolc.html

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2010, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

